Using GitHub Actions to validate every change, show the plan in the pull request and apply it after an approval, authenticating to AWS with OpenID Connect instead of access keys.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. So far tofu apply has been run from a laptop. That does not work for a team: nobody knows who changed what, the result depends on the machine and long-lived AWS keys end up in many places. In a CI/CD pipeline the change goes through Git, a reviewer reads the plan, and a controlled system applies it.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. This section needs:

• the code in a GitHub repository (the examples use itwonderlab/aws-terraform-tutorial, replace it with yours),
• the S3 backend: a pipeline needs a shared state,
• the checks of Terraform Tools.

The workflow

The same code is tested and reviewed in the pull request, and nothing reaches AWS without a merge and an approval.

Step 1: remove the profile from the code

The code uses profile = "ditwl_infradmin" in the provider and in the backend. That profile does not exist in the pipeline, where the credentials come from the environment. Make it optional:

variable "aws_profile" {
  type        = string
  default     = null # in the pipeline the credentials come from the environment
  description = "AWS CLI profile, only for local runs"
}

provider "aws" {
  profile = var.aws_profile
}

For the backend, remove the profile argument from the backend "s3" block and use the AWS_PROFILE environment variable on your computer (export AWS_PROFILE=ditwl_infradmin), or a backend.hcl file as shown in the Terraform Backends section.

Step 2: let GitHub authenticate to AWS without keys

Storing an access key as a GitHub secret is the easy option and a risk: it never expires and, if it leaks, it gives access to your account. OpenID Connect (OIDC) is the alternative: AWS trusts the identity token that GitHub issues for each job and returns temporary credentials for a role.

Create the provider and the roles with Terraform, in a small project of their own (like the backend bootstrap):

locals {
  repo = "itwonderlab/aws-terraform-tutorial" # organization/repository
}

# GitHub as an identity provider
resource "aws_iam_openid_connect_provider" "github" {
  url            = "https://token.actions.githubusercontent.com"
  client_id_list = ["sts.amazonaws.com"]
}

# Role for the pull requests and the plan jobs: read only
data "aws_iam_policy_document" "ditwl-gha-plan-assume" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }
    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:${local.repo}:pull_request", "repo:${local.repo}:ref:refs/heads/main"]
    }
  }
}

resource "aws_iam_role" "ditwl-role-gha-plan" {
  name               = "ditwl-role-gha-plan"
  assume_role_policy = data.aws_iam_policy_document.ditwl-gha-plan-assume.json
}

resource "aws_iam_role_policy_attachment" "ditwl-gha-plan-readonly" {
  role       = aws_iam_role.ditwl-role-gha-plan.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

# Role for the apply job: only the jobs of the "production" environment can use it
data "aws_iam_policy_document" "ditwl-gha-apply-assume" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:${local.repo}:environment:production"]
    }
  }
}

resource "aws_iam_role" "ditwl-role-gha-apply" {
  name               = "ditwl-role-gha-apply"
  assume_role_policy = data.aws_iam_policy_document.ditwl-gha-apply-assume.json
}

# Give the apply role only the permissions that the infrastructure needs.
# PowerUserAccess is used here to keep the example short, it is too broad for production.
resource "aws_iam_role_policy_attachment" "ditwl-gha-apply-power" {
  role       = aws_iam_role.ditwl-role-gha-apply.name
  policy_arn = "arn:aws:iam::aws:policy/PowerUserAccess"
}

output "plan_role_arn" {
  value = aws_iam_role.ditwl-role-gha-plan.arn
}

output "apply_role_arn" {
  value = aws_iam_role.ditwl-role-gha-apply.arn
}

• The sub condition is the security boundary: it says which repository, and which event or environment, can assume the role. Never use repo:*.
• Both roles also need access to the state bucket (the policy from the Terraform Backends section). The plan role can be read-only if the pipeline runs tofu plan -lock=false.
• Recent versions of the AWS provider do not need a thumbprint_list for the GitHub provider. Older versions require it.
• The PowerUserAccess policy does not include IAM, which this very project needs for roles; use a custom least-privilege policy for your infrastructure.

In GitHub, create the production environment (Settings → Environments), add required reviewers and, as repository variables, AWS_PLAN_ROLE_ARN and AWS_APPLY_ROLE_ARN with the two outputs.

Step 3: the GitHub Actions workflow

name: infrastructure

on:
  pull_request:
    paths: ["**.tf", ".github/workflows/infrastructure.yml"]
  push:
    branches: [main]
    paths: ["**.tf", ".github/workflows/infrastructure.yml"]

permissions:
  contents: read
  id-token: write       # request the OIDC token
  pull-requests: write  # comment the plan

env:
  TOFU_VERSION: "1.10.0" # use the version of your team
  AWS_REGION: us-east-1

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v2
        with:
          tofu_version: ${{ env.TOFU_VERSION }}
          tofu_wrapper: false
      - run: tofu fmt -recursive -check -diff
      - run: tofu init -backend=false -input=false
      - run: tofu validate
      - uses: terraform-linters/setup-tflint@v4
      - run: tflint --init && tflint --recursive

  plan:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v2
        with:
          tofu_version: ${{ env.TOFU_VERSION }}
          tofu_wrapper: false
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_PLAN_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}
      - run: tofu init -input=false
      - run: tofu plan -input=false -lock=false -no-color -out=tfplan
      - run: tofu show -no-color tfplan > plan.txt

      - name: Comment the plan in the pull request
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require("fs");
            const plan = fs.readFileSync("plan.txt", "utf8").slice(0, 60000);
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: "### OpenTofu plan\n\n```\n" + plan + "\n```",
            });

      - name: Save the plan to apply it
        if: github.event_name == 'push'
        uses: actions/upload-artifact@v4
        with:
          name: tfplan
          path: tfplan
          retention-days: 1

  apply:
    if: github.event_name == 'push'
    needs: plan
    runs-on: ubuntu-latest
    environment: production # waits for the approval of the required reviewers
    concurrency: apply-production # one apply at a time
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v2
        with:
          tofu_version: ${{ env.TOFU_VERSION }}
          tofu_wrapper: false
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_APPLY_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}
      - uses: actions/download-artifact@v4
        with:
          name: tfplan
      - run: tofu init -input=false
      - run: tofu apply -input=false tfplan

How it works:

• validate runs the checks of the previous section in every pull request and push.
• plan assumes the read-only role and posts the plan, so the reviewers see exactly what would change in AWS.
• apply runs only after the merge, uses the environment production (the approval gate and the only identity allowed to assume the apply role) and applies the saved plan, not a new one. If the state changed in the meantime, OpenTofu rejects the stale plan and the pipeline fails safely.
• The plan file can contain sensitive values. It is kept for one day and only inside the repository's artifacts.

Protect the main branch

Pipelines are only as safe as the rules around them. In GitHub, protect main (Settings → Branches): require a pull request, require the validate and plan checks to pass, require at least one approval, and block direct pushes.

Detect drift

Infrastructure changes outside of Terraform (a person editing something in the AWS console) are called drift. A scheduled job finds it by running a plan and failing when it is not empty:

name: drift
on:
  schedule:
    - cron: "0 6 * * 1-5" # every weekday at 06:00 UTC
permissions:
  contents: read
  id-token: write
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v2
        with:
          tofu_wrapper: false
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_PLAN_ROLE_ARN }}
          aws-region: us-east-1
      - run: tofu init -input=false
      # exit code 0 = no changes, 2 = changes (drift), 1 = error
      - run: tofu plan -input=false -lock=false -detailed-exitcode

The role must allow main (or add the schedule event to the subject conditions of the plan role).

Other options

• GitLab CI/CD: the same steps with id_tokens for OIDC and the GitLab Terraform state or the S3 backend.
• Atlantis, Spacelift, env0, HCP Terraform: tools specialized in running plans and applies from pull requests, with approval policies and a UI. They replace the workflow of this section, not the S3 backend or the checks.
• AWS CodePipeline / CodeBuild: if you prefer to run everything inside AWS.

Cost

GitHub Actions includes free minutes for public repositories and a monthly allowance for private ones. These jobs take a few minutes. OIDC, IAM roles and the S3 backend have no additional cost.

Common Questions About Terraform CI/CD

Why apply the saved plan instead of running tofu apply again?

Because it guarantees that what is applied is what was planned and approved. A new apply could include changes that appeared after the review.

What if two pipelines run at the same time?

The concurrency group serializes the applies and the state lock (see Terraform Backends) prevents two processes from writing the state at once.

Where do I keep secrets such as database passwords?

Not in the repository or in the plan comments. Use manage_master_user_password = true (as in AWS RDS) or AWS Secrets Manager, and mark variables as sensitive.

Can I use access keys instead of OIDC?

You can, with repository secrets, but they are long-lived credentials that must be rotated and can leak. OIDC credentials last about an hour and are bound to the repository and the environment.

Congratulations

You have completed AWS with Terraform: The Essential Guide: from the basics of Terraform and AWS, through a network, servers, a database, DNS, auto scaling and load balancers, to modules, remote state, tooling and a CI/CD pipeline. Browse the series index to review any section, or read about using Terraform, AWS and Ansible together.

Format, validate, lint, scan, document and estimate the cost of your Terraform and OpenTofu code before it reaches AWS.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. Infrastructure code deserves the same care as application code: it should be formatted consistently, checked automatically and reviewed. The tools in this section find most problems in seconds, before tofu apply creates (and bills) anything. They work the same with Terraform and OpenTofu; the examples use tofu.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. The examples use the project with modules from Terraform Modules.

The built-in commands

OpenTofu and Terraform already include the first line of defense.

$ tofu fmt -recursive -check -diff
$ tofu init -backend=false
$ tofu validate
Success! The configuration is valid.

tofu init -backend=false downloads providers and modules without touching the remote state, which is what a validation job needs.

Try an expression with tofu console:

$ tofu console
> cidrsubnet("172.21.0.0/19", 4, 1)
"172.21.2.0/23"
> module.network.subnet_ids["ditwl-sn-za-pro-pub-00"]
"subnet-09da811e23c212363"

To see the dependencies as an image (needs Graphviz):

$ tofu graph | dot -Tsvg > graph.svg

TFLint: finds mistakes that validate cannot see

TFLint is a linter. With the AWS ruleset it detects invalid instance types, deprecated arguments, unused variables or missing required versions.

plugin "terraform" {
  enabled = true
  preset  = "recommended"
}

