Infrastructure as Code

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Provisioning or changing cloud infrastructure with Terraform or Ansible — modules, remote state, workspaces, AWS patterns, idempotent Ansible roles, GitOps with ArgoCD/Flux, drift detection, Vault secret injection.

Do Not Use When

• Vault PKI, dynamic secrets, or rotation depth is needed — load cicd-devsecops.
• The work is CI/CD pipeline construction around IaC — load cicd-pipelines or cicd-pipeline-design.
• The work is Kubernetes object authoring (Deployments, Services, Helm charts) — load kubernetes-platform.

Required Inputs

• Project context, target cloud (or self-managed Debian/Ubuntu), and the concrete change to make.
• Confirm deliverable: design, code, review, migration plan, audit, or runbook.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that the task needs.
• Apply the ordered guidance, decision rules, and acceptance criteria here instead of cherry-picking snippets.
• Make assumptions, risks, and follow-up work explicit when they matter.

Quality Standards

• Outputs are execution-oriented, concise, and consistent with the repository engineering baseline.
• Preserve existing project conventions unless this skill requires a stronger standard.
• Prefer deterministic, reviewable steps over tool-specific magic.

Outputs

• Concrete result fitted to the task: implementation guidance, review findings, ADR-style decisions, templates, or generated artifacts.
• Explicit assumptions, tradeoffs, or unresolved gaps when context is incomplete.

References

• references/terraform-modules-state.md — module skeleton, registry conventions, state commands, import, splitting state, backend choice.
• references/aws-patterns.md — VPC, ECS+ALB, RDS, S3 lifecycle, Terratest.
• references/ansible-debian.md — inventory, role layout, idempotency patterns, hardening playbook, tags.
• references/gitops-argocd-flux.md — ArgoCD Application/ApplicationSet, Flux bootstrap, drift wiring.
• references/iac-tool-selection-and-delivery.md — load when choosing IaC tool categories, deciding Terraform vs OpenTofu (licence verified 2026-09-24), or designing the PR-plan / protected-apply pipeline and state isolation.

Evidence Produced

Why IaC

Inputs

Capability contract

Author and validate code by default. Apply, destroy, import, state edits, and secret writes require explicit environment authority and a reviewed plan.

Degraded mode

If credentials or state are unavailable, run static validation and return an unverified plan checklist; never simulate apply results.

Decision rules

Domain Anti-Patterns

• Editing remote state manually. Fix: use supported commands with backup.
• Applying an unreviewed plan. Fix: approve a saved plan.
• Hardcoding secrets. Fix: inject references at runtime.
• Copying divergent environment modules. Fix: share versioned modules.
• Ignoring drift. Fix: schedule read-only plans.

Snowflake servers — hand-configured, undocumented, irreplaceable — cause outages nobody can recover from. IaC puts environments in version-controlled code, making drift a diffable artifact and rebuilds a routine operation.

§1 Terraform Fundamentals

Terraform's core blocks:

Pin provider and Terraform versions — a minor provider bump can silently change resource behaviour.

terraform {
  required_version = ">= 1.11.0" # S3 native locking (use_lockfile) needs Terraform 1.11+ / OpenTofu 1.10+
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 6.0" } # AWS provider 6.x current as of 2026-09-24
  }
  backend "s3" {
    bucket       = "acme-tfstate"
    key          = "envs/prod/main.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true   # native S3 locking — preferred
  }
}

provider "aws" { region = var.region }

variable "region"      { type = string }
variable "environment" { type = string }
variable "project" {
  type        = string
  description = "Project slug used in resource names"
  validation {
    condition     = can(regex("^[a-z0-9-]{3,20}$", var.project))
    error_message = "project must be 3-20 chars, lowercase, digits, or hyphens."
  }
}

module "network" {
  source      = "./modules/network"
  cidr        = "10.20.0.0/16"
  environment = var.environment
}

resource "aws_s3_bucket" "assets" {
  bucket = "acme-${var.environment}-assets"
  tags   = { Project = var.project, Environment = var.environment }
}

output "vpc_id"           { value = module.network.vpc_id }
output "app_bucket_name"  { value = aws_s3_bucket.assets.id }

For a full VPC + ECS + RDS + S3 lifecycle example see references/aws-patterns.md.

§2 State Management

Never commit terraform.tfstate to Git — it stores secrets in plaintext and creates merge conflicts. Use a remote backend with locking.

