AWS S3 binding spec
- Component format
  - Warning
Spec metadata fields
Binding support
Related links

AWS S3 binding spec

Detailed documentation on the AWS S3 binding component

Component format

To setup AWS S3 binding create a component of type bindings.aws.s3. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.aws.s3
  version: v1
  metadata:
  - name: bucket
    value: mybucket
  - name: region
    value: us-west-2
  - name: endpoint
    value: s3-us-west-2.amazonaws.com
  - name: accessKey
    value: *****************
  - name: secretKey
    value: *****************
  - name: sessionToken
    value: mysession
  - name: decodeBase64
    value: <bool>
  - name: encodeBase64
    value: <bool>
  - name: forcePathStyle
    value: <bool>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
bucket	Y	Output	The name of the S3 bucket to write to	`“bucket”`
region	Y	Output	The specific AWS region	`“us-east-1”`
endpoint	N	Output	The specific AWS endpoint	`“s3-us-east-1.amazonaws.com”`
accessKey	Y	Output	The AWS Access Key to access this resource	`“key”`
secretKey	Y	Output	The AWS Secret Access Key to access this resource	`“secretAccessKey”`
sessionToken	N	Output	The AWS session token to use	`“sessionToken”`
forcePathStyle	N	Output	Currently Amazon S3 SDK supports virtual hosted-style and path-style access. `true` is path-style format like `https://<endpoint>/<your bucket>/<key>`. `false` is hosted-style format like `https://<your bucket>.<endpoint>/<key>`. Defaults to `false`	`true`, `false`
decodeBase64	N	Output	Configuration to decode base64 file content before saving to bucket storage. (In case of saving a file with binary content). `true` is the only allowed positive value. Other positive variations like `“True”, “1”` are not acceptable. Defaults to `false`	`true`, `false`
encodeBase64	N	Output	Configuration to encode base64 file content before return the content. (In case of opening a file with binary content). `true` is the only allowed positive value. Other positive variations like `“True”, “1”` are not acceptable. Defaults to `false`	`true`, `false`

Binding support

This component supports output binding with the following operations:

create : Create file
get : Get file
delete : Delete file
list: List file

Create file

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

Note: by default, a random UUID is generated. See below for Metadata support to set the name

{
  "operation": "create",
  "data": "YOUR_CONTENT"
}

Examples

Save text to a random generated UUID file

Windows
Linux

On Windows, utilize cmd prompt (PowerShell has different escaping mechanism)

curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "create", "data": "Hello World" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

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

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

Save a file to a object

To upload a file, encode it as Base64 and let the Binding know to deserialize it:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.aws.s3
  version: v1
  metadata:
  - name: bucket
    value: mybucket
  - name: region
    value: us-west-2
  - name: endpoint
    value: s3-us-west-2.amazonaws.com
  - name: accessKey
    value: *****************
  - name: secretKey
    value: *****************
  - name: sessionToken
    value: mysession
  - name: decodeBase64
    value: <bool>
  - name: forcePathStyle
    value: <bool>

Then you can upload it as you would normally:

Windows
Linux

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

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

Response

The response body will contain the following JSON:

{
    "location":"https://<your bucket>.s3.<your region>.amazonaws.com/<key>",
    "versionID":"<version ID if Bucket Versioning is enabled"
}

Get object

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

{
  "operation": "get",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

The metadata parameters are:

key - the name of the object

Example

Windows
Linux

curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response body contains the value stored in the object.

Delete object

To perform a delete object operation, invoke the AWS S3 binding with a POST method and the following JSON body:

{
  "operation": "delete",
  "metadata": {
    "key": "my-test-file.txt"
  }
}

The metadata parameters are:

key - the name of the object

Examples

Delete object

Windows
Linux

curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

An HTTP 204 (No Content) and empty body will be retuned if successful.

List objects

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

{
  "operation": "list",
  "data": {
    "maxResults": 10,
    "prefix": "file",
    "marker": "hvlcCQFSOD5TD",
    "delimiter": "i0FvxAn2EOEL6"
  }
}

The data parameters are:

maxResults - (optional) sets the maximum number of keys returned in the response. By default the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
prefix - (optional) limits the response to keys that begin with the specified prefix.
marker - (optional) marker is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this specified key. Marker can be any key in the bucket. The marker value may then be used in a subsequent call to request the next set of list items.
delimiter - (optional) A delimiter is a character you use to group keys.

Response

The response body contains the list of found objects.

The list of objects will be returned as JSON array in the following form:

{
    "CommonPrefixes": null,
    "Contents": [
        {
            "ETag": "\"7e94cc9b0f5226557b05a7c2565dd09f\"",
            "Key": "hpNdFUxruNuwm",
            "LastModified": "2021-08-16T06:44:14Z",
            "Owner": {
                "DisplayName": "owner name",
                "ID": "owner id"
            },
            "Size": 6916,
            "StorageClass": "STANDARD"
        }
    ],
    "Delimiter": "",
    "EncodingType": null,
    "IsTruncated": true,
    "Marker": "hvlcCQFSOD5TD",
    "MaxKeys": 1,
    "Name": "mybucketdapr",
    "NextMarker": "hzaUPWjmvyi9W",
    "Prefix": ""
}

Last modified February 18, 2022: Update setup-jetstream.md (#2200) (428d8c2)

AWS S3

AWS S3 binding spec

Component format

Warning

Spec metadata fields

Binding support

Create file

Examples

Save text to a random generated UUID file

Save text to a specific file

Save a file to a object

Response

Get object

Example

Response

Delete object

Examples

Delete object

Response

List objects

Response

Related links