plugin "aws" {
  enabled = true
  version = "0.40.0" # replace with the latest release of tflint-ruleset-aws
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

$ tflint --init
$ tflint --recursive

Security scanners: Trivy and Checkov

Misconfigurations are the most common cause of cloud incidents: an open security group, a public bucket, an unencrypted volume. Static scanners read the code and report them before deployment.

• Trivy scans Terraform and OpenTofu code (it includes the rules of the former tfsec) and also container images and dependencies.
• Checkov has thousands of policies for AWS, Azure and GCP and supports custom policies.

$ trivy config .
$ checkov -d .

For example, both report the rule that the tutorial broke on purpose in AWS Security Groups: SSH (port 22) open to 0.0.0.0/0. When a finding is accepted, document the exception in the code, for example #trivy:ignore:<rule-id> or #checkov:skip=<id>:reason, so it is visible in the review.

terraform-docs: documentation that does not get old

terraform-docs generates the inputs, outputs and requirements of a module from the code. Put these markers in the README of the module:

<!-- BEGIN_TF_DOCS -->
<!-- END_TF_DOCS -->

and run:

$ terraform-docs markdown table --output-file README.md --output-mode inject modules/network

The tables between the markers are replaced and the rest of the file is kept.

Infracost: the price before the apply

Infracost estimates the monthly cost of the infrastructure from the code and, in a pull request, shows how much each change adds or saves.

$ infracost breakdown --path .
$ infracost diff --path . --compare-to infracost-base.json

It would have shown, for example, the difference between two and three NAT Gateways or the cost of the load balancer from AWS Load Balancers.

Pre-commit: run everything before every commit

The pre-commit framework runs the tools automatically when you commit. The pre-commit-terraform collection has a hook for each tool above. By default it looks for the terraform binary: the --tf-path argument selects OpenTofu.

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.99.0 # replace with the latest release
    hooks:
      - id: terraform_fmt
        args: [--hook-config=--tf-path=tofu]
      - id: terraform_validate
        args: [--hook-config=--tf-path=tofu]
      - id: terraform_tflint
      - id: terraform_trivy
      - id: terraform_docs

$ pip install pre-commit
$ pre-commit install
$ pre-commit run --all-files

The same checks run again in the pipeline of the next section, because a local hook can always be skipped.

Other useful tools

• Version managers: tenv installs and switches between OpenTofu, Terraform and Terragrunt versions, using the version in the .opentofu-version or .terraform-version file of the project.

• Import existing resources: an import block adopts a resource created by hand into the state, and tofu plan shows the result before anything is saved:

  import {
    to = aws_s3_bucket.logs
    id = "ditwl-logs-bucket"
  }

• State surgery: tofu state mv, tofu state rm and moved / removed blocks, to reorganize the code without destroying resources (see Terraform Modules).

• Debugging: TF_LOG=debug tofu plan prints the API calls and the internal decisions.

• Terragrunt: a wrapper to keep configurations DRY when there are many environments and states.

• Editor support: the OpenTofu and Terraform language servers give completion, hover documentation and diagnostics in VS Code, IntelliJ and Neovim.

A recommended order

1. tofu fmt and tofu validate: seconds, always.
2. TFLint: seconds, catches provider-specific mistakes.
3. Trivy or Checkov: seconds to a minute, security.
4. tofu plan: needs credentials, shows the real change.
5. Infracost: cost, in the pull request.

Common Questions About Terraform Tools

Do these tools work with OpenTofu?

Yes. They read the same HCL language. Where a tool expects the terraform binary, there is an option to use tofu (as in the --tf-path argument above).

Which security scanner should I choose: Trivy or Checkov?

Either one. Trivy is one tool for code, containers and dependencies; Checkov has more cloud-specific policies and custom rules in Python or YAML. Many teams run one of them and review the report of the other from time to time.

Should the checks fail the build?

Formatting, validation and linting should. For security findings start with warnings, fix the existing ones and then make new high-severity findings fail the build.

Next Steps

The code is formatted, checked and documented on every commit. The last section runs these checks, the plan and the apply automatically in a pipeline: Terraform CI/CD.

Using the Terraform and OpenTofu s3 backend to keep the state in a versioned, encrypted bucket that a whole team (and a CI/CD pipeline) can share safely.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. Terraform remembers what it created in a state file, terraform.tfstate, which by default is saved next to the code. That is fine for learning, but it becomes a problem as soon as the infrastructure is important:

• if the file is lost, Terraform no longer knows its resources,
• two people (or a person and a pipeline) running tofu apply at the same time can corrupt it,
• the state contains sensitive data (database passwords, keys) in plain text and must not be committed to Git.

A backend defines where the state is stored. This section moves it to Amazon S3.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. You need an AWS profile (ditwl_infradmin, see Terraform AWS Provider) with permissions to create an S3 bucket.

Terraform backends

The backend is configured in the terraform block. The most used ones are:

The S3 backend is the most common choice on AWS: it is cheap, durable (99.999999999%), supports versioning and encryption, and uses the same IAM permissions as the rest of the infrastructure.

Step 1: create the bucket

There is a chicken-and-egg problem: the bucket that stores the state must exist before Terraform can use it, so it is created by a separate, small project (backend-bootstrap/) that keeps its own state locally. It is run once.

terraform {
  required_version = "> 1.5"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  profile = "ditwl_infradmin"
}

data "aws_caller_identity" "current" {}

locals {
  # Bucket names are global: the account number makes it unique
  bucket = "ditwl-tfstate-${data.aws_caller_identity.current.account_id}"
}

resource "aws_s3_bucket" "tfstate" {
  bucket = local.bucket

  # Deleting this bucket would delete the state of all the infrastructure
  lifecycle {
    prevent_destroy = true
  }

  tags = {
    Name = local.bucket
  }
}

# Keep every version of the state: it allows going back after a mistake
resource "aws_s3_bucket_versioning" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id
  versioning_configuration {
    status = "Enabled"
  }
}

# Encrypt the state at rest
resource "aws_s3_bucket_server_side_encryption_configuration" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

# The state is never public
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
}

# Delete old versions after 90 days
resource "aws_s3_bucket_lifecycle_configuration" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id

  rule {
    id     = "expire-old-versions"
    status = "Enabled"
    filter {}

    noncurrent_version_expiration {
      noncurrent_days = 90
    }
  }
}

# Only encrypted connections (HTTPS)
data "aws_iam_policy_document" "tfstate-tls" {
  statement {
    sid       = "DenyInsecureTransport"
    effect    = "Deny"
    actions   = ["s3:*"]
    resources = [aws_s3_bucket.tfstate.arn, "${aws_s3_bucket.tfstate.arn}/*"]

    principals {
      type        = "*"
      identifiers = ["*"]
    }

    condition {
      test     = "Bool"
      variable = "aws:SecureTransport"
      values   = ["false"]
    }
  }
}

resource "aws_s3_bucket_policy" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id
  policy = data.aws_iam_policy_document.tfstate-tls.json

  depends_on = [aws_s3_bucket_public_access_block.tfstate]
}

output "bucket" {
  value = aws_s3_bucket.tfstate.bucket
}

$ cd backend-bootstrap
$ tofu init
$ tofu apply
...
Outputs:

bucket = "ditwl-tfstate-123456789012"

Step 2: configure the backend

In the main project add the backend block (inside the same terraform block as required_providers):

terraform {
  required_version = "> 1.5"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket       = "ditwl-tfstate-123456789012"
    key          = "aws-tutorial/pro/terraform.tfstate"
    region       = "us-east-1"
    profile      = "ditwl_infradmin"
    encrypt      = true
    use_lockfile = true
  }
}

• key is the path of the state file inside the bucket. Use one key per project and environment (aws-tutorial/pro/..., aws-tutorial/dev/...) to keep the states small and independent.
• encrypt = true asks S3 to encrypt the object.
• use_lockfile = true enables native state locking: the backend creates a terraform.tfstate.tflock object next to the state while a command that changes it runs, and S3 conditional writes guarantee that only one process gets it. No other service is needed.

Step 3: migrate the state

$ tofu init -migrate-state
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. ...

  Enter a value: yes

Successfully configured the backend "s3"!

The state is now in S3. Verify it and keep the local copy until you are sure that everything works, then delete it (and make sure that *.tfstate* is in .gitignore):

$ aws s3 ls s3://ditwl-tfstate-123456789012/aws-tutorial/pro/ --profile ditwl_infradmin
$ tofu plan
$ tofu state list

Test the state locking

Run tofu apply in two terminals at the same time. The second one waits and fails with a message like this one, which shows who holds the lock:

Error: Error acquiring the state lock

Lock Info:
  ID:        0d1b2c3d-...
  Operation: OperationTypeApply
  Who:       jruiz@laptop
  Created:   2026-10-05 10:35:12 UTC

If a process dies and leaves a stale lock, release it with tofu force-unlock <ID>, only after being sure that nobody is running.

Who can access the state