The HashiCorp S3-backend documentation is explicit on locking:

Locking can be enabled via S3 or DynamoDB. However, DynamoDB-based locking is deprecated. To enable S3 state locking directly, use the use_lockfile argument (set to true).

The legacy dynamodb_table argument requires a table whose partition key is LockID of type String. New configurations should use use_lockfile = true; existing configurations may run both during transition.

Backend choice:

Importing existing infrastructure:

# Bring an existing AWS S3 bucket under Terraform management
terraform import aws_s3_bucket.assets acme-prod-assets
# Then write the resource block to match — terraform plan should show no diff.

terraform state list
terraform state show aws_s3_bucket.assets
terraform state rm aws_s3_bucket.assets       # untrack without destroying

Split state per blast-radius boundary — network/, data/, app/ — and cross-reference outputs through terraform_remote_state. See references/terraform-modules-state.md.

§3 Module Design

A module is a directory of .tf files consumed via module "name" { source = "..." }. Pin to an exact Git tag — main can break you on any push.

Module skeleton:

modules/network/
  main.tf          # resources
  variables.tf     # typed, documented inputs
  outputs.tf       # exported values consumers depend on
  versions.tf      # required_providers, required_version
  README.md        # usage example, input/output table

Versioning and registry:

• Tag modules in Git with semver (v1.2.0); consumers reference by tag.
• Public modules consumed via the Terraform Registry use source = "namespace/name/provider" and version = "x.y.z".
• Registry naming convention: terraform-<PROVIDER>-<NAME> for module repositories (e.g. terraform-aws-vpc).

module "vpc_git" {
  source = "git::https://github.com/acme/tf-modules.git//modules/vpc?ref=v1.2.0"
  name   = "acme-prod"
  cidr   = "10.20.0.0/16"
  azs    = ["eu-west-1a", "eu-west-1b"]
}

module "vpc_registry" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.5.1"
  # ...
}

Composability rule of thumb: a module should do one thing — a network, a database, a service. Avoid the "everything module" — it forces consumers to accept defaults they cannot opt out of. Deeper input/output contract patterns in references/terraform-modules-state.md.

§4 Workspaces and Environments

For production SaaS, prefer directory-per-env with module composition. For small projects, workspaces are fine:

terraform workspace new prod && terraform workspace select prod
terraform apply -var-file="prod.tfvars"

locals {
  instance_size = {
    dev = "t3.micro", staging = "t3.small", prod = "m6i.large"
  }[terraform.workspace]
}

When prod must live in a separate AWS account, directory-per-env is mandatory — workspaces share backend credentials.

§5 Ansible for Debian/Ubuntu

The Ansible playbook documentation defines the model:

A playbook consists of one or more "plays" in an ordered list. Each play executes part of the overall goal of the playbook, running one or more tasks. Each task calls an Ansible module.

Each play needs hosts (the targeted managed nodes) and at least one task. Plays and tasks execute top-to-bottom; each task runs against all matched hosts before the next task starts.

Minimum nginx role and inventory:

# inventories/prod/hosts.ini
[web]
web1.example.com
web2.example.com

[debian:children]
web

[debian:vars]
ansible_user=deploy
ansible_python_interpreter=/usr/bin/python3

# roles/nginx/tasks/main.yml
- name: Ensure nginx is installed
  ansible.builtin.apt:
    name: nginx
    state: present
    update_cache: true
    cache_valid_time: 3600

- name: Deploy nginx site config
  ansible.builtin.template:
    src: site.conf.j2
    dest: /etc/nginx/sites-available/{{ site_name }}.conf
    owner: root
    group: root
    mode: "0644"
  notify: Reload nginx

# roles/nginx/handlers/main.yml
- name: Reload nginx
  ansible.builtin.service: { name: nginx, state: reloaded }

Idempotency rule: running the playbook ten times leaves the system identical to running it once. Ansible modules are idempotent by default; raw shell commands are not — use ansible.builtin.file, apt, template, systemd, and only fall back to command/shell with explicit changed_when and failed_when.

Variable precedence (most-specific wins): -e > task > block > role > play > host > group > role defaults. Dry-run before prod with ansible-playbook -i inventories/prod site.yml --check --diff.

For role layout, dynamic AWS inventory, dependency declarations, and a baseline Ubuntu hardening playbook (ufw, fail2ban, unattended-upgrades, deploy user, SSH keys), see references/ansible-debian.md.

