Creating DynamoDB Global Tables with Terraform

Introduction

Amazon DynamoDB offers the option to create global tables, which are replicas of your table across your choice of AWS regions. More details can be found on the official documentation: https://aws.amazon.com/dynamodb/global-tables/

The version of global tables discussed in this story is 2019.11.21.

This story will provide steps on how to create global tables using Terraform and how to manage existing global tables, that were originally created manually (via AWS CLI or console), through Terraform.

How to create new global tables using Terraform

Configure provider block with version constraint set to “~> 2.58”. AWS provider versions less than 2.58.0 do not support the replica configuration block.

provider "aws" {
  region = "us-east-1"
  profile = "prod"
  version = "~> 2.58"
}

Configure aws_dynamodb_table resource with replica configuration block(one block per AWS region):

resource "aws_dynamodb_table" "test" {
  name           = "test"
  read_capacity  = 5
  write_capacity = 5
  hash_key       = "Id"
  attribute {
    name = "Id"
    type = "S"
  } 
  replica = {
    region_name = "us-west-2"
  }
}

This resource will create a global table in us-west-2. If you want to create global tables in more than one region, you will need to add them one at a time to the resource and deploy the script each time you add a replica configuration block.

Although Terraform’s official documentation provides an example with multiple replica configuration blocks, currently there is a code bug that does not allow you to create or delete multiple replicas at once. You can find the related bug-fix here, which should be deployed in the near future.

Once the bug-fix is deployed, you can pin the aws provider version to the version that includes the bug-fix. Then, your resource block will look like the following:

Bugfix has been deployed in version 2.65.

provider "aws" {
  region = "us-east-1"
  profile = "prod"
  version = "~> 2.65"
}
resource "aws_dynamodb_table" "test" {
  name           = "test"
  read_capacity  = 5
  write_capacity = 5
  hash_key       = "Id"
  attribute {
    name = "Id"
    type = "S"
  }
  replica = {
    region_name = "us-west-2"
  }
  replica = {
    region_name = "eu-central-1"
  }
  replica = {
    region_name = "ap-southeast-2"
  }
}

How to manage existing global tables through Terraform

Before Terraform supported global tables, you might have manually created global tables via AWS CLI or console. As Terraform started supporting global tables from aws provider version 2.58, you might be in risk of losing your previously created global tables upon your next deployment. There are two ways to handle this situation.

1. Pin your aws provider version to 2.57.0.

If you have not already pinned your aws provider version and do not update your Terraform script to include the replica configuration block, your existing global tables will be deleted. Therefore, you must pin your provider to version 2.57.0 like below. Then, all your existing global tables will not be deleted.

provider "aws" {
  region = "us-east-1"
  profile = "prod"
  version = "~> 2.57.0"
}

2. Pin your aws provider version to 2.58.0 and add the replica configuration block(s) to your Terraform script for all the global tables you created.

provider "aws" {
  region = "us-east-1"
  profile = "prod"
  version = "~> 2.58.0"
}
resource "aws_dynamodb_table" "test" {
  name           = "test"
  read_capacity  = 5
  write_capacity = 5
  hash_key       = "Id"
  attribute {
    name = "Id"
    type = "S"
  }
  replica = {
    region_name = "replica-region-1"
  }
  replica = {
    region_name = "replica-region-2"
  }
}