/aws-cloudformation-dynamodb

name: aws-cloudformation-dynamodb
description: Provides AWS CloudFormation patterns for DynamoDB tables, GSIs, LSIs, auto-scaling, and streams. Use when creating DynamoDB tables with CloudFormation, configuring primary keys, local/global secondary indexes, capacity modes (on-demand/provisioned), point-in-time recovery, encryption, TTL, and implementing template structure with Parameters, Outputs, Mappings, Conditions, cross-stack references.
allowed-tools: Read, Write, Bash

AWS CloudFormation DynamoDB Patterns

Provides production-ready NoSQL database infrastructure patterns using AWS CloudFormation templates with DynamoDB tables, GSIs, LSIs, auto-scaling, encryption, TTL, and streams.

Overview

Covers DynamoDB tables, primary keys, secondary indexes (GSI/LSI), capacity modes, auto-scaling, encryption, TTL, streams, and best practices for parameters, outputs, and cross-stack references.

When to Use

Creating DynamoDB tables, configuring keys and indexes, setting capacity modes, implementing auto-scaling, enabling encryption/TTL/streams, and organizing CloudFormation templates.

Instructions

Follow these steps to create DynamoDB tables with CloudFormation:

1. **Define Table Parameters**: Specify table name and billing mode 2. **Configure Primary Key**: Set partition key and optional sort key 3. **Add Secondary Indexes**: Create GSIs for alternative access patterns 4. **Configure Encryption**: Enable encryption using KMS keys 5. **Set Up TTL**: Define timestamp attribute for automatic deletion 6. **Enable Streams**: Configure stream for change data capture 7. **Add Auto Scaling**: Implement Application Auto Scaling for provisioned capacity 8. **Create Backup**: Enable point-in-time recovery 9. **Validate Template**: Run `aws cloudformation validate-template` before deployment 10. **Deploy Stack**: Use `aws cloudformation create-stack` or `update-stack` 11. **Monitor Events**: Check `aws cloudformation describe-stack-events` for failures or `ROLLBACK` status 12. **Handle Rollback**: On failure, review events for resource errors, fix the template, and re-deploy

Quick Reference

| Resource Type | Purpose | |---------------|---------| | `AWS::DynamoDB::Table` | Create DynamoDB table | | `AWS::ApplicationAutoScaling::ScalableTarget` | Auto scaling configuration | | `AWS::ApplicationAutoScaling::ScalingPolicy` | Scaling policies | | `AWS::KMS::Key` | KMS key for encryption | | `AWS::IAM::Role` | IAM roles for auto scaling | | BillingMode | `PAY_PER_REQUEST` or `PROVISIONED` | | SSESpecification | Server-side encryption |

Examples

Basic Table with On-Demand Capacity

DynamoDBTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: !Sub "${AWS::StackName}-table"
    BillingMode: PAY_PER_REQUEST
    AttributeDefinitions:
      - AttributeName: pk
        AttributeType: S
    KeySchema:
      - AttributeName: pk
        KeyType: HASH

Table with Global Secondary Index

DynamoDBTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: !Sub "${AWS::StackName}-table"
    BillingMode: PAY_PER_REQUEST
    AttributeDefinitions:
      - AttributeName: pk
        AttributeType: S
      - AttributeName: gsi-pk
        AttributeType: S
    KeySchema:
      - AttributeName: pk
        KeyType: HASH
    GlobalSecondaryIndexes:
      - IndexName: gsi-index
        KeySchema:
          - AttributeName: gsi-pk
            KeyType: HASH
        Projection:
          ProjectionType: ALL

Table with TTL

SessionTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: !Sub "${AWS::StackName}-sessions"
    BillingMode: PAY_PER_REQUEST
    AttributeDefinitions:
      - AttributeName: sessionId
        AttributeType: S
    KeySchema:
      - AttributeName: sessionId
        KeyType: HASH
    TimeToLiveSpecification:
      AttributeName: expiresAt
      Enabled: true

Table with Auto Scaling

ScalableTarget:
  Type: AWS::ApplicationAutoScaling::ScalableTarget
  Properties:
    MaxCapacity: 100
    MinCapacity: 5
    ResourceId: !Sub "table/${DynamoDBTable}"
    RoleARN: !GetAtt AutoScalingRole.Arn
    ScalableDimension: dynamodb:table:ReadCapacityUnits
    ServiceNamespace: dynamodb

See [references/complete-examples.md](references/complete-examples.md) for more complete examples including encryption, streams, auto scaling, and production tables.

Template Structure

Base Template

AWSTemplateFormatVersion: 2010-09-09
Description: DynamoDB table with GSI and auto-scaling

Parameters:
  TableName:
    Type: String
    Default: my-table
  BillingMode:
    Type: String
    Default: PAY_PER_REQUEST

Resources:
  DynamoDBTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: !Ref TableName
      BillingMode: !Ref BillingMode

Outputs:
  TableName:
    Value: !Ref DynamoDBTable
  TableArn:
    Value: !GetAtt DynamoDBTable.Arn

See [references/advanced-configuration.md](references/advanced-configuration.md) for detailed Parameters, Mappings, Conditions, Outputs, IAM roles, and cross-stack references.

Best Practices

1. **Use PAY_PER_REQUEST** for development/testing and unpredictable workloads 2. **Enable Point-In-Time Recovery** for production tables 3. **Use KMS encryption** for sensitive data (SSE-KMS) 4. **Configure auto-scaling** for provisioned capacity tables 5. **Design GSIs carefully** - each GSI consumes capacity 6. **Use TTL** for automatic data expiration (sessions, cache) 7. **Enable Streams** for change data capture and analytics 8. **Tag resources** for cost allocation and organization 9. **Export outputs** for cross-stack references 10. **Use Conditions** for environment-specific configurations

Common Troubleshooting

**Table already exists**: Use unique table names or stack deletion policy **GSI creation fails**: Verify attribute definitions include GSI attributes **Auto-scaling not working**: Check IAM role permissions and service-linked role **TTL no