§6 GitOps — ArgoCD and Flux

The Git repo is the single source of truth; a controller continuously reconciles the live cluster to match.

ArgoCD's documented model:

Argo CD continuously monitors running applications and compares the current, live state against the desired target state (as specified in the Git repo). Applications that deviate from this target configuration are flagged as OutOfSync.

ArgoCD syncPolicy fields:

ArgoCD also supports PreSync, Sync, and PostSync hooks for blue/green and canary rollouts, plus ApplicationSet for multi-cluster fan-out.

Flux is multi-controller and headless:

Decision rubric:

Drift detection: ArgoCD flips Application to OutOfSync natively. For Terraform-managed resources, schedule terraform plan -detailed-exitcode every 6 hours and alert on exit code 2. Concrete manifests, bootstrap commands, and notification wiring live in references/gitops-argocd-flux.md.

§7 Terraform vs Ansible Decision Matrix

Rule of thumb: Terraform creates the VPS; Ansible configures it. For Kubernetes, GitOps replaces both — Terraform creates the cluster, ArgoCD or Flux reconciles workloads from Git.

In practice the two cooperate: Terraform creates the EC2 instance and emits its IP into an Ansible inventory; Ansible installs nginx, users, firewall rules.

§8 Secrets at the IaC Boundary

Risks:

1. Secrets read by Terraform end up in plaintext inside the state file. Treat the state backend as a sensitive store — encrypt at rest, restrict IAM/ACL access, version the bucket.
2. sensitive = true on a variable or output suppresses console echo but does not encrypt state.
3. Ansible Vault encrypts variable files at rest, but the playbook process sees plaintext at runtime — secure the runner and the SSH path.

Patterns:

provider "vault" { address = "https://vault.acme.internal" }
data "vault_generic_secret" "rds" { path = "secret/data/prod/rds" }

resource "aws_db_instance" "primary" {
  username = data.vault_generic_secret.rds.data["username"]
  password = data.vault_generic_secret.rds.data["password"]
}

For Kubernetes workloads use external-secrets-operator so manifests reference a Vault path, not a literal secret:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata: { name: api-db, namespace: api-prod }
spec:
  refreshInterval: 15m
  secretStoreRef: { name: vault-backend, kind: ClusterSecretStore }
  target: { name: api-db }
  data:
    - secretKey: password
      remoteRef: { key: prod/rds, property: password }

For Ansible, run a Vault Agent sidecar that renders secrets into /etc/app/db.env and have a systemd unit source it; the playbook installs the agent, never the secret. Cross-reference: cicd-devsecops covers Vault PKI, dynamic secrets, key rotation, and encryption-at-rest. This skill only handles the IaC entry point.

IaC Repository Layout

infra/
  modules/{vpc,rds,ecs}/
  envs/
    dev/{main.tf,terraform.tfvars}
    staging/
    prod/
  ansible/{roles,playbooks,inventories}/

• main mirrors prod — a merge to main is a production change.
• Feature branches target main via PR; CI runs fmt, validate, plan on every PR and posts the plan as a PR comment.
• terraform apply against prod runs only from main after PR approval, through a protected workflow with manual approval.
• Dev and staging apply automatically on merge so feedback cycles stay short.

Companion Skills

• cloud-architecture — AWS services Terraform modules target.
• kubernetes-platform — K8s cluster Terraform often provisions and where GitOps reconciles.
• cicd-pipelines, cicd-pipeline-design — pipelines that run terraform plan/apply.
• cicd-devsecops — Vault depth, secret scanning, SBOM, IaC linting (tflint, tfsec, checkov).
• linux-security-hardening — Ansible roles that harden the OS baseline.

Sources

• Terraform documentation — developer.hashicorp.com/terraform.
• Terraform S3 backend — developer.hashicorp.com/terraform/language/backend/s3.
• Terraform GCS backend — developer.hashicorp.com/terraform/language/backend/gcs.
• Terraform Registry publishing — developer.hashicorp.com/terraform/registry/modules/publish.
• Ansible playbook intro — docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html.
• Ansible roles — docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html.
• ArgoCD — argo-cd.readthedocs.io/en/stable/.
• ArgoCD auto-sync — argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/.
• Flux concepts — fluxcd.io/flux/concepts/.
• Terratest — terratest.gruntwork.io.