DynamoDB configuration for Vault backend storage

The DynamoDB storage backend is used to persist Vault's data in DynamoDB table.

High Availability – the DynamoDB storage backend supports high availability. Because DynamoDB uses the time on the Vault node to implement the session lifetimes on its locks, significant clock skew across Vault nodes could cause contention issues on the lock.
Community Supported – the DynamoDB storage backend is supported by the community. While it has undergone review by HashiCorp employees, they may not be as knowledgeable about the technology. If you encounter problems with this storage backend, you could be referred to the original author for support.

storage "dynamodb" {
  ha_enabled = "true"
  region     = "us-west-2"
  table      = "vault-data"
}

For more information about the read/write capacity of DynamoDB tables, please see the official AWS DynamoDB documentation.

DynamoDB parameters

endpoint (string: "") – Specifies an alternative, AWS compatible, DynamoDB endpoint. This can also be provided via the environment variable AWS_DYNAMODB_ENDPOINT.
ha_enabled (string: "false") – Specifies whether this backend should be used to run Vault in high availability mode. Valid values are "true" or "false". This can also be provided via the environment variable DYNAMODB_HA_ENABLED.
max_parallel (string: "128") – Specifies the maximum number of concurrent requests.
region (string "us-east-1") – Specifies the AWS region. This can also be provided via the environment variable AWS_DEFAULT_REGION.
read_capacity (int: 5) – Specifies the maximum number of reads consumed per second on the table, for use if Vault creates the DynamoDB table. This has no effect if the table already exists. This can also be provided via the environment variable AWS_DYNAMODB_READ_CAPACITY.
table (string: "vault-dynamodb-backend") – Specifies the name of the DynamoDB table in which to store Vault data. If the specified table does not yet exist, it will be created during initialization. This can also be provided via the environment variable AWS_DYNAMODB_TABLE. See the information on the table schema below.
write_capacity (int: 5) – Specifies the maximum number of writes performed per second on the table, for use if Vault creates the DynamoDB table. This value has no effect if the table already exists. This can also be provided via the environment variable AWS_DYNAMODB_WRITE_CAPACITY.

The following settings are used for authenticating to AWS. If you are running your Vault server on an EC2 instance, you can also make use of the EC2 instance profile service to provide the credentials Vault will use to make DynamoDB API calls. Leaving the access_key and secret_key fields empty will cause Vault to attempt to retrieve credentials from the AWS metadata service.

access_key (string: <required>) – Specifies the AWS access key. This can also be provided via the environment variable AWS_ACCESS_KEY_ID.
secret_key (string: <required>) – Specifies the AWS secret key. This can also be provided via the environment variable AWS_SECRET_ACCESS_KEY.
session_token (string: "") – Specifies the AWS session token. This can also be provided via the environment variable AWS_SESSION_TOKEN.

Required AWS permissions

The governing policy for the IAM user or EC2 instance profile that Vault uses to access DynamoDB must contain the following permissions for Vault to perform the required operations on the DynamoDB table:

  "Statement": [
    {
      "Action": [
        "dynamodb:DescribeLimits",
        "dynamodb:DescribeTimeToLive",
        "dynamodb:ListTagsOfResource",
        "dynamodb:DescribeReservedCapacityOfferings",
        "dynamodb:DescribeReservedCapacity",
        "dynamodb:ListTables",
        "dynamodb:BatchGetItem",
        "dynamodb:BatchWriteItem",
        "dynamodb:CreateTable",
        "dynamodb:DeleteItem",
        "dynamodb:GetItem",
        "dynamodb:GetRecords",
        "dynamodb:PutItem",
        "dynamodb:Query",
        "dynamodb:UpdateItem",
        "dynamodb:Scan",
        "dynamodb:DescribeTable"
      ],
      "Effect": "Allow",
      "Resource": [ "arn:aws:dynamodb:us-east-1:... dynamodb table ARN" ]
    },

Table schema

If you are going to create the DynamoDB table prior to the execution and initialization of Vault, you will need to create a table with these attributes:

Primary partition key: "Path", a string
Primary sort key: "Key", a string

You might create the table via Terraform, with a configuration similar to this:

resource "aws_dynamodb_table" "dynamodb-table" {
  name           = "${var.dynamoTable}"
  read_capacity  = 1
  write_capacity = 1
  hash_key       = "Path"
  range_key      = "Key"
  
  attribute {
    name = "Path"
    type = "S"
  }
 
  attribute {
    name = "Key"
    type = "S"
  }
 
  tags = {
    Name        = "vault-dynamodb-table"
    Environment = "prod"
  }
}

If a table with the configured name already exists, Vault will not modify it - and the Vault configuration values of read_capacity and write_capacity have no effect.

If the table does not already exist, Vault will try to create it, with read and write capacities set to the values of read_capacity and write_capacity respectively.

AWS instance metadata timeout

Affects Vault 1.4 and later

Anytime Vault uses the instance metadata service on an EC2 instance, such as for getting credentials from the instance profile, there may be a delay with the introduction of v2 of the instance metadata service (IMDSv2). The AWS SDK used by Vault first attempts to connect to IMDSv2, and if that times out, it falls back to v1. In Vault 1.4, this timeout can take up to 2 minutes. In Vault 1.5.5 and later, it can take up to 2 seconds with this fix: #10133.

The timeout occurs in situations where there is a proxy between Vault and IMDSv2, and the instance hop limit is set to less than the number of "hops" between Vault and IMDSv2. For example, if Vault is running in docker on an EC2 instance with the instance hop limit set to 1, the AWS SDK client will attempt to connect to IMDSv2, timeout, and fall back to IMDSv1 because of the extra network hop between docker and IMDS.

To avoid the timeout behavior, the hop limit may be adjusted on the underlying EC2 instances. With the docker example, setting the hop limit to 2 will allow the AWS SDK in Vault to connect to IMDSv2 without delay.

DynamoDB examples of Vault configuration

Custom table and Read-Write capacity

This example shows using a custom table name and read/write capacity.

storage "dynamodb" {
  table = "my-vault-data"

  read_capacity  = 10
  write_capacity = 15
}

Enabling high availability

This example shows enabling high availability for the DynamoDB storage backend.

api_addr = "https://vault-leader.my-company.internal"

storage "dynamodb" {
  ha_enabled    = "true"
  ...
}