DynamoDB CloudFormation: Tables, Indexes and Backups

Use AWS::DynamoDB::Table in CloudFormation to create a regional DynamoDB table, or AWS::DynamoDB::GlobalTable to manage a current global table and its replicas. Set BillingMode: PAY_PER_REQUEST explicitly for on-demand capacity. Protect persistent data with DeletionPolicy: Retain, UpdateReplacePolicy: Retain and DynamoDB deletion protection.

How CloudFormation works with DynamoDB

CloudFormation accepts YAML or JSON describing a desired collection of AWS resources. A stack owns those resources, resolves dependencies and applies changes. This gives you a reviewable configuration for development and production, but it does not make deployments instantaneous or every update reversible. Table creation, index backfill and replica operations can take time.

Version-controlled templates make configuration changes visible in code review. Parameters let environments use different values without maintaining unrelated copies. A change set shows proposed additions, modifications and replacements before execution. Security depends on the permissions and policies you define; merely putting a table in a template does not restrict application access.

Use the current Table reference and GlobalTable reference. The resources have different property shapes, especially for capacity and replica settings.

Create an on-demand DynamoDB table

Save this complete template as student-table.yaml:

AWSTemplateFormatVersion: "2010-09-09"
Description: Student table with backups and deletion protection
Resources:
  StudentTable:
    Type: AWS::DynamoDB::Table
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      DeletionProtectionEnabled: true
      AttributeDefinitions:
        - AttributeName: studentId
          AttributeType: S
      KeySchema:
        - AttributeName: studentId
          KeyType: HASH
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true
        RecoveryPeriodInDays: 14
      TimeToLiveSpecification:
        AttributeName: expiresAt
        Enabled: true
      Tags:
        - Key: Application
          Value: students
Outputs:
  TableName:
    Value: !Ref StudentTable
  TableArn:
    Value: !GetAtt StudentTable.Arn
AWSTemplateFormatVersion: "2010-09-09"
Description: Student table with backups and deletion protection
Resources:
  StudentTable:
    Type: AWS::DynamoDB::Table
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      DeletionProtectionEnabled: true
      AttributeDefinitions:
        - AttributeName: studentId
          AttributeType: S
      KeySchema:
        - AttributeName: studentId
          KeyType: HASH
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true
        RecoveryPeriodInDays: 14
      TimeToLiveSpecification:
        AttributeName: expiresAt
        Enabled: true
      Tags:
        - Key: Application
          Value: students
Outputs:
  TableName:
    Value: !Ref StudentTable
  TableArn:
    Value: !GetAtt StudentTable.Arn

Ref returns the physical table name; GetAtt Arn returns its ARN. Letting CloudFormation generate the name avoids collisions between environments. If you set TableName, replacement may require a new name, so plan data migration before changing key definitions.

Only table and index keys belong in AttributeDefinitions. Item fields such as a student's name, email or expiry time do not need schema declarations. HASH means partition key and RANGE means sort key. Attribute types are S, N or B, not full application object schemas.

Validate and preview the deployment with AWS CLI v2:

aws sts get-caller-identity
aws cloudformation validate-template --template-body file://student-table.yaml
aws cloudformation deploy --template-file student-table.yaml \
  --stack-name students-dev --region us-east-1 --no-execute-changeset
aws sts get-caller-identity
aws cloudformation validate-template --template-body file://student-table.yaml
aws cloudformation deploy --template-file student-table.yaml \
  --stack-name students-dev --region us-east-1 --no-execute-changeset

Inspect the resulting change set before executing it. Template validation does not prove that quotas, permissions and every service-specific combination are valid. Check stack events if deployment fails and confirm the table is active before using it.

Maximum throughput and warm throughput

For an on-demand table, add an optional rate cap inside Properties:

OnDemandThroughput:
  MaxReadRequestUnits: 20000
  MaxWriteRequestUnits: 8000
OnDemandThroughput:
  MaxReadRequestUnits: 20000
  MaxWriteRequestUnits: 8000

This is a best-effort throughput target, not a hard spending ceiling. Requests above it may be throttled, while burst capacity can temporarily exceed it. GSIs support separate OnDemandThroughput settings. Do not combine on-demand billing with ProvisionedThroughput.

Warm throughput prepares the table for an immediate traffic increase:

WarmThroughput:
  ReadUnitsPerSecond: 20000
  WriteUnitsPerSecond: 8000
WarmThroughput:
  ReadUnitsPerSecond: 20000
  WriteUnitsPerSecond: 8000

Proactively increasing warm throughput can incur a one-time fee. It is useful before a known spike, not a required setting for every new table. Ensure the configured maximum permits the traffic you intend to serve. The warm-throughput property reference documents its shape.

Create a global secondary index

