Terraform Patterns

Ce skill couvre les patterns concrets pour construire un Terraform / OpenTofu codebase production-grade. Il complète l'agent terraform-engineer en fournissant des recettes prêtes à coller.

MCP server disponible : ce plugin déclare terraform dans .mcp.json (HashiCorp Docker MCP). Claude Code peut introspecter Terraform Cloud / Enterprise workspaces directement.

1. Structure de projet recommandée

infrastructure/
├── modules/                    # Modules réutilisables locaux
│   ├── vpc/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── versions.tf
│   │   └── README.md
│   └── eks-cluster/
├── envs/
│   ├── dev/
│   │   ├── backend.tf
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   └── prod/
└── .github/workflows/
    └── terraform.yml

Règle : modules/ contient le réutilisable, envs/<env>/ est l'instance qui appelle les modules avec ses variables.

2. HCL idiomatique

Variable avec validation

variable "environment" {
  type        = string
  description = "Deployment environment (dev, staging, prod)"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be one of: dev, staging, prod."
  }
}

variable "instance_count" {
  type        = number
  default     = 1
  description = "Number of EC2 instances to launch"

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 10
    error_message = "instance_count must be between 1 and 10."
  }
}

Locals pour la composition

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

  common_tags = {
    Project     = var.project
    Environment = var.environment
    ManagedBy   = "terraform"
    Owner       = var.owner
  }

  is_prod = var.environment == "prod"

  instance_type = local.is_prod ? "m5.large" : "t3.micro"
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = local.instance_type

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-web"
  })
}

for_each vs count

# count: pour des quantités
resource "aws_instance" "workers" {
  count         = var.worker_count
  ami           = data.aws_ami.amazon_linux.id
  instance_type = "t3.medium"

  tags = { Name = "worker-${count.index}" }
}

# for_each: pour des sets nommés (PRÉFÉRÉ quand applicable)
resource "aws_instance" "workers" {
  for_each = toset(["api", "worker", "scheduler"])

  ami           = data.aws_ami.amazon_linux.id
  instance_type = "t3.medium"

  tags = { Name = each.key }
}

# for_each avec map (encore mieux)
locals {
  workers = {
    api       = { instance_type = "t3.medium", disk_size = 50 }
    worker    = { instance_type = "t3.large", disk_size = 100 }
    scheduler = { instance_type = "t3.small", disk_size = 30 }
  }
}

resource "aws_instance" "workers" {
  for_each = local.workers

  ami           = data.aws_ami.amazon_linux.id
  instance_type = each.value.instance_type

  root_block_device {
    volume_size = each.value.disk_size
  }

  tags = { Name = each.key }
}

Avantage for_each : ajouter/retirer un élément n'affecte pas les autres (avec count, retirer le worker [1] décale tous les suivants → recreate).

Dynamic blocks

resource "aws_security_group" "web" {
  name = "${local.name_prefix}-web"

  dynamic "ingress" {
    for_each = var.allowed_ports

    content {
      from_port   = ingress.value.port
      to_port     = ingress.value.port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
      description = ingress.value.description
    }
  }

  tags = local.common_tags
}

3. Backend remote (obligatoire en équipe)

AWS S3 + DynamoDB lock