The state may contain secrets, so access is controlled with IAM. This policy lets a user or pipeline use only the state of this project:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::ditwl-tfstate-123456789012",
      "Condition": { "StringLike": { "s3:prefix": ["aws-tutorial/pro/*"] } }
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::ditwl-tfstate-123456789012/aws-tutorial/pro/*"
    }
  ]
}

The lock file is stored under the same key prefix, so the policy covers it. Read-only users (for example, a pipeline that only runs tofu plan -lock=false) need just s3:GetObject and s3:ListBucket. To also encrypt the contents of the state before it is sent to S3, read How to Encrypt Terraform State with OpenTofu.

Locking with DynamoDB

For versions without native locking, create a table with a LockID key and point the backend to it:

resource "aws_dynamodb_table" "tflock" {
  name         = "ditwl-tflock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

  backend "s3" {
    # ... the same arguments ...
    dynamodb_table = "ditwl-tflock"
  }

The IAM policy of the users also needs dynamodb:GetItem, dynamodb:PutItem and dynamodb:DeleteItem on the table.

Partial configuration

The backend block cannot use Terraform variables (OpenTofu allows variables and locals in recent versions). To avoid repeating values between environments, or to keep them out of the repository, leave them out of the block and pass them when initializing:

bucket = "ditwl-tfstate-123456789012"
key    = "aws-tutorial/dev/terraform.tfstate"
region = "us-east-1"

$ tofu init -backend-config=backend.hcl

AWS S3 Cost

A state file is a few kilobytes: storage, versions and requests cost a few cents a month at most. It is the cheapest insurance for your infrastructure.

Common Questions About Terraform Backends

Can I store the state in Git?

No. It contains secrets in plain text, has no locking and merging two versions of a state file is not possible.

What if I change the key or the bucket?

Terraform sees an empty state and would try to create everything again. Change the configuration and run tofu init -migrate-state so that the existing state is copied to the new location.

Should I use workspaces for the environments?

Workspaces keep several states for the same code and backend. Many teams prefer one directory (or one key) per environment because it is more explicit and avoids applying to the wrong one.

How can another project read the outputs of this one?

With the terraform_remote_state data source, which only needs read access to the state, or better with a data source of the real resource (for example aws_vpc), which does not depend on the other project's state.

Next Steps

The state is shared and protected. Continue with Terraform Tools to validate, lint and document the code.

Using Terraform and OpenTofu modules to turn the VPC, subnets, gateways and routing tables of the tutorial into a reusable building block.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. Every section so far added resources to a single file, terraform-aws-tutorial.tf. That is the best way to learn, but it does not scale: the file grows, the same patterns are copied between projects and one mistake can affect everything. A module groups resources behind a small interface of inputs (variables) and outputs, so they can be reused, tested and versioned.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. This section refactors the network created in AWS VPC, AWS Subnets, AWS Internet Gateway, AWS NAT Gateway and AWS Routing Tables.

Terraform modules

A module is a directory with Terraform files. Every Terraform project is already a module, the root module, and it can call other modules (child modules) with a module block:

• Inputs: variable blocks, set as arguments of the module block.
• Outputs: output blocks, read as module.<name>.<output>.
• Sources: a local path (./modules/network), the public registry (terraform-aws-modules/vpc/aws), a Git repository (git::https://github.com/org/repo.git//modules/network?ref=v1.2.0) or an S3 bucket.

Good modules do one thing, expose few and well-documented variables, hide implementation details and do not configure providers (the provider is inherited from the root module).

The new structure of the project

.
├── providers.tf        # terraform {} and provider "aws" {}
├── main.tf             # calls the module and the rest of the resources
├── moved.tf            # tells Terraform that the resources changed address
└── modules
    └── network
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

The goal is the same infrastructure: after the refactor, tofu plan must not create, change or destroy anything.

The network module

Input variables

variable "name_prefix" {
  type        = string
  description = "Prefix used in the names of the resources, for example ditwl"
}

variable "vpc_name" {
  type        = string
  description = "Name tag of the VPC"
}

variable "vpc_cidr_block" {
  type        = string
  description = "IPv4 CIDR block of the VPC, for example 172.21.0.0/19"

  validation {
    condition     = can(cidrnetmask(var.vpc_cidr_block))
    error_message = "vpc_cidr_block must be a valid IPv4 CIDR block, for example 172.21.0.0/19."
  }
}

variable "subnets" {
  type = map(object({
    cidr_block        = string
    availability_zone = string
    public            = bool
  }))
  description = "Subnets by name. Private subnets need a public subnet in the same Availability Zone for the NAT Gateway."

  validation {
    condition = alltrue([
      for s in var.subnets : s.public || anytrue([for p in var.subnets : p.public && p.availability_zone == s.availability_zone])
    ])
    error_message = "Every Availability Zone with a private subnet needs a public subnet."
  }
}

The subnets variable is a map: each key is the name of a subnet. A for_each over it creates all the subnets, so adding a subnet means adding one entry, not copying a resource block.

Resources

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0"
    }
  }
}

locals {
  public_subnets  = { for name, s in var.subnets : name => s if s.public }
  private_subnets = { for name, s in var.subnets : name => s if !s.public }

  # One NAT Gateway per Availability Zone, in the public subnet of that zone
  nat_subnet_by_az = { for name, s in local.public_subnets : s.availability_zone => name }
  private_azs      = toset([for s in local.private_subnets : s.availability_zone])

  # us-east-1a -> za
  zone = { for az in keys(local.nat_subnet_by_az) : az => "z${substr(az, -1, 1)}" }
}

resource "aws_vpc" "this" {
  cidr_block = var.vpc_cidr_block
  tags = {
    Name = var.vpc_name
    tool = "Terraform"
  }
}

resource "aws_subnet" "this" {
  for_each = var.subnets

  vpc_id                  = aws_vpc.this.id
  cidr_block              = each.value.cidr_block
  availability_zone       = each.value.availability_zone
  map_public_ip_on_launch = each.value.public
  tags = {
    Name = each.key
  }
}

resource "aws_internet_gateway" "this" {
  vpc_id = aws_vpc.this.id
  tags = {
    Name = "${var.name_prefix}-ig"
  }
}

resource "aws_eip" "nat" {
  for_each = local.nat_subnet_by_az

  domain = "vpc"
  tags = {
    Name = "${var.name_prefix}-eip-ngw-${local.zone[each.key]}"
  }
}

resource "aws_nat_gateway" "this" {
  for_each = local.nat_subnet_by_az

  subnet_id     = aws_subnet.this[each.value].id
  allocation_id = aws_eip.nat[each.key].id
  tags = {
    Name = "${var.name_prefix}-ngw-${local.zone[each.key]}-pub"
  }

  depends_on = [aws_internet_gateway.this]
}

# Public routing table, the main one of the VPC: access to the Internet through the Internet Gateway
resource "aws_route_table" "public" {
  vpc_id = aws_vpc.this.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.this.id
  }

  tags = {
    Name = "${var.name_prefix}-rt-pub-main"
  }
}

resource "aws_main_route_table_association" "public" {
  vpc_id         = aws_vpc.this.id
  route_table_id = aws_route_table.public.id
}

# One private routing table per Availability Zone: access to the Internet through the NAT Gateway of the zone
resource "aws_route_table" "private" {
  for_each = local.private_azs

  vpc_id = aws_vpc.this.id
  tags = {
    Name = "${var.name_prefix}-rt-priv-${local.zone[each.key]}"
  }
}

resource "aws_route" "private_nat" {
  for_each = local.private_azs

  route_table_id         = aws_route_table.private[each.key].id
  destination_cidr_block = "0.0.0.0/0"
  nat_gateway_id         = aws_nat_gateway.this[each.key].id
}

resource "aws_route_table_association" "private" {
  for_each = local.private_subnets

  subnet_id      = aws_subnet.this[each.key].id
  route_table_id = aws_route_table.private[each.value.availability_zone].id
}

Outputs

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.this.id
}

output "subnet_ids" {
  description = "IDs of all the subnets by name"
  value       = { for name, s in aws_subnet.this : name => s.id }
}

output "public_subnet_ids" {
  description = "IDs of the public subnets"
  value       = [for name, s in local.public_subnets : aws_subnet.this[name].id]
}

output "private_subnet_ids" {
  description = "IDs of the private subnets"
  value       = [for name, s in local.private_subnets : aws_subnet.this[name].id]
}

Using the module

Replace the VPC, subnet, gateway and routing table resources in terraform-aws-tutorial.tf with one module block:

module "network" {
  source = "./modules/network"

  name_prefix    = "ditwl"
  vpc_name       = "ditlw-vpc"
  vpc_cidr_block = "172.21.0.0/19"

  subnets = {
    "ditwl-sn-za-pro-pub-00" = { cidr_block = "172.21.0.0/23", availability_zone = "us-east-1a", public = true }
    "ditwl-sn-za-pro-pri-02" = { cidr_block = "172.21.2.0/23", availability_zone = "us-east-1a", public = false }
    "ditwl-sn-zb-pro-pub-04" = { cidr_block = "172.21.4.0/23", availability_zone = "us-east-1b", public = true }
    "ditwl-sn-zb-pro-pri-06" = { cidr_block = "172.21.6.0/23", availability_zone = "us-east-1b", public = false }
  }
}

The rest of the infrastructure used to reference the resources directly. Now it uses the outputs of the module:

For example, an EC2 instance now uses subnet_id = module.network.subnet_ids["ditwl-sn-za-pro-pub-00"] and a security group vpc_id = module.network.vpc_id.

Moving the existing resources: the moved block

If you run tofu plan now, Terraform sees that aws_vpc.ditlw-vpc disappeared from the code and that module.network.aws_vpc.this is new: it would destroy the whole network and create it again. A moved block tells Terraform that the resource did not change, only its address did, and the state is updated without touching the real infrastructure.

moved {
  from = aws_vpc.ditlw-vpc
  to   = module.network.aws_vpc.this
}

moved {
  from = aws_subnet.ditwl-sn-za-pro-pub-00
  to   = module.network.aws_subnet.this["ditwl-sn-za-pro-pub-00"]
}
moved {
  from = aws_subnet.ditwl-sn-za-pro-pri-02
  to   = module.network.aws_subnet.this["ditwl-sn-za-pro-pri-02"]
}
moved {
  from = aws_subnet.ditwl-sn-zb-pro-pub-04
  to   = module.network.aws_subnet.this["ditwl-sn-zb-pro-pub-04"]
}
moved {
  from = aws_subnet.ditwl-sn-zb-pro-pri-06
  to   = module.network.aws_subnet.this["ditwl-sn-zb-pro-pri-06"]
}

moved {
  from = aws_internet_gateway.ditwl-ig
  to   = module.network.aws_internet_gateway.this
}

moved {
  from = aws_eip.ditwl-eip-ngw-za
  to   = module.network.aws_eip.nat["us-east-1a"]
}
moved {
  from = aws_eip.ditwl-eip-ngw-zb
  to   = module.network.aws_eip.nat["us-east-1b"]
}
moved {
  from = aws_nat_gateway.ditwl-ngw-za-pub
  to   = module.network.aws_nat_gateway.this["us-east-1a"]
}
moved {
  from = aws_nat_gateway.ditwl-ngw-zb-pub
  to   = module.network.aws_nat_gateway.this["us-east-1b"]
}

moved {
  from = aws_route_table.ditwl-rt-pub-main
  to   = module.network.aws_route_table.public
}
moved {
  from = aws_main_route_table_association.ditwl-rta-default
  to   = module.network.aws_main_route_table_association.public
}
moved {
  from = aws_route_table.ditwl-rt-priv-za
  to   = module.network.aws_route_table.private["us-east-1a"]
}
moved {
  from = aws_route_table.ditwl-rt-priv-zb
  to   = module.network.aws_route_table.private["us-east-1b"]
}
moved {
  from = aws_route.ditwl-r-rt-priv-za-ngw-za
  to   = module.network.aws_route.private_nat["us-east-1a"]
}
moved {
  from = aws_route.ditwl-r-rt-priv-zb-ngw-zb
  to   = module.network.aws_route.private_nat["us-east-1b"]
}
moved {
  from = aws_route_table_association.ditwl-rta-za-pro-pri-02
  to   = module.network.aws_route_table_association.private["ditwl-sn-za-pro-pri-02"]
}
moved {
  from = aws_route_table_association.ditwl-rta-zb-pro-pri-06
  to   = module.network.aws_route_table_association.private["ditwl-sn-zb-pro-pri-06"]
}

Run the Terraform Plan

A new module has to be installed before it can be used:

$ tofu init
Initializing modules...
- network in modules/network

Then check the plan. Every moved resource is listed, and nothing is created or destroyed:

$ tofu plan
...
  # aws_vpc.ditlw-vpc has moved to module.network.aws_vpc.this
    resource "aws_vpc" "this" {
        id = "vpc-0361cf67e9e74acf6"
        # (14 unchanged attributes hidden)
    }
...
Plan: 0 to add, 0 to change, 0 to destroy.

Apply the plan to save the new addresses in the state:

$ tofu apply

Keep moved.tf until everyone who shares the state has applied the change, then delete it.

Public registry modules

You do not always have to write the module. The Terraform Registry and the OpenTofu Registry have thousands of them. The most popular one for this job, terraform-aws-modules/vpc/aws, builds the same network:

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0" # always pin the version

  name = "ditlw-vpc"
  cidr = "172.21.0.0/19"

  azs             = ["us-east-1a", "us-east-1b"]
  public_subnets  = ["172.21.0.0/23", "172.21.4.0/23"]
  private_subnets = ["172.21.2.0/23", "172.21.6.0/23"]

  enable_nat_gateway     = true
  one_nat_gateway_per_az = true
}

Read the code of a registry module before using it and pin its version, as it will create resources in your AWS account.

Module best practices

• One purpose per module, with a short list of variables. If a module needs 40 variables, it is probably several modules.
• Describe and validate every variable (description, type, validation) and every output.
• No provider blocks inside modules, only required_providers. The root module configures the provider.
• Use for_each over a map instead of count: adding or removing an element does not renumber the others.
• Version the modules that are shared (Git tags or a registry) and update them in a controlled way.
• Document them with a README. The Terraform Tools section shows how to generate it automatically.

Common Questions About Terraform Modules

What is the difference between a module and a workspace?

A module is a way to reuse code. A workspace is a way to keep several states for the same code (for example, one per environment). They solve different problems and can be combined.

Can a module use resources created outside of it?

Yes, but pass them as variables (for example vpc_id) instead of reading them inside the module. The module stays independent and easier to test.

How do I use the same module for several environments?

Call it several times with different inputs, from different root modules (one directory and one state per environment) or in the same one with different names.

What happens if I rename a resource inside a module?

Terraform considers it a different resource and recreates it. Add a moved block inside the module with the old and the new address.

Next Steps

The infrastructure is now organized in modules. Before sharing it with a team, the state must stop living on your computer: continue with Terraform Backends.

Using the Terraform aws_lb, aws_lb_target_group and aws_lb_listener resource blocks to distribute the traffic between the instances of an Auto Scaling group.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. The previous section created a group of front-end instances whose IP addresses change all the time. In this section an Application Load Balancer becomes the single, stable entry point: it receives the traffic from the Internet, sends it only to healthy instances and, with a certificate, serves it over HTTPS.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. This section builds on:

• AWS Auto Scaling: the group ditwl-asg-front-end,
• AWS Security Groups: the group ditwl-sg-front-end,
• AWS Route 53 (DNS): the public zone ditwl-r53-public (only for the DNS name and HTTPS).

AWS Load Balancers

Elastic Load Balancing offers several types of load balancers:

This tutorial uses an Application Load Balancer. It has four parts:

• the load balancer (aws_lb), placed in the public subnets of at least two Availability Zones,
• a security group that controls who can reach it,
• a target group (aws_lb_target_group): the list of instances that receive the traffic and the health check used to know which are healthy,
• a listener (aws_lb_listener): the port and protocol the load balancer listens on and what it does with the requests.

Definition of an Application Load Balancer with Terraform

Security groups

The load balancer accepts HTTP from the Internet. The front-end instances now accept HTTP only from the load balancer, which means nobody can reach them directly. Remove the rule ditwl-sr-internet-to-front-end-http created in the Security Groups section and add:

# Security Group for the load balancer
resource "aws_security_group" "ditwl-sg-alb-front-end" {
  name        = "ditwl-sg-alb-front-end"
  vpc_id      = aws_vpc.ditlw-vpc.id
  description = "Load balancer of the front-end servers"
}

# Allow access from the Internet to port 80 HTTP in the load balancer
resource "aws_security_group_rule" "ditwl-sr-internet-to-alb-http" {
  security_group_id = aws_security_group.ditwl-sg-alb-front-end.id
  type              = "ingress"
  from_port         = 80
  to_port           = 80
  protocol          = "tcp"
  cidr_blocks       = ["0.0.0.0/0"] # Internet
  description       = "Allow access from the Internet to port 80 in the load balancer"
}

# Allow the load balancer to reach port 80 in the front-end servers
resource "aws_security_group_rule" "ditwl-sr-alb-to-front-end-egress" {
  security_group_id        = aws_security_group.ditwl-sg-alb-front-end.id
  type                     = "egress"
  from_port                = 80
  to_port                  = 80
  protocol                 = "tcp"
  source_security_group_id = aws_security_group.ditwl-sg-front-end.id
  description              = "Allow traffic from the load balancer to the front-end servers"
}

# Allow access from the load balancer to port 80 in the front-end servers
resource "aws_security_group_rule" "ditwl-sr-alb-to-front-end-http" {
  security_group_id        = aws_security_group.ditwl-sg-front-end.id
  type                     = "ingress"
  from_port                = 80
  to_port                  = 80
  protocol                 = "tcp"
  source_security_group_id = aws_security_group.ditwl-sg-alb-front-end.id
  description              = "Allow access from the load balancer to port 80 in the front-end"
}

Referencing a security group instead of an IP range is a best practice: the rule keeps working when the load balancer changes its addresses.

Load balancer, target group and listener

# Application Load Balancer in the two public subnets
resource "aws_lb" "ditwl-alb-front-end" {
  name                       = "ditwl-alb-front-end"
  load_balancer_type         = "application"
  internal                   = false
  security_groups            = [aws_security_group.ditwl-sg-alb-front-end.id]
  subnets                    = [aws_subnet.ditwl-sn-za-pro-pub-00.id, aws_subnet.ditwl-sn-zb-pro-pub-04.id]
  drop_invalid_header_fields = true
}

# Target group: the front-end instances and how to check that they are healthy
resource "aws_lb_target_group" "ditwl-tg-front-end" {
  name                 = "ditwl-tg-front-end"
  port                 = 80
  protocol             = "HTTP"
  vpc_id               = aws_vpc.ditlw-vpc.id
  deregistration_delay = 30 # seconds to finish the requests in progress before removing an instance

  health_check {
    path                = "/"
    matcher             = "200"
    interval            = 15
    timeout             = 5
    healthy_threshold   = 2
    unhealthy_threshold = 3
  }
}

# Listener: HTTP on port 80 forwards the requests to the target group
resource "aws_lb_listener" "ditwl-lbl-front-end-http" {
  load_balancer_arn = aws_lb.ditwl-alb-front-end.arn
  port              = 80
  protocol          = "HTTP"

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.ditwl-tg-front-end.arn
  }
}

output "ditwl-alb-front-end-dns" {
  value = aws_lb.ditwl-alb-front-end.dns_name
}

Connect the Auto Scaling group to the target group

Modify the Auto Scaling group from the previous section. Two arguments change: the group registers its instances in the target group, and it uses the load balancer health check, so an instance that does not answer is replaced and not only the ones that are stopped.

resource "aws_autoscaling_group" "ditwl-asg-front-end" {
  # ... the rest of the arguments do not change ...
  target_group_arns = [aws_lb_target_group.ditwl-tg-front-end.arn]
  health_check_type = "ELB"
}

For a production environment, move the instances to the private subnets (vpc_zone_identifier = [aws_subnet.ditwl-sn-za-pro-pri-02.id, aws_subnet.ditwl-sn-zb-pro-pri-06.id]). Only the load balancer is then exposed to the Internet, and the instances use the NAT Gateways to download packages.

A DNS name for the load balancer

An alias record in the public zone points www to the load balancer. Unlike a CNAME, it is free and can also be used for the zone apex.

resource "aws_route53_record" "ditwl-r53-public-www" {
  zone_id = aws_route53_zone.ditwl-r53-public.zone_id
  name    = "www.${aws_route53_zone.ditwl-r53-public.name}"
  type    = "A"

  alias {
    name                   = aws_lb.ditwl-alb-front-end.dns_name
    zone_id                = aws_lb.ditwl-alb-front-end.zone_id
    evaluate_target_health = true
  }
}

HTTPS with AWS Certificate Manager

AWS Certificate Manager (ACM) issues free public certificates for the load balancer. The certificate is validated with a DNS record, which Terraform creates in the public zone, so the zone must be delegated and working.

# Certificate for www.demo.itwonderlab.com
resource "aws_acm_certificate" "ditwl-acm-www" {
  domain_name       = "www.${aws_route53_zone.ditwl-r53-public.name}"
  validation_method = "DNS"

  lifecycle {
    create_before_destroy = true
  }
}

# DNS records that prove that we own the domain
resource "aws_route53_record" "ditwl-r53-acm-www-validation" {
  for_each = {
    for o in aws_acm_certificate.ditwl-acm-www.domain_validation_options : o.domain_name => {
      name   = o.resource_record_name
      record = o.resource_record_value
      type   = o.resource_record_type
    }
  }

  allow_overwrite = true
  zone_id         = aws_route53_zone.ditwl-r53-public.zone_id
  name            = each.value.name
  type            = each.value.type
  records         = [each.value.record]
  ttl             = 60
}

# Wait until the certificate is issued
resource "aws_acm_certificate_validation" "ditwl-acm-www" {
  certificate_arn         = aws_acm_certificate.ditwl-acm-www.arn
  validation_record_fqdns = [for r in aws_route53_record.ditwl-r53-acm-www-validation : r.fqdn]
}

# HTTPS listener
resource "aws_lb_listener" "ditwl-lbl-front-end-https" {
  load_balancer_arn = aws_lb.ditwl-alb-front-end.arn
  port              = 443
  protocol          = "HTTPS"
  ssl_policy        = "ELBSecurityPolicy-TLS13-1-2-2021-06"
  certificate_arn   = aws_acm_certificate_validation.ditwl-acm-www.certificate_arn

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.ditwl-tg-front-end.arn
  }
}

Then allow port 443 in ditwl-sg-alb-front-end (a second aws_security_group_rule like ditwl-sr-internet-to-alb-http with port 443), and change the HTTP listener to redirect to HTTPS:

resource "aws_lb_listener" "ditwl-lbl-front-end-http" {
  load_balancer_arn = aws_lb.ditwl-alb-front-end.arn
  port              = 80
  protocol          = "HTTP"

  default_action {
    type = "redirect"
    redirect {
      port        = "443"
      protocol    = "HTTPS"
      status_code = "HTTP_301"
    }
  }
}

Run the Terraform Plan

$ tofu plan
$ tofu apply

The ALB takes a few minutes to be active and the instances need to pass the health checks before they receive traffic. Then test it:

$ tofu output ditwl-alb-front-end-dns
$ curl http://<alb-dns-name>/
front-end ip-172-21-1-35
$ curl http://<alb-dns-name>/
front-end ip-172-21-5-120

Each request can be answered by a different instance: the response shows the name of the instance that served it. Check the status of the targets in the AWS console (EC2 → Target Groups → ditwl-tg-front-end → Targets) or with aws elbv2 describe-target-health.

To destroy the infrastructure and avoid charges:

$ tofu destroy

AWS Load Balancers Cost

An Application Load Balancer is billed per hour while it exists plus per Load Balancer Capacity Unit (LCU) consumed (new connections, active connections, processed bytes and rule evaluations). A small test environment costs a few cents a day, but a forgotten load balancer is a monthly charge, so destroy it after the tests. See the Elastic Load Balancing pricing. ACM public certificates are free.

Common Questions About AWS Load Balancers

Should I use an Application or a Network Load Balancer?

Use an ALB for HTTP and HTTPS applications: it understands the requests and can route by host name or path. Use an NLB when you need static IP addresses, very low latency or protocols that are not HTTP.

How do I send different paths to different target groups?

Add aws_lb_listener_rule resources to a listener with a condition on the path (/api/*) or the host name and an action that forwards to another target group.

Why does the target group show unhealthy instances?

Check that the security group of the instances allows the traffic from the load balancer, that the application listens on the target group port and that the health_check path returns the code in matcher. The health_check_grace_period of the Auto Scaling group must be long enough for the instance to boot.

Can I terminate HTTPS in the instances instead?

You can, with an NLB in TLS passthrough mode, but terminating HTTPS in the ALB is simpler: ACM renews the certificates automatically and the instances do not handle certificates.

Next Steps

So far Terraform and AWS were used together to create the infrastructure. The next section shows how to use Terraform, AWS and Ansible together to configure the servers.

Using the Terraform aws_launch_template, aws_autoscaling_group and aws_autoscaling_policy resource blocks to run a self-healing group of EC2 instances that grows and shrinks with demand.

Welcome to our tutorial series about Terraform or OpenTofu on AWS. In the previous sections a VPC, subnets, security groups, EC2 instances, a database and DNS were defined. In this section the front-end server stops being a single instance and becomes a group of instances that AWS replaces when they fail and scales when the load changes.

Prerequisites

Read the previous sections of the tutorial, listed in the series index at the end of this page. This section reuses:

• the public subnets ditwl-sn-za-pro-pub-00 and ditwl-sn-zb-pro-pub-04 from AWS Subnets,
• the security groups ditwl-sg-base-ec2 and ditwl-sg-front-end from AWS Security Groups,
• the key pair ditwl-kp-config-user from AWS Key Pairs,
• the AMI data source ubuntu-23-04-arm64-minimal from AWS AMIs.

AWS Auto Scaling

An Amazon EC2 Auto Scaling group (ASG) is a collection of EC2 instances managed as a single unit. It keeps the number of instances between a minimum and a maximum, spreads them across Availability Zones, replaces the ones that fail their health checks and adds or removes instances following scaling policies.

Three resources are needed:

• Launch template (aws_launch_template): the blueprint of every instance in the group: AMI, instance type, key pair, security groups, user data and tags.
• Auto Scaling group (aws_autoscaling_group): how many instances, in which subnets (Availability Zones) and how to check their health.
• Scaling policy (aws_autoscaling_policy) and optionally scheduled actions (aws_autoscaling_schedule): when to add or remove instances.

What changes in the infrastructure

The EC2 section defined one front-end server, ditwl-ec-front-end-001. Instances in an Auto Scaling group are created and destroyed by AWS, so they cannot be defined one by one in Terraform and their IP addresses change. Make these changes in terraform-aws-tutorial.tf:

1. Remove (or comment out) the resource aws_instance.ditwl-ec-front-end-001. The back-end server ditwl-ec-back-end-123 is not changed.
2. Remove the Route 53 records that point to that instance (ditwl-r53-public-front-end-001 and ditwl-r53-private-front-end-001). The next section, AWS Load Balancers, adds one stable DNS name for the whole group.

Definition of an Auto Scaling group with Terraform

Launch template: ditwl-lt-front-end

# Launch template for the front-end servers
resource "aws_launch_template" "ditwl-lt-front-end" {
  name                   = "ditwl-lt-front-end"
  image_id               = data.aws_ami.ubuntu-23-04-arm64-minimal.id
  instance_type          = "t4g.micro"
  key_name               = "ditwl-kp-config-user"
  vpc_security_group_ids = [aws_security_group.ditwl-sg-base-ec2.id, aws_security_group.ditwl-sg-front-end.id]
  update_default_version = true # every change creates a new version and makes it the default

  metadata_options {
    http_endpoint = "enabled"
    http_tokens   = "required" # only IMDSv2 (session tokens) can read the instance metadata
  }

  # Cloud-init script: install a web server that shows the name of the instance
  user_data = base64encode(<<-EOT
    #!/bin/bash
    apt-get update
    apt-get install -y nginx
    echo "front-end $(hostname)" > /var/www/html/index.html
  EOT
  )

  tag_specifications {
    resource_type = "instance"
    tags = {
      "Name"        = "ditwl-ec-front-end"
      "app"         = "front-end"
      "os"          = "ubuntu"
      "environment" = "pro"
      "cost_center" = "marketing-department"
      "owner"       = "IT Wonder Lab"
    }
  }
}

• user_data must be Base64 encoded in launch templates. base64encode() takes care of it.
• http_tokens = "required" is a good security default: it disables IMDSv1, which is used in server-side request forgery attacks.
• The provider default_tags are not copied to the instances launched by an Auto Scaling group, that is why the tags are repeated in tag_specifications.

Auto Scaling group: ditwl-asg-front-end

# Auto Scaling group for the front-end servers, one or more instances in two Availability Zones
resource "aws_autoscaling_group" "ditwl-asg-front-end" {
  name                      = "ditwl-asg-front-end"
  min_size                  = 1
  max_size                  = 4
  desired_capacity          = 2
  vpc_zone_identifier       = [aws_subnet.ditwl-sn-za-pro-pub-00.id, aws_subnet.ditwl-sn-zb-pro-pub-04.id]
  health_check_type         = "EC2"
  health_check_grace_period = 120

  launch_template {
    id      = aws_launch_template.ditwl-lt-front-end.id
    version = aws_launch_template.ditwl-lt-front-end.latest_version
  }

  # Replace the instances gradually when the launch template changes (new AMI, new user data...)
  instance_refresh {
    strategy = "Rolling"
    preferences {
      min_healthy_percentage = 50
    }
  }

  # Tag applied to the group and to every instance it launches
  tag {
    key                 = "Name"
    value               = "ditwl-ec-front-end"
    propagate_at_launch = true
  }

  # The scaling policy changes the desired capacity, Terraform must not undo it
  lifecycle {
    ignore_changes = [desired_capacity]
  }
}

• min_size, max_size and desired_capacity are the lower limit, the upper limit (also a cost guardrail) and the number of instances at the start.
• vpc_zone_identifier lists one subnet per Availability Zone. The group balances the instances between them.
• version = ...latest_version makes the group change when the launch template changes, which is what triggers the instance refresh. With "$Latest" Terraform would not see any difference.

Scaling policy: keep the average CPU at 50%

# Target tracking: AWS adds or removes instances to keep the average CPU around 50%
resource "aws_autoscaling_policy" "ditwl-asp-front-end-cpu" {
  name                      = "ditwl-asp-front-end-cpu"
  autoscaling_group_name    = aws_autoscaling_group.ditwl-asg-front-end.name
  policy_type               = "TargetTrackingScaling"
  estimated_instance_warmup = 120

  target_tracking_configuration {
    predefined_metric_specification {
      predefined_metric_type = "ASGAverageCPUUtilization"
    }
    target_value = 50.0
  }
}

Target tracking works like a thermostat: it creates the CloudWatch alarms and calculates how many instances are needed. It is the simplest policy and the right choice in most cases.

Scheduled action: fewer instances at night

# Every day at 22:00 UTC reduce the group to one instance (and back to two at 06:00 UTC)
resource "aws_autoscaling_schedule" "ditwl-ass-front-end-night" {
  scheduled_action_name  = "ditwl-ass-front-end-night"
  autoscaling_group_name = aws_autoscaling_group.ditwl-asg-front-end.name
  min_size               = 1
  max_size               = 2
  desired_capacity       = 1
  recurrence             = "0 22 * * *"
}

resource "aws_autoscaling_schedule" "ditwl-ass-front-end-day" {
  scheduled_action_name  = "ditwl-ass-front-end-day"
  autoscaling_group_name = aws_autoscaling_group.ditwl-asg-front-end.name
  min_size               = 1
  max_size               = 4
  desired_capacity       = 2
  recurrence             = "0 6 * * *"
}

Run the Terraform Plan

Plan using OpenTofu

$ tofu plan

The plan creates the launch template, the Auto Scaling group, the scaling policy and the two scheduled actions, and destroys the instance ditwl-ec-front-end-001 (and the DNS records if they were defined).

Apply the changes using OpenTofu

$ tofu apply

Type yes to confirm. The group starts two instances, one in each Availability Zone. List them with the AWS CLI:

$ aws autoscaling describe-auto-scaling-groups \
    --auto-scaling-group-names ditwl-asg-front-end \
    --query 'AutoScalingGroups[0].Instances[].[InstanceId,AvailabilityZone,LifecycleState,HealthStatus]' \
    --output table --profile ditwl_infradmin

Test the self-healing

Terminate one of the instances and watch the group create a replacement in a couple of minutes, without any change in Terraform:

$ aws ec2 terminate-instances --instance-ids i-0123456789abcdef0 --profile ditwl_infradmin
$ aws autoscaling describe-scaling-activities --auto-scaling-group-name ditwl-asg-front-end \
    --max-items 3 --profile ditwl_infradmin

To see the scale-out, connect to one instance and generate CPU load (for example with stress-ng). After a few minutes the average CPU goes over 50% and the group adds instances up to max_size.

Destroy the infrastructure using OpenTofu

$ tofu destroy

AWS Auto Scaling Cost

An Auto Scaling group has no additional charge: you pay for the resources it launches (EC2 instances, EBS volumes and data transfer). The cost is therefore controlled by max_size and the instance type. Detailed CloudWatch monitoring, if enabled in the launch template, is billed separately. Check the EC2 pricing page for the current prices and remember to destroy the infrastructure after the tests.

Common Questions About AWS Auto Scaling

What is the difference between minimum, maximum and desired capacity?

min_size and max_size are the limits that no policy can cross. desired_capacity is the number of instances the group tries to have right now. Scaling policies change the desired capacity inside those limits.

Why is desired_capacity in ignore_changes?

Because AWS changes it while scaling. Without ignore_changes, the next tofu apply would reset the group to the value in the code and fight with the scaling policy.

How can I roll out a new AMI or a new version of the user data?

Change the launch template. The new version is used by new instances, and the instance_refresh block replaces the existing ones gradually, keeping at least 50% of the capacity healthy.

Can I use Spot Instances to reduce the cost?

Yes. Replace the launch_template block with a mixed_instances_policy block, which lets the group combine On-Demand and Spot capacity and several instance types. It is a good fit for stateless front-end servers.

Why not use count or for_each on aws_instance?

Terraform would create a fixed set of instances and nothing would replace a failed one or react to the load. An Auto Scaling group delegates that work to AWS.

Next Steps

The instances in the group are created and destroyed all the time and each one has a different IP address, so users need a single stable entry point. Continue with AWS Load Balancers.

A single line of Terraform can add hundreds of dollars a month: a NAT gateway, a larger RDS instance, a load balancer. Infracost reads the code or the plan and estimates the monthly cost using public cloud prices. It works with Terraform and OpenTofu, and supports AWS, Azure and Google Cloud.

Install and use

$ infracost auth login          # free API key
$ infracost breakdown --path .

Example of the output for a configuration with a NAT gateway and an EC2 instance:

 Name                                  Monthly Qty  Unit   Monthly Cost

 aws_nat_gateway.public_a
 ├─ NAT gateway                                730  hours        $36.00
 └─ Data processed                  Monthly cost depends on usage: $0.045 per GB

 aws_instance.web
 ├─ Instance usage (Linux, t3.micro)             730  hours         $7.59
 └─ root_block_device
    └─ Storage (general purpose SSD, gp3)         8  GB            $0.64

 OVERALL TOTAL                                                    $44.23

The prices and format depend on the region and on the version of the tool, so treat the example as an illustration. The estimate does not include usage-based charges (data transfer, requests) unless you provide a usage file.

Compare with the current state: diff

$ infracost breakdown --path . --format json --out-file base.json
# change the code
$ infracost diff --path . --compare-to base.json

The diff command shows the difference in monthly cost caused by your change.

Usage estimates

For resources that bill by usage, such as S3, Lambda or data transfer, create a usage file:

version: 0.1
resource_usage:
  aws_lambda_function.api:
    monthly_requests: 5000000
    request_duration_ms: 200
  aws_s3_bucket.assets:
    standard:
      storage_gb: 500
      monthly_tier_1_requests: 1000000

$ infracost breakdown --path . --usage-file infracost-usage.yml

In pull requests

Add a step to the GitHub Actions pipeline that posts the cost difference as a comment on each pull request, using the infracost/actions/setup action and infracost comment github. Reviewers then see "+$38/month" next to the code change. You can also set a policy that fails the check when the increase passes a threshold.

Keep demo and tutorial costs low

When you follow the AWS with Terraform tutorials:

• Use a separate AWS account for demos and set a budget alert in AWS Budgets.
• Run tofu destroy when you finish. The most expensive items are NAT gateways, load balancers, RDS instances and unattached Elastic IPs, which are charged by the hour.
• Prefer small instance types (t3.micro, db.t4g.micro) and check the free tier conditions for your account.
• Tag all resources (resource tagging) and use Cost Explorer to filter by tag.
• Delete forgotten resources: an old EBS volume or snapshot still costs money.

Cost estimation is part of the Terraform best practices.

When you have more than one VPC (one per environment, per team or per account), you need a way for them to talk using private IP addresses. The two main options are VPC peering and AWS Transit Gateway. The CIDR blocks of the connected VPCs must not overlap, so plan them in advance (VPC tutorial).

Comparison

VPC peering in the same account and region

resource "aws_vpc_peering_connection" "app_to_shared" {
  vpc_id      = aws_vpc.app.id
  peer_vpc_id = aws_vpc.shared.id
  auto_accept = true

  tags = {
    Name = "app-to-shared"
  }
}

auto_accept only works when both VPCs are in the same account and region. After the peering exists, add routes on both sides: the connection does nothing without them.

resource "aws_route" "app_to_shared" {
  route_table_id            = aws_route_table.app_private.id
  destination_cidr_block    = aws_vpc.shared.cidr_block
  vpc_peering_connection_id = aws_vpc_peering_connection.app_to_shared.id
}

resource "aws_route" "shared_to_app" {
  route_table_id            = aws_route_table.shared_private.id
  destination_cidr_block    = aws_vpc.app.cidr_block
  vpc_peering_connection_id = aws_vpc_peering_connection.app_to_shared.id
}

Then allow the traffic in the security groups (reference the CIDR of the other VPC). Routing is explained in routing tables.

Peering across accounts

The requester creates the connection and the owner of the other VPC accepts it, using a second provider with credentials for that account:

provider "aws" {
  alias   = "peer"
  region  = "eu-west-1"
  profile = "other-account"
}

data "aws_caller_identity" "peer" {
  provider = aws.peer
}

resource "aws_vpc_peering_connection" "cross" {
  vpc_id        = aws_vpc.app.id
  peer_vpc_id   = var.peer_vpc_id
  peer_owner_id = data.aws_caller_identity.peer.account_id
}

resource "aws_vpc_peering_connection_accepter" "cross" {
  provider                  = aws.peer
  vpc_peering_connection_id = aws_vpc_peering_connection.cross.id
  auto_accept               = true
}

Transit Gateway

resource "aws_ec2_transit_gateway" "main" {
  description                     = "Central hub"
  default_route_table_association = "enable"
  default_route_table_propagation = "enable"
  dns_support                     = "enable"

  tags = {
    Name = "ditwl-tgw"
  }
}

resource "aws_ec2_transit_gateway_vpc_attachment" "vpc" {
  for_each = {
    app    = { vpc_id = aws_vpc.app.id,    subnet_ids = aws_subnet.app_tgw[*].id }
    shared = { vpc_id = aws_vpc.shared.id, subnet_ids = aws_subnet.shared_tgw[*].id }
  }

  transit_gateway_id = aws_ec2_transit_gateway.main.id
  vpc_id             = each.value.vpc_id
  subnet_ids         = each.value.subnet_ids
}

With default association and propagation, every attached VPC can reach every other VPC. The routes inside the VPCs still need to point to the gateway:

resource "aws_route" "app_to_tgw" {
  route_table_id         = aws_route_table.app_private.id
  destination_cidr_block = "10.0.0.0/8"   # all your internal networks
  transit_gateway_id     = aws_ec2_transit_gateway.main.id

  depends_on = [aws_ec2_transit_gateway_vpc_attachment.vpc]
}

For isolation (for example production cannot reach development), disable the defaults and create separate Transit Gateway route tables and associations.

Share it across accounts

Use AWS Resource Access Manager (aws_ram_resource_share and aws_ram_principal_association) to share the Transit Gateway with other accounts in your organization (multi-account), then each account creates its attachment.

Costs

Transit Gateway charges per attachment per hour and per GB processed, so a small setup with two VPCs is much cheaper with peering. Peering has no hourly fee. Data transfer between AZs and regions applies to both. Consider VPC endpoints for access to specific services and estimate with Infracost.

OpenTofu is an open-source Infrastructure as Code (IaC) tool. You describe the infrastructure you want (networks, servers, databases, DNS records) in text files written in HCL, and OpenTofu compares it with what exists and creates, changes or deletes resources until both match. It works with AWS, Azure, Google Cloud, Kubernetes and thousands of other services through providers.

It started in 2023 as a fork of Terraform 1.5 after HashiCorp changed Terraform's license. It is governed by the Linux Foundation and is now a CNCF project, and it keeps the MPL 2.0 open-source license. For a detailed comparison read Terraform vs OpenTofu.

How it works

1. Write the configuration in .tf files.
2. tofu init downloads the providers and modules and configures the backend.
3. tofu plan reads the real state of the infrastructure and shows what will change.
4. tofu apply executes the changes and records the result in the state.
5. tofu destroy removes everything that the configuration manages.

A first example

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "eu-west-1"
}

resource "aws_s3_bucket" "example" {
  bucket = "my-unique-bucket-name-12345"
}

$ tofu init
$ tofu plan
$ tofu apply

The configuration blocks are still named terraform {}, and the files still use the .tf extension, so existing code works without changes.

Features that stand out

• State and plan encryption on the client (how to encrypt the state).
• Provider iteration with for_each and early variable evaluation for module sources and backends.
• Built-in testing with tofu test (testing).
• An open registry at registry.opentofu.org, with the same providers and modules that Terraform uses.
• A public roadmap driven by community RFCs.

Who uses it

OpenTofu is a replacement for teams that need an open-source license, that want a tool not controlled by a single company or that need state encryption. Platforms such as Spacelift, env0, Scalr and Terragrunt support it.

Start learning

1. Install OpenTofu.
2. Follow the AWS with Terraform series, which uses OpenTofu in every example.
3. If you already use Terraform, migrate your infrastructure.
4. Learn the commands and the recommended project structure.

The lifecycle block is available in every resource and changes the default behavior of the plan. For a different approach to a related problem, see avoiding instance destroy in AWS.

prevent_destroy

Makes any plan that would destroy the resource fail. Use it for databases, buckets with data and anything hard to recover:

resource "aws_db_instance" "main" {
  identifier = "ditwl-pro-db"
  # ...

  lifecycle {
    prevent_destroy = true
  }
}

It does not protect against removing the resource and its lifecycle block from the code at the same time, so it is a safety net and not a security control. Use AWS deletion protection too.

create_before_destroy

When a change forces replacement, Terraform destroys first and then creates. With create_before_destroy the new object is created first, so there is no gap:

resource "aws_launch_template" "web" {
  name_prefix   = "web-"
  image_id      = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  lifecycle {
    create_before_destroy = true
  }
}

Both objects exist for a moment, so unique names must not collide. Use name_prefix instead of name, as in the example. It is common in auto scaling groups and load balancers.

ignore_changes

Tells Terraform not to react to differences in some attributes. It is useful when another system changes them, for example autoscaling changing desired_capacity:

resource "aws_autoscaling_group" "web" {
  # ...
  desired_capacity = 2

  lifecycle {
    ignore_changes = [desired_capacity]
  }
}

Use ignore_changes = all only as a last resort, because Terraform will stop managing the resource.

replace_triggered_by

Forces the replacement of a resource when another resource or attribute changes:

resource "aws_instance" "app" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  lifecycle {
    replace_triggered_by = [aws_security_group.app.id]
  }
}

precondition and postcondition

Custom checks that fail the plan or apply with your own message:

data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"]

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"]
  }
}

resource "aws_instance" "app" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  lifecycle {
    precondition {
      condition     = data.aws_ami.ubuntu.architecture == "x86_64"
      error_message = "The AMI must be x86_64."
    }

    postcondition {
      condition     = self.public_ip != ""
      error_message = "The instance must have a public IP."
    }
  }
}

A precondition is evaluated before creating the resource and a postcondition after, with self pointing to the result.

Summary

lifecycle arguments must be literal values: they cannot use variables or expressions. Related: import, moved and removed.

Sooner or later you need to bring existing infrastructure under Terraform, rename a resource, move it into a module or stop managing it. All of these change the state and the code, but must not change the real infrastructure. Terraform (1.5 and later) and OpenTofu (1.6 and later) do it with configuration blocks that go through plan and code review, instead of the old imperative commands.

import blocks: adopt existing resources

Suppose an S3 bucket was created by hand in the console:

import {
  to = aws_s3_bucket.legacy
  id = "ditwl-legacy-bucket"
}

resource "aws_s3_bucket" "legacy" {
  bucket = "ditwl-legacy-bucket"
}

terraform plan shows that the resource will be imported, and apply adds it to the state. The id format depends on the resource and is documented at the end of each resource page in the provider documentation.

You can ask Terraform to write the resource code for you:

$ terraform plan -generate-config-out=generated.tf

Review the generated file before using it: it contains every attribute, including some computed ones that you should remove.

After the import is applied you can delete the import block. With for_each in the import block (supported in current versions) you can import many resources at once.

moved blocks: rename or relocate a resource

Renaming aws_instance.web to aws_instance.app makes Terraform destroy one and create the other. A moved block tells it that it is the same object:

moved {
  from = aws_instance.web
  to   = aws_instance.app
}

It also works to move a resource into a module, or between modules:

moved {
  from = aws_vpc.main
  to   = module.network.aws_vpc.main
}

Keep the moved blocks while there may be other users of the module with the old state, then you can remove them. Modules published for others should keep them.

removed blocks: stop managing without destroying

To remove a resource from the code without deleting the real infrastructure, use a removed block (Terraform 1.7 and OpenTofu 1.7 and later):

removed {
  from = aws_s3_bucket.legacy

  lifecycle {
    destroy = false
  }
}

The resource is forgotten by the state, and the bucket keeps existing. Without destroy = false, removing the block from the code means destroy.

The command line equivalents

Before these blocks existed the same was done with commands. You may still find them in older tutorials:

$ terraform import aws_s3_bucket.legacy ditwl-legacy-bucket
$ terraform state mv aws_instance.web aws_instance.app
$ terraform state rm aws_s3_bucket.legacy

They change the state immediately and without a plan, so they are easy to get wrong and leave nothing in the code history. Prefer the blocks, especially in a team or in a CI/CD pipeline.

Checklist

1. Back up the state (or use a versioned backend).
2. Write the block and run plan.
3. Confirm the plan says import or move, with no destroy.
4. Apply, then run plan again to confirm no changes remain.

Related: lifecycle, for_each vs count and migrating from Terraform to OpenTofu.

Sometimes Terraform thinks that a resource is fine but you know it is not: an instance with a broken configuration, a corrupted node, a failed provisioner. Other times you want to apply only part of the configuration. Three tools exist, and the first is the safest.

-replace: force recreation

$ terraform plan -replace=aws_instance.web
$ terraform apply -replace=aws_instance.web

The plan shows the resource as # aws_instance.web will be replaced, as requested and, since it goes through the normal plan, you can review exactly what will be destroyed and created before confirming. For resources with count or for_each, quote the address:

$ terraform apply -replace='aws_instance.web[1]'
$ terraform apply -replace='aws_subnet.private["b"]'

You can repeat the flag to replace several resources.

taint and untaint: the old way

terraform taint marks a resource in the state as damaged, so the next apply replaces it:

$ terraform taint aws_instance.web
$ terraform untaint aws_instance.web

It is deprecated in favor of -replace. The problem with taint is that it changes the state immediately and without a plan, so a teammate might apply while the mark is there without realizing it. Use -replace instead.

A provisioner failure (provisioners) still taints a resource automatically.

-target: apply only part of the graph

$ terraform plan -target=module.network
$ terraform apply -target=aws_security_group.web

-target limits the plan to the resource and what it depends on. It is useful in emergencies, for example to fix a broken resource when the rest of the configuration has an error, or to create a resource that a for_each depends on (see common errors).

Terraform itself warns that it is for exceptional use. The risks:

• The state and the code can diverge, because other resources that should change are skipped.
• It skips dependents, so you may leave the infrastructure in an inconsistent state.
• It becomes a habit that hides structural problems, such as a state that is too big (project structure).

Run a full plan afterwards to confirm that nothing remains. OpenTofu 1.9 and later also has -exclude, the opposite option, to leave out resources.

Other targeted operations

Recreating without downtime

If the resource serves traffic, use create_before_destroy in its lifecycle so the new one exists before the old one is deleted. With Auto Scaling, prefer an instance refresh over replacing instances by hand.

In CI/CD

Avoid -target in pipelines. Apply the saved plan of the whole configuration (GitHub Actions). Use -replace only through a reviewed manual workflow.

In August 2023 HashiCorp changed the license of Terraform from the open-source MPL 2.0 to the Business Source License (BSL 1.1). The community answered with a fork, first called OpenTF and now OpenTofu, which became a project of the Linux Foundation and was later accepted into the CNCF. OpenTofu keeps the MPL 2.0 license. HashiCorp was later acquired by IBM, but the Terraform license did not return to open source.

Both tools read the same HCL language and use the same providers and modules, so for most people the day-to-day commands are identical: tofu init, tofu plan and tofu apply.

Comparison

Features change in every release, so check the current release notes of both projects before deciding.

What the BSL license means for you

The BSL does not prevent you from using Terraform to manage your own or your customers' infrastructure. It restricts using it to build a product that competes with HashiCorp's commercial offerings. If you are a company that only deploys infrastructure, you are probably not affected, but legal teams of some companies prefer an open-source license, and some Linux distributions and cloud vendors cannot redistribute BSL software.

Differences in practice

• State encryption in OpenTofu protects the state and plan files without depending on the backend. This is a significant advantage when state contains secrets (secrets management).
• Early variable evaluation (1.8) allows variables and locals in module sources and backend configuration, something Terraform does not support.
• Provider for_each (1.9) lets you create one provider configuration per region or account in a loop.
• Terraform-only features: HCP Terraform integration, ephemeral resources and write-only arguments appeared first in Terraform (OpenTofu has since added support for ephemeral resources, check your version), and Terraform Stacks.

Compatibility and migration

OpenTofu 1.6 was compatible with Terraform 1.5 and the 1.6 series. Since then both evolve independently, so the compatibility with the latest Terraform versions can not be assumed. Migration is simple for most projects and reversible while you stay inside the common feature set. See the migration tutorial and the installation guide.

Which one should you choose?

• OpenTofu if you want an open-source license, state encryption, or you are starting a new project and have no HCP Terraform dependency.
• Terraform if you use HCP Terraform, Sentinel or Stacks, or your company has a support contract with HashiCorp.
• Either one if the team is small and nothing above matters. You can write code that works with both by avoiding exclusive features.

All the tutorials in this site run on both. See the AWS with Terraform series for a complete example.

A Terraform or OpenTofu configuration becomes reusable when it stops having fixed values inside the resources. Three blocks of HCL take care of this:

• variable: an input of the configuration or of a module.
• output: a value that the configuration returns, shown after apply and available to other configurations.
• locals: a named expression calculated inside the configuration, to avoid repeating it.

Input variables

variable "environment" {
  type        = string
  description = "Environment name"
  default     = "dev"

  validation {
    condition     = contains(["dev", "pre", "pro"], var.environment)
    error_message = "The environment must be dev, pre or pro."
  }
}

variable "instance_count" {
  type    = number
  default = 1
}

variable "tags" {
  type    = map(string)
  default = {}
}

variable "db_password" {
  type      = string
  sensitive = true
}

Use the value with var.<name>:

resource "aws_instance" "web" {
  count         = var.instance_count
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
  tags          = merge(var.tags, { Environment = var.environment })
}

Types can be string, number, bool, list(...), set(...), map(...), object({...}) and tuple([...]). A variable without default is required.

Setting the values

Terraform looks for values in this order, the last one wins:

1. The default of the variable.
2. Environment variables named TF_VAR_<name>.
3. terraform.tfvars and terraform.tfvars.json.
4. Files *.auto.tfvars and *.auto.tfvars.json, in alphabetical order.
5. -var-file and -var on the command line.

environment    = "pro"
instance_count = 3
tags = {
  Project = "demo"
}

$ tofu plan -var-file=pro.tfvars
$ TF_VAR_db_password='S3cret' tofu apply

Local values

Use locals for expressions that you repeat or to give a name to a calculation:

locals {
  name_prefix = "ditwl-${var.environment}"

  common_tags = merge(var.tags, {
    Environment = var.environment
    ManagedBy   = "opentofu"
  })
}

resource "aws_s3_bucket" "logs" {
  bucket = "${local.name_prefix}-logs"
  tags   = local.common_tags
}

Locals are not inputs: users of your module cannot change them. A good rule is to use variables for what the caller decides and locals for what is derived.

Output values

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.main.id
}

output "db_endpoint" {
  value     = aws_db_instance.main.endpoint
  sensitive = true
}

After apply the values are printed, and you can read them any time:

$ tofu output vpc_id
$ tofu output -json

In a module, the outputs are the only way to expose values to the caller: module.network.vpc_id. To read the outputs of another configuration use terraform_remote_state.

Variable validation and preconditions

validation blocks check a variable before the plan. For checks that involve resources or data sources, use precondition and postcondition inside lifecycle (see lifecycle).

File organization

By convention, a configuration has main.tf, variables.tf, outputs.tf, providers.tf and versions.tf. Terraform loads every .tf file in the directory, so the names are only a convention. See project structure.

AWS IAM decides who can do what in an AWS account. In Terraform you work with four objects: policies (what is allowed), roles (an identity that someone or something can assume), trust policies (who can assume the role) and instance profiles (how an EC2 instance uses a role). For users, see IAM users with Terraform.

The two policies of a role

Every role has:

1. A trust policy (assume role policy): which principal can assume the role (an EC2 instance, a Lambda function, another account, GitHub).
2. One or more permission policies: what the role can do once assumed.

Build policies with aws_iam_policy_document

Writing JSON by hand is error-prone. The aws_iam_policy_document data source builds it in HCL and lets you use references:

data "aws_iam_policy_document" "ec2_assume" {
  statement {
    actions = ["sts:AssumeRole"]

    principals {
      type        = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  }
}

data "aws_iam_policy_document" "read_bucket" {
  statement {
    sid       = "ListBucket"
    actions   = ["s3:ListBucket"]
    resources = [aws_s3_bucket.assets.arn]
  }

  statement {
    sid       = "ReadObjects"
    actions   = ["s3:GetObject"]
    resources = ["${aws_s3_bucket.assets.arn}/*"]
  }
}

Role, policy and attachment

resource "aws_iam_role" "app" {
  name               = "ditwl-pro-app-role"
  assume_role_policy = data.aws_iam_policy_document.ec2_assume.json
}

resource "aws_iam_policy" "read_bucket" {
  name   = "ditwl-pro-app-read-bucket"
  policy = data.aws_iam_policy_document.read_bucket.json
}

resource "aws_iam_role_policy_attachment" "read_bucket" {
  role       = aws_iam_role.app.name
  policy_arn = aws_iam_policy.read_bucket.arn
}

# AWS managed policy, for example to use Systems Manager Session Manager
resource "aws_iam_role_policy_attachment" "ssm" {
  role       = aws_iam_role.app.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
}

An alternative for permissions that belong to only one role is aws_iam_role_policy, an inline policy. Avoid aws_iam_policy_attachment (without role_), which takes exclusive ownership of the policy and can detach it from other identities.

Instance profile for EC2

EC2 instances use roles through an instance profile:

resource "aws_iam_instance_profile" "app" {
  name = "ditwl-pro-app-profile"
  role = aws_iam_role.app.name
}

resource "aws_instance" "app" {
  ami                  = data.aws_ami.ubuntu.id
  instance_type        = "t3.micro"
  iam_instance_profile = aws_iam_instance_profile.app.name
}

The application on the instance now gets temporary credentials from the metadata service. No access keys are stored on disk. See EC2 with Terraform.

Allow another account or a person to assume a role

data "aws_iam_policy_document" "cross_account" {
  statement {
    actions = ["sts:AssumeRole"]

    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::111111111111:root"]
    }

    condition {
      test     = "Bool"
      variable = "aws:MultiFactorAuthPresent"
      values   = ["true"]
    }
  }
}

The same pattern is used to give a CI/CD pipeline access: GitHub Actions with OIDC.

Permission boundaries

A permission boundary is a policy that sets the maximum permissions of a role, whatever policies are attached. It is useful when you let developers create their own roles:

resource "aws_iam_role" "developer_created" {
  name                 = "app-role"
  assume_role_policy   = data.aws_iam_policy_document.ec2_assume.json
  permissions_boundary = aws_iam_policy.boundary.arn
}

Least privilege checklist

• Name actions and resources explicitly. Avoid "Action": "*" and "Resource": "*".
• Use conditions (source VPC, MFA, tags, aws:PrincipalOrgID).
• One role per application and per environment.
• Prefer roles to users and temporary to long-lived credentials.
• Review the findings of IAM Access Analyzer and the "last used" information.
• Scan the code with Checkov or Trivy.

Next: S3 with Terraform.

The Terraform CI/CD tutorial explains the concepts. This guide shows a concrete pipeline for GitHub Actions. The key point is authentication: instead of saving an AWS access key and secret in GitHub, the workflow proves its identity to AWS with an OpenID Connect (OIDC) token and receives temporary credentials.

1. Create the OIDC provider and the role in AWS

Create these resources once, with Terraform, in the AWS account where the pipeline will deploy:

resource "aws_iam_openid_connect_provider" "github" {
  url            = "https://token.actions.githubusercontent.com"
  client_id_list = ["sts.amazonaws.com"]
}

data "aws_iam_policy_document" "assume" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:my-org/my-infra:*"]
    }
  }
}

resource "aws_iam_role" "terraform" {
  name               = "github-terraform"
  assume_role_policy = data.aws_iam_policy_document.assume.json
}

Attach to the role the IAM permissions that your code needs. Use two roles: a read-only role for plan (used in pull requests) and a write role for apply (only on main). See IAM roles and policies.

2. The workflow

name: infra

on:
  pull_request:
    paths: ["infra/**"]
  push:
    branches: [main]
    paths: ["infra/**"]

permissions:
  id-token: write   # needed to request the OIDC token
  contents: read
  pull-requests: write

env:
  AWS_REGION: eu-west-1

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra
    steps:
      - uses: actions/checkout@v4

      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.10.0

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111111111111:role/github-terraform-plan
          aws-region: ${{ env.AWS_REGION }}

      - run: tofu fmt -check -recursive
      - run: tofu init -input=false
      - run: tofu validate
      - run: tofu plan -input=false -out=tfplan

      - uses: actions/upload-artifact@v4
        with:
          name: tfplan
          path: infra/tfplan

  apply:
    needs: plan
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production        # add required reviewers in GitHub
    defaults:
      run:
        working-directory: infra
    steps:
      - uses: actions/checkout@v4

      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.10.0

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111111111111:role/github-terraform-apply
          aws-region: ${{ env.AWS_REGION }}

      - uses: actions/download-artifact@v4
        with:
          name: tfplan
          path: infra

      - run: tofu init -input=false
      - run: tofu apply -input=false tfplan

Replace the account ID, role names, region and the versions of the tools with yours. To use Terraform, replace the setup action with hashicorp/setup-terraform and the tofu commands with terraform.

How it works

• permissions: id-token: write lets the job request the OIDC token from GitHub.
• configure-aws-credentials exchanges the token for temporary credentials of the role. They expire in about an hour and are never stored.
• On pull requests only the plan job runs, with the read-only role.
• On merge to main, apply runs the saved plan (tfplan), so what is applied is exactly what was reviewed. The environment setting lets you require a manual approval.

Good practices

• Use a remote backend with locking, since two runs must never apply at the same time. Add a concurrency group to the workflow too.
• Do not print secrets: see secrets management.
• Add security scanning and tests before the plan.
• Pin third-party actions to a full commit SHA in sensitive repositories.
• Show the plan in the pull request comments with a tool such as Atlantis, Spacelift or a plan-comment action, so reviewers see the changes.

Replace terraform with tofu to use OpenTofu: every command below works in both. For explanations, see the tutorials.

Main workflow

Useful plan and apply flags

State

Prefer import, moved and removed blocks: see import, moved and removed.

Output, console and graph

$ terraform output
$ terraform output -raw vpc_id
$ terraform show
$ terraform console              # evaluate expressions
$ terraform graph | dot -Tpng > graph.png
$ terraform providers
$ terraform version

Workspaces

$ terraform workspace list
$ terraform workspace new dev
$ terraform workspace select dev
$ terraform workspace delete dev

See workspaces vs directories.

Debugging

$ export TF_LOG=DEBUG
$ export TF_LOG_PATH=terraform.log

More in how to debug Terraform.

Environment variables

HCL syntax

# Resource
resource "aws_instance" "web" {
  ami           = var.ami
  instance_type = "t3.micro"
}

# Data source
data "aws_region" "current" {}

# Variable, local and output
variable "name" { type = string }
locals { prefix = "ditwl-${var.name}" }
output "id" { value = aws_instance.web.id }

# Module
module "network" {
  source = "./modules/network"
  cidr   = "10.0.0.0/16"
}

# Meta-arguments
#   count, for_each, depends_on, provider, lifecycle

# Conditional
instance_type = var.env == "pro" ? "m6i.large" : "t3.micro"

# for expressions
names = [for s in var.subnets : upper(s)]
map   = { for k, v in var.items : k => v.id }

# Splat
ids = aws_instance.web[*].id

See for_each vs count, dynamic blocks and lifecycle.

Common functions

The full list is in Terraform functions.

AWS S3 is object storage. Since version 4 of the AWS provider, the settings of a bucket are separate resources instead of arguments of aws_s3_bucket. This guide creates a private, encrypted and versioned bucket, which is the right default.

The bucket

resource "aws_s3_bucket" "data" {
  bucket = "ditwl-pro-data-${data.aws_caller_identity.current.account_id}"

  tags = local.common_tags
}

data "aws_caller_identity" "current" {}

Bucket names are global across all AWS accounts, so adding the account ID helps to make it unique. Never use force_destroy = true in production: it deletes all objects when the bucket is destroyed.

Block all public access

resource "aws_s3_bucket_public_access_block" "data" {
  bucket = aws_s3_bucket.data.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

Enable this by default. For public websites do not open the bucket: serve it through CloudFront.

Ownership and ACLs

New buckets disable ACLs by default. Make it explicit:

resource "aws_s3_bucket_ownership_controls" "data" {
  bucket = aws_s3_bucket.data.id

  rule {
    object_ownership = "BucketOwnerEnforced"
  }
}

Encryption with KMS

S3 encrypts every object with SSE-S3 by default. To use your own KMS key:

resource "aws_kms_key" "s3" {
  description         = "Key for the data bucket"
  enable_key_rotation = true
}

resource "aws_s3_bucket_server_side_encryption_configuration" "data" {
  bucket = aws_s3_bucket.data.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = aws_kms_key.s3.arn
    }

    bucket_key_enabled = true   # reduces KMS request costs
  }
}

Versioning and lifecycle

resource "aws_s3_bucket_versioning" "data" {
  bucket = aws_s3_bucket.data.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_lifecycle_configuration" "data" {
  bucket = aws_s3_bucket.data.id

  depends_on = [aws_s3_bucket_versioning.data]

  rule {
    id     = "archive-and-expire"
    status = "Enabled"

    filter {}

    transition {
      days          = 30
      storage_class = "STANDARD_IA"
    }

    noncurrent_version_expiration {
      noncurrent_days = 90
    }

    abort_incomplete_multipart_upload {
      days_after_initiation = 7
    }
  }
}

Lifecycle rules control costs by moving old data to cheaper classes and deleting old versions.

Bucket policy: force HTTPS

data "aws_iam_policy_document" "data_bucket" {
  statement {
    sid       = "DenyInsecureTransport"
    effect    = "Deny"
    actions   = ["s3:*"]
    resources = [aws_s3_bucket.data.arn, "${aws_s3_bucket.data.arn}/*"]

    principals {
      type        = "*"
      identifiers = ["*"]
    }

    condition {
      test     = "Bool"
      variable = "aws:SecureTransport"
      values   = ["false"]
    }
  }
}

resource "aws_s3_bucket_policy" "data" {
  bucket = aws_s3_bucket.data.id
  policy = data.aws_iam_policy_document.data_bucket.json

  depends_on = [aws_s3_bucket_public_access_block.data]
}

Grant access to applications with IAM roles rather than by opening the bucket.

Several buckets

Use for_each or a module when you need the same configuration more than once.

Using S3 as a Terraform backend

The same service can store your state: see Terraform backends. Use a separate bucket for it, with versioning and no public access.

Cost

S3 charges for storage by class, requests and data transferred out. Versioning and incomplete uploads add storage cost silently, hence the lifecycle rule. Estimate with Infracost.

Verify

$ tofu apply
$ aws s3 cp hello.txt s3://ditwl-pro-data-111111111111/hello.txt
$ aws s3api get-public-access-block --bucket ditwl-pro-data-111111111111

The community project terraform-aws-modules publishes the most downloaded modules for AWS: vpc, iam, s3-bucket, eks, security-group, rds, alb, lambda and many more. They encode years of fixes and options, and are documented in the Terraform registry (OpenTofu uses the same modules from its own registry).

The trade-off: you learn less about the underlying resources and depend on module upgrades. The AWS with Terraform series writes the resources by hand to teach them, which is the right way to learn. In production, a maintained module is often the better choice.

How to use a registry module

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "ditwl-pro"
  cidr = "10.10.0.0/16"

  azs             = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
  private_subnets = ["10.10.1.0/24", "10.10.2.0/24", "10.10.3.0/24"]
  public_subnets  = ["10.10.101.0/24", "10.10.102.0/24", "10.10.103.0/24"]

  enable_nat_gateway   = true
  single_nat_gateway   = true      # cheaper, less available
  enable_dns_hostnames = true

  public_subnet_tags = {
    "kubernetes.io/role/elb" = 1
  }

  private_subnet_tags = {
    "kubernetes.io/role/internal-elb" = 1
  }

  tags = {
    Environment = "pro"
    ManagedBy   = "opentofu"
  }
}

This single block creates the VPC, subnets, internet gateway, NAT gateway and route tables that take several tutorials to write by hand. The module outputs include vpc_id, private_subnets and public_subnets.

Always pin the version (~> 5.0 allows 5.x updates but not 6.0) and read the changelog before upgrading a major version, since module upgrades can recreate resources. Run plan and review it.

EKS cluster on top of the VPC

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "ditwl-pro"
  cluster_version = "1.31"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  cluster_endpoint_public_access           = true
  enable_cluster_creator_admin_permissions = true

  eks_managed_node_groups = {
    default = {
      instance_types = ["t3.medium"]
      min_size       = 2
      max_size       = 4
      desired_size   = 2
    }
  }

  tags = {
    Environment = "pro"
  }
}

The version numbers above are examples: check the current major version and the supported Kubernetes versions in the module documentation, because the inputs change between majors. The module creates the cluster, IAM roles, security groups, an OIDC provider and the managed node group. Connect to it with:

$ aws eks update-kubeconfig --name ditwl-pro --region eu-west-1
$ kubectl get nodes

To write the cluster by hand see Terraform EKS. To install add-ons such as an ingress controller use the Helm provider, and to deploy applications use Argo CD.

Other popular modules

Checklist before using a third-party module

• Is it maintained, with recent releases and responses to issues?
• Does it pin provider versions reasonably?
• Read the code of the resources it creates: you are responsible for what it deploys.
• Pin the version and update deliberately.
• Scan it with security tools.

Cost

The example creates a NAT gateway, an EKS control plane (charged per hour) and EC2 nodes. Estimate it with Infracost and run destroy when you finish.

FinOps is the practice of managing cloud costs as an engineering concern: visibility first, then optimization, then continuous governance. The cloud makes it easy to create resources and easy to forget them. This checklist covers what has the greatest effect, in order.

1. See your costs

• Enable Cost Explorer and the Cost and Usage Report (CUR), and review the top services every month.
• Define budgets with alerts (AWS Budgets) per account and per project, at 50, 80 and 100 percent.
• Turn on Cost Anomaly Detection.
• Use a separate account per environment (multi-account), which makes costs attributable by default.

resource "aws_budgets_budget" "monthly" {
  name         = "monthly-total"
  budget_type  = "COST"
  limit_amount = "200"
  limit_unit   = "USD"
  time_unit    = "MONTHLY"

  notification {
    comparison_operator        = "GREATER_THAN"
    threshold                  = 80
    threshold_type             = "PERCENTAGE"
    notification_type          = "ACTUAL"
    subscriber_email_addresses = ["finops@example.com"]
  }
}

2. Tag everything

Costs without tags cannot be assigned. Define mandatory tags (Project, Environment, Owner, CostCenter), apply them with the provider's default_tags, and activate them as cost allocation tags in the billing console. See resource tagging and Terraform best practices.

3. Delete what you do not use

Frequent waste:

• Unattached EBS volumes and old snapshots.
• Unassociated Elastic IPs, which are charged since all public IPv4 addresses have a cost.
• Idle load balancers and NAT gateways in test environments.
• Old AMIs with their snapshots, and ECR images without a lifecycle policy.
• CloudWatch log groups with no retention.
• Demo environments left running: run tofu destroy, or schedule non-production resources to stop at night.

4. Right-size compute

• Use Compute Optimizer recommendations to find over-provisioned instances and volumes.
• Choose current generation instance types, and Graviton (arm64), which usually gives better price-performance.
• Convert gp2 volumes to gp3, which is cheaper and lets you set IOPS independently.
• Use Auto Scaling so capacity follows demand.

5. Choose the right purchase option

Commit only to what you are sure to use for the whole period, usually 60 to 70 percent of the stable baseline.

6. Reduce network costs

Network charges are often a surprise:

• A NAT gateway charges per hour and per GB processed. Add free gateway endpoints for S3 and DynamoDB, and interface endpoints only where traffic justifies them (VPC endpoints).
• Data transfer between Availability Zones and out to the Internet costs money. Keep chatty components in the same AZ when high availability allows it, and put CloudFront in front of public content.
• Use a single NAT gateway for development environments only.

7. Storage and databases

• S3 lifecycle rules and Intelligent-Tiering for old data. Delete incomplete multipart uploads.
• DynamoDB TTL and on-demand mode for spiky tables.
• Stop or snapshot and delete development RDS instances, and consider Aurora Serverless for variable loads.

8. Architecture

Serverless (Lambda, Fargate) can be cheaper for irregular traffic, and more expensive for constant high load. Measure before migrating.

9. Automate and shift left

• Estimate the cost of every change in the pull request with Infracost.
• Enforce rules with AWS Organizations SCPs (for example, deny very large instance types in sandbox).
• Review the top ten cost drivers every month with the people who own them.

Quick wins in order

1. Budgets and alerts. 2. Delete idle resources. 3. Log retention. 4. Gateway endpoints. 5. gp3 and Graviton. 6. Savings Plan for the stable base.