AWS DynamoDB

Detailed information on the AWS DynamoDB state store component

Component format

To setup a DynamoDB state store create a component of type state.aws.dynamodb. See this guide on how to create and apply a state store configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: state.aws.dynamodb
  7.   version: v1
  8.   metadata:
  9.   - name: table
  10.     value: "Contracts"
  11.   - name: accessKey
  12.     value: "AKIAIOSFODNN7EXAMPLE" # Optional
  13.   - name: secretKey
  14.     value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" # Optional
  15.   - name: endpoint
  16.     value: "http://localhost:8080" # Optional
  17.   - name: region
  18.     value: "eu-west-1" # Optional
  19.   - name: sessionToken
  20.     value: "myTOKEN" # Optional
  21.   - name: ttlAttributeName
  22.     value: "expiresAt" # Optional
  23.   - name: partitionKey
  24.     value: "ContractID" # Optional

Warning

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

Primary Key

In order to use DynamoDB as a Dapr state store, the table must have a primary key named key. See the section Partition Keys for an option to change this behavior.

Spec metadata fields

FieldRequiredDetailsExample
tableYname of the DynamoDB table to use“Contracts”
accessKeyNID of the AWS account with appropriate permissions to SNS and SQS. Can be secretKeyRef to use a secret reference“AKIAIOSFODNN7EXAMPLE”
secretKeyNSecret for the AWS user. Can be secretKeyRef to use a secret reference“wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY”
regionNThe AWS region to the instance. See this page for valid regions: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html. Ensure that DynamoDB are available in that region.“us-east-1”
endpointNAWS endpoint for the component to use. Only used for local development. The endpoint is unncessary when running against production AWS“http://localhost:4566“
sessionTokenNAWS session token to use. A session token is only required if you are using temporary security credentials.“TOKEN”
ttlAttributeNameNThe table attribute name which should be used for TTL.“expiresAt”
partitionKeyNThe table primary key or partition key attribute name. This field is used to replace the default primary key attribute name “key”. See the section Partition Keys.“ContractID”

Important

When running the Dapr sidecar (daprd) with your application on EKS (AWS Kubernetes), if you’re using a node/pod that has already been attached to an IAM policy defining access to AWS resources, you must not provide AWS access-key, secret-key, and tokens in the definition of the component spec you’re using.

Setup AWS DynamoDB

See Authenticating to AWS for information about authentication-related attributes

Time to live (TTL)

In order to use DynamoDB TTL feature, you must enable TTL on your table and define the attribute name. The attribute name must be defined in the ttlAttributeName field. See official AWS docs.

Partition Keys

By default, the DynamoDB state store component uses the table attribute name key as primary/partition key in the DynamoDB table. This can be overridden by specifying a metadata field in the component configuration with a key of partitionKey and a value of the desired attribute name.

To learn more about DynamoDB primary/partition keys, read the AWS DynamoDB Developer Guide.

The following statestore.yaml file shows how to configure the DynamoDB state store component to use the partition key attribute name of ContractID:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: statestore
  5. spec:
  6.   type: state.aws.dynamodb
  7.   version: v1
  8.   metadata:
  9.   - name: table
  10.     value: "Contracts"
  11.   - name: partitionKey
  12.     value: "ContractID"

The above component specification assumes the following DynamoDB Table Layout:

  1. {
  2.     "Table": {
  3.         "AttributeDefinitions": [
  4.             {
  5.                 "AttributeName": "ContractID",
  6.                 "AttributeType": "S"
  7.             }
  8.         ],
  9.         "TableName": "Contracts",
  10.         "KeySchema": [
  11.             {
  12.                 "AttributeName": "ContractID",
  13.                 "KeyType": "HASH"
  14.             }
  15.         ],
  16. }

The following operation passes "A12345" as the value for key, and based on the component specification provided above, the Dapr runtime will replace the key attribute name with ContractID as the Partition/Primary Key sent to DynamoDB:

  1. $ dapr run --app-id contractsprocessing --app-port ...
  3. $ curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  4.   -H "Content-Type: application/json"
  5.   -d '[
  6.         {
  7.           "key": "A12345",
  8.           "value": "Dapr Contract"
  9.         }
  10.       ]'

The following AWS CLI Command displays the contents of the DynamoDB Contracts table:

  1. $ aws dynamodb get-item \
  2.     --table-name Contracts \
  3.     --key '{"ContractID":{"S":"contractsprocessing||A12345"}}' 
  4. {
  5.     "Item": {
  6.         "value": {
  7.             "S": "Dapr Contract"
  8.         },
  9.         "etag": {
  10.             "S": "....."
  11.         },
  12.         "ContractID": {
  13.             "S": "contractsprocessing||A12345"
  14.         }
  15.     }
  16. }

Last modified January 17, 2023: [1.10][AWS DynamoDB] Documentation for Partition Key Metadata Field (#3052) (a95ddf4d)