Cloud
Also in Self-Managed

aws_dynamodb

Stores key/value pairs as a single document in a DynamoDB table. The key is stored as a string value and used as the table hash key. The value is stored as a binary value using the data_key field name.

A prefix can be specified to allow multiple cache types to share a single DynamoDB table. An optional TTL duration (ttl) and field (ttl_key) can be specified if the backing table has TTL enabled.

Strong read consistency can be enabled using the consistent_read configuration field.

  • Common

  • Advanced

cache:
  label: ""
  aws_dynamodb:
    table: "" # No default (required)
    hash_key: "" # No default (required)
    data_key: "" # No default (required)
cache:
  label: ""
  aws_dynamodb:
    table: "" # No default (required)
    hash_key: "" # No default (required)
    data_key: "" # No default (required)
    consistent_read: false
    default_ttl: "" # No default (optional)
    ttl_key: "" # No default (optional)
    retries:
      initial_interval: 1s
      max_interval: 5s
      max_elapsed_time: 30s
    region: "" # No default (optional)
    endpoint: "" # No default (optional)
    tcp:
      connect_timeout: 0s
      keep_alive:
        idle: 15s
        interval: 15s
        count: 9
      tcp_user_timeout: 0s
    credentials:
      profile: "" # No default (optional)
      id: "" # No default (optional)
      secret: "" # No default (optional)
      token: "" # No default (optional)
      from_ec2_role: false # No default (optional)
      role: "" # No default (optional)
      role_external_id: "" # No default (optional)

Fields

consistent_read

Whether to use strongly consistent reads on Get commands.

Type: bool

Default: false

credentials

Manually configure the AWS credentials to use (optional). For more information, see the Amazon Web Services guide.

Type: object

credentials.from_ec2_role

Use the credentials of a host EC2 machine configured to assume an IAM role associated with the instance.

Type: bool

credentials.id

The ID of the AWS credentials to use.

Type: string

credentials.profile

The profile from ~/.aws/credentials to use.

Type: string

credentials.role

The ARN of the role to assume.

Type: string

credentials.role_external_id

An external ID to use when assuming a role.

Type: string

credentials.secret

The secret for the AWS credentials in use.

This field contains sensitive information that usually shouldn’t be added to a configuration directly. For more information, see Manage Secrets before adding it to your configuration.

Type: string

credentials.token

The token for the AWS credentials in use. Required only when using short-term credentials.

Type: string

data_key

The key of the table column to store item values within.

Type: string

default_ttl

An optional default TTL to set for items, calculated from the moment the item is cached. A ttl_key must be specified in order to set item TTLs.

Type: string

endpoint

A custom endpoint URL for AWS API requests. Use this to connect to AWS-compatible services or local testing environments instead of the standard AWS endpoints.

Type: string

hash_key

The key of the table column to store item keys within.

Type: string

region

The AWS region in which your resources are hosted.

Type: string

retries

Determine time intervals and cut offs for retry attempts.

Type: object

retries.initial_interval

The initial period to wait between retry attempts. The retry interval increases for each failed attempt, up to the max_interval value. This field accepts Go duration format strings such as 100ms, 1s, or 5s.

Type: string

Default: 1s

# Examples:
initial_interval: 50ms

# ---

initial_interval: 1s

retries.max_elapsed_time

The maximum overall period of time to spend on retry attempts before the request is aborted.

Type: string

Default: 30s

# Examples:
max_elapsed_time: 1m

# ---

max_elapsed_time: 1h

retries.max_interval

The maximum period to wait between retry attempts

Type: string

Default: 5s

# Examples:
max_interval: 5s

# ---

max_interval: 1m

table

The table to store items in.

Type: string

tcp

Configure TCP socket-level settings to optimize network performance and reliability. These low-level controls are useful for:

  • Unresponsive hosts: Set connect_timeout to limit how long a connection attempt can take (the default 0s sets no limit)

  • Long-lived connections: Configure keep_alive settings to detect and recover from stale connections

  • Unstable networks: Tune keep-alive probes to balance between quick failure detection and avoiding false positives

  • Linux systems with specific requirements: Use tcp_user_timeout (Linux 2.6.37+) to control data acknowledgment timeouts

Most users should keep the default values. Only modify these settings if you’re experiencing connection stability issues or have specific network requirements.

Type: object

tcp.connect_timeout

Maximum amount of time a dial will wait for a connect to complete. Zero disables.

Type: string

Default: 0s

tcp.keep_alive

TCP keep-alive probe configuration.

Type: object

tcp.keep_alive.count

Maximum unanswered keep-alive probes before dropping the connection. Zero defaults to 9.

Type: int

Default: 9

tcp.keep_alive.idle

Duration the connection must be idle before sending the first keep-alive probe. Zero defaults to 15s. Negative values disable keep-alive probes.

Type: string

Default: 15s

tcp.keep_alive.interval

Duration between keep-alive probes. Zero defaults to 15s.

Type: string

Default: 15s

tcp.tcp_user_timeout

Maximum time to wait for acknowledgment of transmitted data before killing the connection. Linux-only (kernel 2.6.37+), ignored on other platforms. When enabled, keep_alive.idle must be greater than this value per RFC 5482. Zero disables.

Type: string

Default: 0s

ttl_key

The column key to place the TTL value within. The value is the expiry time as a Unix timestamp in seconds, stored as a number attribute, which is the format that DynamoDB TTL requires. A TTL value is only written when both this field and a TTL duration are set.

Type: string