README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-dynamodb
# Tags of this project
tags:
  - aws
  - terraform
  - terraform-modules
  - databases
  - autoscaling
  - dynamodb
  - dynamodb-table
  - dynamodb-database
# Categories of this project
categories:
  - terraform-modules/databases
# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"
# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-dynamodb
# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-dynamodb.svg"
    url: "https://github.com/cloudposse/terraform-aws-dynamodb/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"
related:
  - name: "terraform-aws-dynamodb-autoscaler"
    description: "Terraform module to provision DynamoDB autoscaler"
    url: "https://github.com/cloudposse/terraform-aws-dynamodb-autoscaler"
  - name: "terraform-aws-tfstate-backend"
    description: "Provision an S3 bucket to store terraform.tfstate file and a DynamoDB table to lock the state file to prevent concurrent modifications and state corruption"
    url: "https://github.com/cloudposse/terraform-aws-tfstate-backend"
  - name: "terraform-aws-elasticache-redis"
    description: "Terraform module to provision an ElastiCache Redis Cluster"
    url: "https://github.com/cloudposse/terraform-aws-elasticache-redis"
  - name: "terraform-aws-elasticache-memcached"
    description: "Terraform Module for ElastiCache Memcached Cluster"
    url: "https://github.com/cloudposse/terraform-aws-elasticache-memcached"
  - name: "terraform-aws-elasticache-cloudwatch-sns-alarms"
    description: "Terraform module that configures CloudWatch SNS alerts for ElastiCache"
    url: "https://github.com/cloudposse/terraform-aws-elasticache-cloudwatch-sns-alarms"
  - name: "terraform-aws-rds-cluster"
    description: "Terraform module to provision an RDS Aurora cluster for MySQL or Postgres"
    url: "https://github.com/cloudposse/terraform-aws-rds-cluster"
  - name: "terraform-aws-rds"
    description: "Terraform module to provision AWS RDS instances"
    url: "https://github.com/cloudposse/terraform-aws-rds"
# Short description of this project
description: |-
  Terraform module to provision a DynamoDB table with autoscaling.

  Autoscaler scales up/down the provisioned OPS for the DynamoDB table based on the load.

  ## Requirements

  This module requires [AWS Provider](https://github.com/terraform-providers/terraform-provider-aws) `>= 4.22.0`
# How to use this project
usage: |2-

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest) (which tests and deploys the example on AWS), see [test](test).

  ```hcl
  module "dynamodb_table" {
    source = "cloudposse/dynamodb/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    namespace                    = "eg"
    stage                        = "dev"
    name                         = "cluster"
    hash_key                     = "HashKey"
    range_key                    = "RangeKey"
    autoscale_write_target       = 50
    autoscale_read_target        = 50
    autoscale_min_read_capacity  = 5
    autoscale_max_read_capacity  = 20
    autoscale_min_write_capacity = 5
    autoscale_max_write_capacity = 20
    enable_autoscaler            = true
  }
  ```

  ## Advanced Usage

  With additional attributes, global secondary indexes and `non_key_attributes` (see [examples/complete](examples/complete)).

  ```hcl
  module "dynamodb_table" {
    source = "cloudposse/dynamodb/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    namespace                    = "eg"
    stage                        = "dev"
    name                         = "cluster"
    hash_key                     = "HashKey"
    range_key                    = "RangeKey"
    autoscale_write_target       = 50
    autoscale_read_target        = 50
    autoscale_min_read_capacity  = 5
    autoscale_max_read_capacity  = 20
    autoscale_min_write_capacity = 5
    autoscale_max_write_capacity = 20
    enable_autoscaler            = true

    dynamodb_attributes = [
      {
        name = "DailyAverage"
        type = "N"
      },
      {
        name = "HighWater"
        type = "N"
      },
      {
        name = "Timestamp"
        type = "S"
      }
    ]

    local_secondary_index_map = [
      {
        name               = "TimestampSortIndex"
        range_key          = "Timestamp"
        projection_type    = "INCLUDE"
        non_key_attributes = ["HashKey", "RangeKey"]
      },
      {
        name               = "HighWaterIndex"
        range_key          = "Timestamp"
        projection_type    = "INCLUDE"
        non_key_attributes = ["HashKey", "RangeKey"]
      }
    ]

    global_secondary_index_map = [
      {
        name               = "DailyAverageIndex"
        hash_key           = "DailyAverage"
        range_key          = "HighWater"
        write_capacity     = 5
        read_capacity      = 5
        projection_type    = "INCLUDE"
        non_key_attributes = ["HashKey", "RangeKey"]
      }
    ]

    replicas = ["us-east-1"]
  }
  ```

  __NOTE:__ Variables "global_secondary_index_map" and "local_secondary_index_map" have a predefined schema, but in some cases not all fields are required or needed.

  For example:
   * `non_key_attributes` can't be specified for Global Secondary Indexes (GSIs) when `projection_type` is `ALL`
   * `read_capacity` and `write_capacity` are not required for GSIs

  In these cases, set the fields to `null` and Terraform will treat them as if they were not provided at all, but will not complain about missing values:

  ```hcl
    global_secondary_index_map = [
      {
        write_capacity     = null
        read_capacity      = null
        projection_type    = "ALL"
        non_key_attributes = null
      }
    ]
  ```

  See [Terraform types and values](https://www.terraform.io/docs/configuration/expressions.html#types-and-values) for more details.
include:
  - "docs/targets.md"
  - "docs/terraform.md"
# Contributors to this project
contributors:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Jamie Nelson"
    github: "Jamie-BitFlight"
  - name: "Daren Desjardins"
    github: "darend"
  - name: "Maarten van der Hoef"
    github: "maartenvanderhoef"