To query students by class, add classId to AttributeDefinitions and the index to StudentTable.Properties:

AttributeDefinitions:
  - AttributeName: studentId
    AttributeType: S
  - AttributeName: classId
    AttributeType: S
GlobalSecondaryIndexes:
  - IndexName: ByClass
    KeySchema:
      - AttributeName: classId
        KeyType: HASH
    Projection:
      ProjectionType: ALL
AttributeDefinitions:
  - AttributeName: studentId
    AttributeType: S
  - AttributeName: classId
    AttributeType: S
GlobalSecondaryIndexes:
  - IndexName: ByClass
    KeySchema:
      - AttributeName: classId
        KeyType: HASH
    Projection:
      ProjectionType: ALL

Replace the existing AttributeDefinitions list; do not duplicate the YAML key. Keep the base table's KeySchema. A GSI has its own partition key and can optionally have a sort key. ALL copies all fields; KEYS_ONLY copies keys; INCLUDE adds an explicit list of non-key attributes.

For provisioned tables, every GSI needs ProvisionedThroughput too. For on-demand tables, omit it. Add or remove indexes in separate, reviewed updates and monitor backfill. CloudFormation can finish a stack update before a new GSI finishes backfilling, so gate application queries on the index's active status.

Create a local secondary index

An LSI shares the table partition key and requires the base table to have a sort key. The following complete resource models a student's enrollments and supports ordering them by student name:

EnrollmentTable:
  Type: AWS::DynamoDB::Table
  DeletionPolicy: Retain
  UpdateReplacePolicy: Retain
  Properties:
    BillingMode: PAY_PER_REQUEST
    DeletionProtectionEnabled: true
    AttributeDefinitions:
      - AttributeName: studentId
        AttributeType: S
      - AttributeName: moduleCode
        AttributeType: S
      - AttributeName: studentName
        AttributeType: S
    KeySchema:
      - AttributeName: studentId
        KeyType: HASH
      - AttributeName: moduleCode
        KeyType: RANGE
    LocalSecondaryIndexes:
      - IndexName: ByStudentName
        KeySchema:
          - AttributeName: studentId
            KeyType: HASH
          - AttributeName: studentName
            KeyType: RANGE
        Projection:
          ProjectionType: KEYS_ONLY
EnrollmentTable:
  Type: AWS::DynamoDB::Table
  DeletionPolicy: Retain
  UpdateReplacePolicy: Retain
  Properties:
    BillingMode: PAY_PER_REQUEST
    DeletionProtectionEnabled: true
    AttributeDefinitions:
      - AttributeName: studentId
        AttributeType: S
      - AttributeName: moduleCode
        AttributeType: S
      - AttributeName: studentName
        AttributeType: S
    KeySchema:
      - AttributeName: studentId
        KeyType: HASH
      - AttributeName: moduleCode
        KeyType: RANGE
    LocalSecondaryIndexes:
      - IndexName: ByStudentName
        KeySchema:
          - AttributeName: studentId
            KeyType: HASH
          - AttributeName: studentName
            KeyType: RANGE
        Projection:
          ProjectionType: KEYS_ONLY

Insert it under Resources as an alternative example. LSIs must be created with the table; adding one to a populated table requires a new table and a migration. Choose the key design from actual access patterns before deployment.

Configure provisioned auto scaling

For the original StudentTable, change billing to PROVISIONED, remove on-demand caps, and add:

ProvisionedThroughput:
  ReadCapacityUnits: 5
  WriteCapacityUnits: 5
ProvisionedThroughput:
  ReadCapacityUnits: 5
  WriteCapacityUnits: 5

Then add these resources beside StudentTable to scale writes:

StudentWriteTarget:
  Type: AWS::ApplicationAutoScaling::ScalableTarget
  DependsOn: StudentTable
  Properties:
    MinCapacity: 5
    MaxCapacity: 100
    ResourceId: !Sub "table/${StudentTable}"
    ScalableDimension: dynamodb:table:WriteCapacityUnits
    ServiceNamespace: dynamodb
    RoleARN: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/aws-service-role/dynamodb.application-autoscaling.amazonaws.com/AWSServiceRoleForApplicationAutoScaling_DynamoDBTable"
StudentWritePolicy:
  Type: AWS::ApplicationAutoScaling::ScalingPolicy
  Properties:
    PolicyName: StudentWriteTargetTracking
    PolicyType: TargetTrackingScaling
    ScalingTargetId: !Ref StudentWriteTarget
    TargetTrackingScalingPolicyConfiguration:
      TargetValue: 70
      ScaleInCooldown: 60
      ScaleOutCooldown: 60
      PredefinedMetricSpecification:
        PredefinedMetricType: DynamoDBWriteCapacityUtilization
