Terraform na prática: como organizar módulos para 50+ ambientes

Quando você tem 3 ambientes, qualquer estrutura Terraform funciona. Quando você tem 50+, a organização dos módulos define se sua equipe escala ou afunda. Este artigo apresenta padrões reais para gestão de IaC em larga escala.

O problema: copy-paste de ambientes

O anti-pattern mais comum: copiar a pasta `dev/` para `staging/` e `prod/`. Funciona no início, mas gera drift inevitável quando alguém atualiza um ambiente e esquece os outros.

Estrutura de módulos recomendada

```

terraform/

├── modules/

│ ├── networking/

│ │ ├── main.tf

│ │ ├── variables.tf

│ │ └── outputs.tf

│ ├── compute/

│ ├── database/

│ └── monitoring/

├── environments/

│ ├── dev/

│ │ ├── main.tf

│ │ ├── terraform.tfvars

│ │ └── backend.tf

│ ├── staging/

│ └── prod/

└── global/

├── iam/

└── dns/

```

Princípio: módulos são genéricos; ambientes são configuração. Nunca coloque lógica de negócio nos módulos — apenas variáveis.

Remote state: S3 + DynamoDB

State local é inaceitável para times. Configure remote state com locking desde o primeiro dia.

```hcl

terraform {

backend "s3" {

bucket = "empresa-terraform-state"

key = "prod/networking/terraform.tfstate"

region = "us-east-1"

dynamodb_table = "terraform-locks"

encrypt = true

}

}

```

Dica: use um state file por componente, não um state monolítico. Isso reduz blast radius e tempo de plan/apply.

Workspaces vs Terragrunt

Terraform Workspaces

Workspaces nativos do Terraform são adequados para cenários simples: mesmo código, variáveis diferentes por ambiente.

```bash

terraform workspace new staging

terraform workspace select staging

terraform plan -var-file=staging.tfvars

```

Limitação: workspaces compartilham o mesmo backend config. Para isolamento forte entre ambientes, isso é insuficiente.

Terragrunt

Terragrunt resolve o problema de DRY (Don't Repeat Yourself) em escala.

```hcl

# terragrunt.hcl (raiz)

remote_state {

backend = "s3"

generate {

path = "backend.tf"

if_exists = "overwrite"

}

config = {

bucket = "empresa-terraform-state"

key = "${path_relative_to_include()}/terraform.tfstate"

region = "us-east-1"

dynamodb_table = "terraform-locks"

encrypt = true

}

}

```

Quando usar Terragrunt: mais de 10 ambientes, múltiplas contas AWS, necessidade de orquestração de dependências entre stacks.

Versionamento de módulos

Módulos internos devem ser versionados via Git tags. Nunca referencie `main` em produção.

```hcl

module "networking" {

source = "git::https://github.com/empresa/tf-modules.git//networking?ref=v2.3.1"

vpc_cidr = var.vpc_cidr

environment = var.environment

project_name = var.project_name

}

```

Validação e testes

Use `terraform validate`, `tflint` e `checkov` no CI. Para testes de integração, considere Terratest com ambientes efêmeros.

```bash

# Pipeline CI mínimo

terraform fmt -check

terraform validate

tflint --recursive

checkov -d .

terraform plan -out=plan.tfplan

```

Conclusão

Organização de Terraform em escala exige disciplina de engenharia de software: módulos versionados, state isolado, CI/CD automatizado e testes. Invista na fundação — refatorar IaC em produção é exponencialmente mais caro do que acertar desde o início.