# envs/prod/backend.tf
terraform {
  backend "s3" {
    bucket         = "company-tf-state-prod"
    key            = "infrastructure/main.tfstate"
    region         = "eu-west-3"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

Setup initial du backend :

# bootstrap/main.tf — à apply UNE FOIS avant tout, avec un state local
resource "aws_s3_bucket" "tf_state" {
  bucket = "company-tf-state-prod"
}

resource "aws_s3_bucket_versioning" "tf_state" {
  bucket = aws_s3_bucket.tf_state.id
  versioning_configuration { status = "Enabled" }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "tf_state" {
  bucket = aws_s3_bucket.tf_state.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

resource "aws_dynamodb_table" "tf_locks" {
  name         = "terraform-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

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

GCS

terraform {
  backend "gcs" {
    bucket = "company-tf-state-prod"
    prefix = "infrastructure"
  }
}

GCS a un locking natif via Cloud Storage Object Locking — pas besoin de DynamoDB equivalent.

4. Module design

Structure standard

modules/vpc/
├── main.tf         # Resources principales
├── variables.tf    # Inputs
├── outputs.tf      # Outputs
├── versions.tf     # required_providers + required_version
└── README.md       # Doc auto-générée par terraform-docs

versions.tf

terraform {
  required_version = ">= 1.5.0"

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

Pin de version dans le consumer

# envs/prod/main.tf
module "vpc" {
  source = "git::https://github.com/myorg/terraform-modules.git//vpc?ref=v1.2.3"

  cidr_block = "10.0.0.0/16"
  azs        = ["eu-west-3a", "eu-west-3b", "eu-west-3c"]

  tags = local.common_tags
}

Toujours pinner par tag (?ref=v1.2.3), jamais ?ref=main qui peut casser.

Outputs

# modules/vpc/outputs.tf
output "vpc_id" {
  value       = aws_vpc.this.id
  description = "ID of the VPC"
}

output "private_subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "IDs of the private subnets"
}

output "public_subnet_ids" {
  value       = aws_subnet.public[*].id
  description = "IDs of the public subnets"
}

5. Workspaces vs directory-per-env

Approche 1 — Workspaces (déconseillée pour les vraies prods)

terraform workspace new dev
terraform workspace new prod
terraform workspace select prod
terraform apply

Problèmes :

• Risque d'apply sur le mauvais env (oubli de workspace select)
• Le code est partagé → différences de config tortueuses (if workspace == "prod" partout)
• Les backends sont partagés → fragile

Approche 2 — Directory-per-env (recommandée)

envs/
├── dev/
├── staging/
└── prod/

Chaque dir a son propre backend.tf, ses propres variables, son propre state.

Avantages :

• Plus sûr (impossible de se tromper d'env)
• Plus simple à raisonner
• Backups séparés

Inconvénient : duplication de code → mitigée par Terragrunt.

Terragrunt (DRY pour multi-env)

# terragrunt.hcl (root)
remote_state {
  backend = "s3"
  config = {
    bucket         = "company-tf-state-${path_relative_to_include()}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "eu-west-3"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# live/prod/vpc/terragrunt.hcl
include "root" { path = find_in_parent_folders() }

terraform {
  source = "git::https://github.com/myorg/terraform-modules.git//vpc?ref=v1.2.3"
}

inputs = {
  cidr_block  = "10.0.0.0/16"
  environment = "prod"
}

cd live/prod/vpc
terragrunt apply

6. Refactoring sécurisé

moved blocks (Terraform 1.1+)

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

resource "aws_instance" "web_server" {
  # ...
}

terraform plan voit le rename comme un no-op (pas de destroy/create).

import blocks (Terraform 1.5+)

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

resource "aws_s3_bucket" "legacy" {
  bucket = "my-existing-bucket"
}

Workflow :

1. Écrire le import block + une définition resource minimale
2. terraform plan → voit les diffs entre la config et la réalité
3. Itérer sur la config pour matcher la réalité
4. terraform apply → l'import est enregistré

7. Policy-as-code avec OPA / Conftest

# policies/no_public_s3.rego
package terraform

deny[msg] {
    resource := input.resource_changes[_]
    resource.type == "aws_s3_bucket"
    resource.change.after.acl == "public-read"
    msg := sprintf("S3 bucket '%s' must not be public-read", [resource.address])
}

deny[msg] {
    resource := input.resource_changes[_]
    resource.type == "aws_s3_bucket"
    not resource.change.after.server_side_encryption_configuration
    msg := sprintf("S3 bucket '%s' must have encryption enabled", [resource.address])
}

terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
conftest test tfplan.json -p policies/

8. CI/CD (GitHub Actions)

name: Terraform

on:
  pull_request:
    paths: ['envs/**', 'modules/**']

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  plan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env: [dev, staging, prod]
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/terraform-${{ matrix.env }}
          aws-region: eu-west-3

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.7.0

      - run: terraform fmt -check -recursive
      - run: terraform init
        working-directory: envs/${{ matrix.env }}

      - run: terraform validate
        working-directory: envs/${{ matrix.env }}

      - run: terraform plan -out=tfplan
        working-directory: envs/${{ matrix.env }}

      - name: Conftest
        run: conftest test envs/${{ matrix.env }}/tfplan -p policies/

      - name: Comment plan on PR
        uses: actions/github-script@v7
        # ... post plan output as PR comment

9. terraform-docs

brew install terraform-docs
terraform-docs markdown table modules/vpc/ > modules/vpc/README.md

À ajouter en pre-commit hook :

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: v0.17.0
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./modules"]

Anti-patterns

1. State local committé en Git — secrets exposés, conflicts garantis
2. terraform apply sans plan — changements non-revus
3. Provider non pinné — breaking changes au prochain init
4. Modules non versionnés (?ref=main) — casse aléatoire
5. Hard-coded values — impossible à porter
6. Workspaces pour des envs très différents — préférer directory-per-env
7. Secrets dans le state non chiffré — fuite via S3 mal configuré
8. Pas de policy-as-code — S3 publics, IAM trop permissif
9. Apply en local plutôt qu'en CI — pas de traçabilité
10. Pas de drift detection — code et réalité divergent silencieusement
11. Pas de tagging cohérent — facture cloud incompréhensible
12. force_destroy = true sur S3/RDS — perte de données possible

Checklist

• Backend remote chiffré + locked
• Provider versions pinnées
• Modules versionnés par tag
• Variables avec validation
• Outputs documentés
• Tags cohérents partout
• Policy-as-code (OPA/Sentinel)
• CI plan-then-apply
• Drift detection auto
• State backup régulier
• terraform-docs auto-généré
• Tests Terratest pour les modules critiques
• DR plan testé

Quand déléguer

• Architecture cloud large → skill cloud-architecture (ce plugin)
• K8s manifests → skill kubernetes-patterns (ce plugin)
• Agent terraform pour décisions → terraform-engineer (ce plugin)
• CI/CD général → agent ci-cd-engineer (atum-stack-backend)

Ressources

• https://developer.hashicorp.com/terraform/docs
• https://opentofu.org/docs/
• https://terragrunt.gruntwork.io/
• https://www.openpolicyagent.org/docs/latest/terraform/
• https://terraform-docs.io/