SFTP binding spec

Detailed documentation on the Secure File Transfer Protocol (SFTP) binding component

Component format

To set up the SFTP binding, create a component of type bindings.sftp. See [this guide]({{ ref bindings-overview.md }}) on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.sftp
  version: v1
  metadata:
  - name: rootPath
    value: "<string>"
  - name: address
    value: "<string>"
  - name: username
    value: "<string>"
  - name: password
    value: "*****************"
  - name: privateKey
    value: "*****************"
  - name: privateKeyPassphrase
    value: "*****************"
  - name: hostPublicKey
    value: "*****************"
  - name: knownHostsFile
    value: "<string>"
  - name: insecureIgnoreHostKey
    value: "<bool>"

Spec metadata fields

Field Required Binding support Details Example
rootPath Y Output Root path for default working directory "/path"
address Y Output Address of SFTP server "localhost:22"
username Y Output Username for authentication "username"
password N Output Password for username/password authentication "password"
privateKey N Output Private key for public key authentication 
"|-
—–BEGIN OPENSSH PRIVATE KEY—–
*****************
—–END OPENSSH PRIVATE KEY—–"
privateKeyPassphrase N Output Private key passphrase for public key authentication "passphrase"
hostPublicKey N Output Host public key for host validation "ecdsa-sha2-nistp256 *** root@openssh-server"
knownHostsFile N Output Known hosts file for host validation "/path/file"
insecureIgnoreHostKey N Output Allows to skip host validation. Defaults to "false" "true", "false"

Binding support

This component supports output binding with the following operations:

Create file

To perform a create file operation, invoke the SFTP binding with a POST method and the following JSON body:

{
  "operation": "create",
  "data": "<YOUR_BASE_64_CONTENT>",
  "metadata": {
    "fileName": "<filename>",
  }
}

Example


curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"fileName\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>


curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "fileName": "my-test-file.jpg" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response body contains the following JSON:

{
   "fileName": "<filename>"
}

Get file

To perform a get file operation, invoke the SFTP binding with a POST method and the following JSON body:

{
  "operation": "get",
  "metadata": {
    "fileName": "<filename>"
  }
}

Example


curl -d '{ \"operation\": \"get\", \"metadata\": { \"fileName\": \"filename\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>


curl -d '{ "operation": "get", "metadata": { "fileName": "filename" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response body contains the value stored in the file.

List files

To perform a list files operation, invoke the SFTP binding with a POST method and the following JSON body:

{
  "operation": "list"
}

If you only want to list the files beneath a particular directory below the rootPath, specify the relative directory name as the fileName in the metadata.

{
  "operation": "list",
  "metadata": {
    "fileName": "my/cool/directory"
  }
}

Example


curl -d '{ \"operation\": \"list\", \"metadata\": { \"fileName\": \"my/cool/directory\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>


curl -d '{ "operation": "list", "metadata": { "fileName": "my/cool/directory" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response is a JSON array of file names.

Delete file

To perform a delete file operation, invoke the SFTP binding with a POST method and the following JSON body:

{
  "operation": "delete",
  "metadata": {
    "fileName": "myfile"
  }
}

Example


curl -d '{ \"operation\": \"delete\", \"metadata\": { \"fileName\": \"myfile\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>


curl -d '{ "operation": "delete", "metadata": { "fileName": "myfile" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

An HTTP 204 (No Content) and empty body is returned if successful.


Last modified November 20, 2024: Apply suggestions from code review (87a350e0)