Move State to S3 with Locking

1. 1

   Write the bootstrap configuration

   A separate folder with its own providers. prevent_destroy means even terraform destroy in this folder fails, which you want for the bucket holding every state file you own. noncurrent_version_expiration keeps 90 days of old state versions without growing forever.

   terraform {
     required_version = ">= 1.10"
     required_providers {
       aws    = { source = "hashicorp/aws", version = "~> 6.0" }
       random = { source = "hashicorp/random", version = "~> 3.6" }
     }
   }
   
   provider "aws" {
     region = "ap-south-1"
     default_tags {
       tags = { Project = "shoplite", ManagedBy = "terraform", Stack = "bootstrap" }
     }
   }
   
   resource "random_id" "suffix" {
     byte_length = 2
   }
   
   resource "aws_s3_bucket" "tfstate" {
     bucket = "shoplite-tfstate-${random_id.suffix.hex}"
   
     lifecycle {
       prevent_destroy = true
     }
   }
   
   resource "aws_s3_bucket_versioning" "tfstate" {
     bucket = aws_s3_bucket.tfstate.id
     versioning_configuration {
       status = "Enabled"
     }
   }
   
   resource "aws_s3_bucket_server_side_encryption_configuration" "tfstate" {
     bucket = aws_s3_bucket.tfstate.id
     rule {
       apply_server_side_encryption_by_default {
         sse_algorithm = "aws:kms"
       }
       bucket_key_enabled = true
     }
   }
   
   resource "aws_s3_bucket_public_access_block" "tfstate" {
     bucket                  = aws_s3_bucket.tfstate.id
     block_public_acls       = true
     block_public_policy     = true
     ignore_public_acls      = true
     restrict_public_buckets = true
   }
   
   resource "aws_s3_bucket_lifecycle_configuration" "tfstate" {
     bucket = aws_s3_bucket.tfstate.id
     rule {
       id     = "expire-old-state-versions"
       status = "Enabled"
       filter {}
       noncurrent_version_expiration {
         noncurrent_days = 90
       }
     }
   }
   
   output "state_bucket" {
     value = aws_s3_bucket.tfstate.bucket
   }

2. 2

   Apply the bootstrap with local state

   This is the only apply in the course that deliberately uses local state. Note the bucket name from the output; you'll use it in two backend blocks.

   terminalcopy cmd

   $ cd ../bootstrap

   terraform init && terraform apply

   ── expected output ──

   ...

   Plan: 6 to add, 0 to change, 0 to destroy.

   ...

   Apply complete! Resources: 6 added, 0 changed, 0 destroyed.

    

   Outputs:

    

   state_bucket = "shoplite-tfstate-c41e"

3. 3

   Move the bootstrap's own state into the bucket

   Add a backend block, using the literal bucket name because backend blocks can't use variables, and re-run init. Terraform detects the backend change and offers to copy the existing local state. Answer yes. Afterwards the local terraform.tfstate is empty and can be deleted.

   terraform {
     backend "s3" {
       bucket       = "shoplite-tfstate-c41e"
       key          = "bootstrap/terraform.tfstate"
       region       = "ap-south-1"
       encrypt      = true
       use_lockfile = true
     }
   }

   terminalcopy cmd

   $ terraform init -migrate-state

   ── expected output ──

   Initializing the backend...

   Do you want to copy existing state to the new backend?

   Pre-existing state was found while migrating the previous "local" backend to the

   newly configured "s3" backend. No existing state was found in the newly

   configured "s3" backend. Do you want to copy this state to the new "s3"

   backend? Enter "yes" to copy and "no" to start with an empty state.

    

   Enter a value: yes

    

   Successfully configured the backend "s3"! Terraform will automatically

   use this backend unless the backend configuration changes.

4. 4

   Point ShopLite at the bucket and migrate

   Same pattern for the main config, with a different key. The key encodes project and environment, a convention Stage 6 relies on.

   terraform {
     backend "s3" {
       bucket       = "shoplite-tfstate-c41e"
       key          = "shoplite/dev/terraform.tfstate"
       region       = "ap-south-1"
       encrypt      = true
       use_lockfile = true
     }
   }

   terminalcopy cmd

   $ cd ../infra

   terraform init -migrate-state

   terraform plan

   ── expected output ──

   Successfully configured the backend "s3"! Terraform will automatically

   use this backend unless the backend configuration changes.

   ...

   No changes. Your infrastructure matches the configuration.

5. 5

   Delete the local copies and check the bucket

   Local state files are now stale duplicates, and keeping them only invites someone to use them by accident. Remove them, then look at what's in S3: one object per configuration.

   terminalcopy cmd

   $ rm -f terraform.tfstate terraform.tfstate.backup ../bootstrap/terraform.tfstate*

   aws s3 ls s3://shoplite-tfstate-c41e --recursive

   ── expected output ──

   2026-09-26 11:02:17 9214 bootstrap/terraform.tfstate

   2026-09-26 11:05:41 7688 shoplite/dev/terraform.tfstate

6. 6

   See the lock object appear during an operation

   Start terraform apply and leave it at the prompt. In another terminal, list the bucket again. A .tflock object exists for as long as the operation runs; S3's conditional writes guarantee only one process can create it. Answer no and it disappears.

   terminalcopy cmd

   $ aws s3 ls s3://shoplite-tfstate-c41e/shoplite/dev/

   ── expected output ──

   2026-09-26 11:05:41 7688 terraform.tfstate

   2026-09-26 11:09:02 233 terraform.tfstate.tflock

7. 7

   Know how to roll state back

   With versioning, every state write is recoverable. List versions, download an older one, inspect it, and, only if you're sure, push it back with terraform state push. You'll rarely need this, but it's worth knowing before an incident rather than during one.

   terminalcopy cmd

   $ aws s3api list-object-versions --bucket shoplite-tfstate-c41e \

   --prefix shoplite/dev/terraform.tfstate --query 'Versions[].[VersionId,LastModified]' --output table

   ── expected output ──

   -------------------------------------------------------------

   | ListObjectVersions |

   +-----------------------------------+-----------------------+

   | 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY| 2026-09-26T11:05:41Z |

   | 0pmRZ.S2hJ8qOy_.tW7YI7d9hxHO2Lp4 | 2026-09-26T11:05:40Z |

   +-----------------------------------+-----------------------+

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.