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.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: accessKey
    value: "AKIAIOSFODNN7EXAMPLE" # Optional
  - name: secretKey
    value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" # Optional
  - name: endpoint
    value: "http://localhost:8080" # Optional
  - name: region
    value: "eu-west-1" # Optional
  - name: sessionToken
    value: "myTOKEN" # Optional
  - name: ttlAttributeName
    value: "expiresAt" # Optional
  - name: partitionKey
    value: "ContractID" # Optional

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

Field Required Details Example
table Y name of the DynamoDB table to use "Contracts"
accessKey N ID of the AWS account with appropriate permissions to SNS and SQS. Can be secretKeyRef to use a secret reference "AKIAIOSFODNN7EXAMPLE"
secretKey N Secret for the AWS user. Can be secretKeyRef to use a secret reference "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
region N The 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"
endpoint N AWS endpoint for the component to use. Only used for local development. The endpoint is unncessary when running against production AWS "http://localhost:4566"
sessionToken N AWS session token to use. A session token is only required if you are using temporary security credentials. "TOKEN"
ttlAttributeName N The table attribute name which should be used for TTL. "expiresAt"
partitionKey N The 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"

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:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: partitionKey
    value: "ContractID"

The above component specification assumes the following DynamoDB Table Layout:

{
    "Table": {
        "AttributeDefinitions": [
            {
                "AttributeName": "ContractID",
                "AttributeType": "S"
            }
        ],
        "TableName": "Contracts",
        "KeySchema": [
            {
                "AttributeName": "ContractID",
                "KeyType": "HASH"
            }
        ],
}

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:

$ dapr run --app-id contractsprocessing --app-port ...

$ curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "A12345",
          "value": "Dapr Contract"
        }
      ]'

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

$ aws dynamodb get-item \
    --table-name Contracts \
    --key '{"ContractID":{"S":"contractsprocessing||A12345"}}' 
{
    "Item": {
        "value": {
            "S": "Dapr Contract"
        },
        "etag": {
            "S": "....."
        },
        "ContractID": {
            "S": "contractsprocessing||A12345"
        }
    }
}