StudentWriteTarget:
  Type: AWS::ApplicationAutoScaling::ScalableTarget
  DependsOn: StudentTable
  Properties:
    MinCapacity: 5
    MaxCapacity: 100
    ResourceId: !Sub "table/${StudentTable}"
    ScalableDimension: dynamodb:table:WriteCapacityUnits
    ServiceNamespace: dynamodb
    RoleARN: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/aws-service-role/dynamodb.application-autoscaling.amazonaws.com/AWSServiceRoleForApplicationAutoScaling_DynamoDBTable"
StudentWritePolicy:
  Type: AWS::ApplicationAutoScaling::ScalingPolicy
  Properties:
    PolicyName: StudentWriteTargetTracking
    PolicyType: TargetTrackingScaling
    ScalingTargetId: !Ref StudentWriteTarget
    TargetTrackingScalingPolicyConfiguration:
      TargetValue: 70
      ScaleInCooldown: 60
      ScaleOutCooldown: 60
      PredefinedMetricSpecification:
        PredefinedMetricType: DynamoDBWriteCapacityUtilization

The deployment identity needs permission to create the DynamoDB Application Auto Scaling service-linked role if it does not already exist. DependsOn belongs beside Properties, not inside it. For reads, create a separate target with dynamodb:table:ReadCapacityUnits and a policy using DynamoDBReadCapacityUtilization.

GSIs use table/TABLE/index/INDEX resource IDs and index dimensions. These separate scaling resources apply to AWS::DynamoDB::Table. A GlobalTable manages scaling through its own throughput settings; AWS explicitly warns against attaching competing scaling resources to its replicas.

Create global tables and replicas

Deploy this template once in us-east-1. It owns both replicas from that stack:

AWSTemplateFormatVersion: "2010-09-09"
Resources:
  StudentGlobalTable:
    Type: AWS::DynamoDB::GlobalTable
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: studentId
          AttributeType: S
      KeySchema:
        - AttributeName: studentId
          KeyType: HASH
      StreamSpecification:
        StreamViewType: NEW_AND_OLD_IMAGES
      WriteOnDemandThroughputSettings:
        MaxWriteRequestUnits: 8000
      Replicas:
        - Region: us-east-1
          DeletionProtectionEnabled: true
          ReadOnDemandThroughputSettings:
            MaxReadRequestUnits: 20000
          PointInTimeRecoverySpecification:
            PointInTimeRecoveryEnabled: true
            RecoveryPeriodInDays: 14
        - Region: us-west-2
          DeletionProtectionEnabled: true
          ReadOnDemandThroughputSettings:
            MaxReadRequestUnits: 20000
          PointInTimeRecoverySpecification:
            PointInTimeRecoveryEnabled: true
            RecoveryPeriodInDays: 14
AWSTemplateFormatVersion: "2010-09-09"
Resources:
  StudentGlobalTable:
    Type: AWS::DynamoDB::GlobalTable
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: studentId
          AttributeType: S
      KeySchema:
        - AttributeName: studentId
          KeyType: HASH
      StreamSpecification:
        StreamViewType: NEW_AND_OLD_IMAGES
      WriteOnDemandThroughputSettings:
        MaxWriteRequestUnits: 8000
      Replicas:
        - Region: us-east-1
          DeletionProtectionEnabled: true
          ReadOnDemandThroughputSettings:
            MaxReadRequestUnits: 20000
          PointInTimeRecoverySpecification:
            PointInTimeRecoveryEnabled: true
            RecoveryPeriodInDays: 14
        - Region: us-west-2
          DeletionProtectionEnabled: true
          ReadOnDemandThroughputSettings:
            MaxReadRequestUnits: 20000
          PointInTimeRecoverySpecification:
            PointInTimeRecoveryEnabled: true
            RecoveryPeriodInDays: 14

This uses multi-Region eventual consistency. Include the stack's Region in Replicas, and do not deploy the same global resource from independent regional stacks. The deployment role needs permissions in all replica Regions.

Global tables use WriteOnDemandThroughputSettings and ReadOnDemandThroughputSettings, rather than the regional table's combined OnDemandThroughput. WarmThroughput is a global resource property. Deletion protection, PITR, resource policies and tags belong to individual replica specifications. Check the replica property reference before copying regional settings.

For a new MRSC table in the same three US Regions, set MultiRegionConsistency: STRONG, keep replicas in us-east-1 and us-west-2, and add:

GlobalTableWitnesses:
  - Region: us-east-2
GlobalTableWitnesses:
  - Region: us-east-2

MRSC requires three Regions, either three data replicas or two plus a witness. It does not support TTL, LSIs or transactions. Start from an empty table and choose consistency at creation. See DynamoDB global tables before selecting it for an application.

