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-tfstate-backend

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-tfstate-backend

# Badges to display
badges:
  - name: "Build Status"
    image: "https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend.svg?branch=master"
    url: "https://travis-ci.org/cloudposse/terraform-aws-tfstate-backend"
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-tfstate-backend.svg"
    url: "https://github.com/cloudposse/terraform-aws-tfstate-backend/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "terraform-aws-dynamodb"
    description: "Terraform module that implements AWS DynamoDB with support for AutoScaling"
    url: "https://github.com/cloudposse/terraform-aws-dynamodb"
  - name: "terraform-aws-dynamodb-autoscaler"
    description: "Terraform module to provision DynamoDB autoscaler"
    url: "https://github.com/cloudposse/terraform-aws-dynamodb-autoscaler"

# Short description of this project
description: |-
  Terraform module to 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.

  The module supports the following:

  1. Forced server-side encryption at rest for the S3 bucket
  2. S3 bucket versioning to allow for Terraform state recovery in the case of accidental deletions and human errors
  3. State locking and consistency checking via DynamoDB table to prevent concurrent operations
  4. DynamoDB server-side encryption

  https://www.terraform.io/docs/backends/types/s3.html


  __NOTE:__ The operators of the module (IAM Users) must have permissions to create S3 buckets and DynamoDB tables when performing `terraform plan` and `terraform apply`

  __NOTE:__ This module cannot be used to apply changes to the `mfa_delete` feature of the bucket. Changes regarding mfa_delete can only be made manually using the root credentials with MFA of the AWS Account where the bucket resides. Please see: https://github.com/terraform-providers/terraform-provider-aws/issues/62

# How to use this project
usage: |-
  1. Define the module in your `.tf` file using local state:
     ```hcl
     terraform {
       required_version = ">= 0.11.3"
     }

     module "terraform_state_backend" {
       source        = "git::https://github.com/cloudposse/terraform-aws-tfstate-backend.git?ref=master"
       namespace     = "cp"
       stage         = "prod"
       name          = "terraform"
       attributes    = ["state"]
       region        = "us-east-1"
     }
     ```

  1. `terraform init`

  1. `terraform apply`. This will create the state bucket and locking table.

  1. Then add a `backend` that uses the new bucket and table:
     ```hcl
     terraform {
       required_version = ">= 0.11.3"

       backend "s3" {
         region         = "us-east-1"
         bucket         = "< the name of the S3 bucket >"
         key            = "terraform.tfstate"
         dynamodb_table = "< the name of the DynamoDB table >"
         encrypt        = true
       }
     }

     module "another_module" {
       source = "....."
     }
     ```

  1. `terraform init`. Terraform will detect that you're trying to move your state into S3 and ask, "Do you want to copy existing state to the new backend?" Enter "yes". Now state is stored in the bucket and the DynamoDB table will be used to lock the state to prevent concurrent modifications.

  <br/>

  ![s3-bucket-with-terraform-state](images/s3-bucket-with-terraform-state.png)


include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors:
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Maarten van der Hoef"
    github: "maartenvanderhoef"
  - name: "Vladimir"
    github: "SweetOps"