Modules, environments and Terraform in CI

What a module is

Every folder of .tf files is a module. The folder where you run terraform is the root module. A root module can call other modules, called child modules, to reuse a group of resources. Think of a module as a function: variables are its parameters, outputs are its return values, and the resources inside are its body.

modules/vpc/
  main.tf        # the resources: VPC, subnets, route tables
  variables.tf   # inputs: name, cidr_block, azs, public_subnets ...
  outputs.tf     # outputs: vpc_id, public_subnet_ids ...
  versions.tf    # required_providers
  README.md

Calling a module

module "vpc" {
  source = "./modules/vpc"     # a local path
  name       = "portal-${var.environment}"
  cidr_block = "10.20.0.0/16"
  azs        = ["ap-south-1a", "ap-south-1b"]
}

module "network" {
  source  = "terraform-aws-modules/vpc/aws"   # from the public Registry
  version = "~> 5.0"                          # pin a version you have tested
  # ... inputs ...
}

resource "aws_instance" "app" {
  subnet_id = module.vpc.public_subnet_ids[0]   # read a module output
  # ...
}

source can be a local path, a Git URL or a Registry address. Registry modules accept a version argument; always pin it, so an update cannot change your infrastructure without a review. The public Terraform Registry (registry.terraform.io) lists providers and community modules. Read a module's code before you trust it with production.

Structuring environments

You need dev, staging and production that are alike but separate. There are two common ways.

Many teams choose a directory per environment for production systems, because a mistake in dev cannot touch prod state, and access can differ. Whatever you choose, keep one state per environment (and often per component, such as network and database) so the "blast radius" of a bad apply stays small.

Naming and tagging

Use one naming pattern, such as project-environment-component (portal-prod-db). Tag every resource with at least project, environment, owner and cost centre. Tags let finance split the cloud bill by team and let engineers find who owns a forgotten server. On AWS, the provider's default_tags setting adds tags to every resource automatically.

The dependency lock file

terraform init writes .terraform.lock.hcl, which records the exact provider versions and checksums chosen. Commit it, so every laptop and CI runner uses the same provider build. Run terraform init -upgrade on purpose when you want newer versions, and review the change.

Terraform in CI/CD

1. On every pull request: terraform fmt -check, terraform validate, a linter such as tflint, and a security scanner such as Checkov.
2. Run terraform plan and post the plan as a comment on the pull request, so reviewers see the real effect.
3. After merge to main: apply, ideally the saved plan file. For production, require a manual approval step.
4. Give CI short-lived cloud credentials (for example OIDC federation) instead of long-lived keys stored in the repo.

terraform fmt -check -recursive
terraform init -input=false
terraform validate
tflint
checkov -d .
terraform plan -input=false -out=tfplan
# after merge and approval:
terraform apply -input=false tfplan

Policy as code means writing rules that every plan must pass, such as "no S3 bucket may be public" or "every resource needs an owner tag". Checkov and tfsec-style scanners have many built-in rules. Open Policy Agent (OPA) lets you write your own rules in a language called Rego; HCP Terraform also supports policy checks.

Terraform and OpenTofu

In August 2023 HashiCorp changed Terraform's licence from the open-source MPL to the Business Source License (BSL 1.1), which limits some commercial uses. In response, the community created OpenTofu, an open-source fork now hosted by the Linux Foundation. Its command is tofu (tofu init, tofu plan, tofu apply), and it reads the same HCL files and providers. The two have since added some different features, so check each tool's documentation before switching. For learning, the ideas in this module apply to both.

Common mistakes