Do not change AWS::DynamoDB::Table to AWS::DynamoDB::GlobalTable in place. AWS warns that this can delete the table. If later replication is likely, consider starting with a single-replica GlobalTable, or plan an explicit migration for an existing resource.

Encryption and resource-based policies

DynamoDB always encrypts data at rest with an AWS owned key by default. For a regional table using a customer managed KMS key, add SSESpecification with SSEEnabled: true, SSEType: KMS and KMSMasterKeyId set to the key identifier.

For global tables, set the global SSESpecification to enable KMS and give every replica its own SSESpecification.KMSMasterKeyId. The key must exist in that replica's Region. KMSMasterKeyId is a single property name; splitting it across YAML lines produces an invalid template.

A table can also own a resource-based policy. For a self-contained fragment, define parameters for a fixed table name and an existing reader role ARN, then add these properties:

TableName: !Ref StudentTableName
ResourcePolicy:
  PolicyDocument:
    Version: "2012-10-17"
    Statement:
      - Effect: Allow
        Principal:
          AWS: !Ref ReaderRoleArn
        Action:
          - dynamodb:GetItem
        Resource: !Sub "arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${StudentTableName}"
TableName: !Ref StudentTableName
ResourcePolicy:
  PolicyDocument:
    Version: "2012-10-17"
    Statement:
      - Effect: Allow
        Principal:
          AWS: !Ref ReaderRoleArn
        Action:
          - dynamodb:GetItem
        Resource: !Sub "arn:${AWS::Partition}:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${StudentTableName}"

Define both parameters as Type: String under Parameters. Using the name parameter avoids a circular reference to the resource's own ARN inside its properties. For cross-account access, the reader also needs an identity policy and must use the full table ARN. In global tables, place the policy on each relevant replica. The ResourcePolicy reference describes out-of-band update and drift-detection limitations.

Streams, backups and TTL

These independent properties serve different purposes:

For a regional table's stream, add:

StreamSpecification:
  StreamViewType: NEW_AND_OLD_IMAGES
StreamSpecification:
  StreamViewType: NEW_AND_OLD_IMAGES

The stream includes before and after images and retains records for 24 hours. It is not a long-term backup. KinesisStreamSpecification is a separate integration for Kinesis Data Streams.

PITR protects against accidental writes and deletes after it is enabled. A shorter recovery period does not lower its price. Schedule and manage on-demand backups separately, for example through AWS Backup. Retention policies preserve resources; they do not restore overwritten data.

TTL names the expiry field but does not populate it. Your application writes expiresAt in epoch seconds, and expired items can remain readable until background cleanup deletes them, typically within a few days.

Add CloudWatch alarms

Add the following beside the original StudentTable. It alerts on table write-throttle events; the threshold and period are example monitoring choices:

MonitoringTopic:
  Type: AWS::SNS::Topic
StudentWriteThrottleAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmDescription: Student table write requests are throttled
    Namespace: AWS/DynamoDB
    MetricName: WriteThrottleEvents
    Dimensions:
      - Name: TableName
        Value: !Ref StudentTable
    Statistic: Sum
    Period: 60
    EvaluationPeriods: 1
    Threshold: 0
    ComparisonOperator: GreaterThanThreshold
    TreatMissingData: notBreaching
    AlarmActions:
      - !Ref MonitoringTopic
MonitoringTopic:
  Type: AWS::SNS::Topic
StudentWriteThrottleAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmDescription: Student table write requests are throttled
    Namespace: AWS/DynamoDB
    MetricName: WriteThrottleEvents
    Dimensions:
      - Name: TableName
        Value: !Ref StudentTable
    Statistic: Sum
    Period: 60
    EvaluationPeriods: 1
    Threshold: 0
    ComparisonOperator: GreaterThanThreshold
    TreatMissingData: notBreaching
    AlarmActions:
      - !Ref MonitoringTopic

Add and confirm a subscription to the SNS topic before expecting notifications. Use separate index dimensions for GSI monitoring, and inspect the more specific throttle-reason metrics when diagnosing whether the cause is capacity, a hot key, a quota or an on-demand cap.

Retention, local testing and alternatives

DeletionPolicy: Retain keeps a table when it is removed from the stack or the stack is deleted. UpdateReplacePolicy: Retain keeps the old physical resource during replacement. DeletionProtectionEnabled blocks service deletion until explicitly disabled. A retained table continues to cost money and may no longer be owned by the stack, so record ownership and recovery procedures.

Test application data access with DynamoDB Local, then test CloudFormation and IAM in an AWS development environment. Local emulation does not validate stack deployment or production security behavior.

Terraform is an alternative infrastructure engine. AWS CDK generates CloudFormation from code, and AWS SAM adds serverless resource shorthand. AWS Config and CodeDeploy have different jobs and are not replacements for a DynamoDB resource template.