Infrastructure as Code — Terraform, Pulumi e CDK

Em 2017, a GitLab sofreu um incidente famoso: um engenheiro de banco de dados, tentando remediar replicação quebrada em produção, deletou acidentalmente o diretório de dados do PostgreSQL primário. O restore falhou por quatro razões: o backup automático não estava funcionando há meses, o WAL archiving estava desabilitado, a réplica de staging era do dia anterior, e o processo de restore nunca havia sido testado. Seis horas de downtime e 300 GB de dados perdidos depois, a GitLab publicou o postmortem — e mudou a forma como toda a indústria pensa sobre operação de banco de dados. O que isso tem a ver com IaC? Nenhum dos cinco sistemas de backup era gerenciado como código. Eles eram scripts manuais e configurações feitas à mão por indivíduos. Quando o indivíduo estava dormindo, os scripts não estavam rodando.

Infrastructure as Code é a prática de definir e provisionar infraestrutura através de código versionado, revisado por pares, e executado de forma idempotente — em vez de através de cliques em console ou scripts shell ad hoc. A palavra "código" implica todas as práticas que o código de aplicação já tem: version control (git), code review (pull request), testes, CI/CD, e rollback. Quando você trata infra como código, incidentes como o da GitLab ficam impossíveis por construção: você não pode ter uma configuração que "alguém fez" e que ninguém mais conhece.

Por que IaC é pré-requisito

Sem IaC, os problemas recorrentes de operação são:

• Configuration drift: o ambiente de produção diverge do staging porque alguém fez um ajuste manual em prod que nunca foi replicado. Na próxima falha, o comportamento é diferente nos dois ambientes — impossível reproduzir o problema.
• Conhecimento tribal: só uma pessoa sabe como recriar o ambiente do zero porque ela é quem fez à mão e nunca documentou. Essa pessoa entra de férias ou sai da empresa.
• Sem code review de infra: um security group com porta 22 aberta para 0.0.0.0/0 foi adicionado para "testar algo" e nunca removido. Com IaC, isso apareceria no pull request.
• Sem rollback: você mudou uma configuração de load balancer e algo quebrou, mas não há registro do estado anterior.
• Sem auditoria: quem criou aquela instância EC2 de $5000/mês? Quando? Por quê?

IaC resolve todos esses problemas porque o estado desejado da infraestrutura está em um repositório git, com histórico completo, autoria, e revisão.

Terraform — o padrão de mercado

Terraform (HashiCorp, 2014) é a ferramenta de IaC mais adotada. Usa HCL (HashiCorp Configuration Language), uma DSL declarativa orientada a blocos. Você descreve o estado desejado — não como chegar lá — e o Terraform calcula e executa o delta:

# main.tf — VPC simples com subnet pública
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
  backend "s3" {
    bucket         = "minha-empresa-terraform-state"
    key            = "producao/vpc/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock"
    encrypt        = true
  }
}

provider "aws" {
  region = var.aws_region
}

resource "aws_vpc" "main" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_hostnames = true

  tags = {
    Name        = "vpc-producao"
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

resource "aws_subnet" "public" {
  count             = length(var.availability_zones)
  vpc_id            = aws_vpc.main.id
  cidr_block        = cidrsubnet("10.0.0.0/16", 8, count.index)
  availability_zone = var.availability_zones[count.index]

  tags = {
    Name = "subnet-publica-${var.availability_zones[count.index]}"
  }
}

variable "aws_region"          { default = "us-east-1" }
variable "environment"         { default = "producao" }
variable "availability_zones"  { default = ["us-east-1a", "us-east-1b", "us-east-1c"] }

O fluxo de trabalho Terraform é sempre: terraform init → terraform plan → review humano do plan → terraform apply. O plan mostra exatamente o que vai ser criado, modificado, ou destruído — sem executar nada. Isso permite code review de mudanças de infraestrutura antes que aconteçam.

State file — a peça crítica

Terraform mantém um state file que mapeia recursos declarados no HCL para recursos reais no provider. Sem o state, o Terraform não sabe que o aws_vpc.main no seu código corresponde ao vpc-0a1b2c3d4e5f na AWS. O state é o que permite o plano de mudança incremental — e é o que mais costuma causar problemas.

State remoto com S3 + DynamoDB é o padrão para AWS:

# Criar o bucket e a tabela DynamoDB para state (bootstrap — feito uma vez, manualmente)
# O estado do estado não pode ser gerenciado pelo próprio Terraform
aws s3api create-bucket \
  --bucket minha-empresa-terraform-state \
  --region us-east-1

aws s3api put-bucket-versioning \
  --bucket minha-empresa-terraform-state \
  --versioning-configuration Status=Enabled

aws dynamodb create-table \
  --table-name terraform-state-lock \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

O S3 armazena o state com versionamento (rollback possível), e o DynamoDB fornece locking distribuído (impede dois terraform apply concorrentes no mesmo state — condição de corrida que pode corromper infra).

Workspaces e módulos

Workspaces permitem múltiplos states a partir do mesmo código HCL — tipicamente para ambientes (dev, staging, prod). A alternativa mais robusta para equipes maiores é ter diretórios separados por ambiente com módulos compartilhados:

infra/
├── modules/
│   ├── vpc/           # módulo reutilizável
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── eks-cluster/   # outro módulo
│       └── ...
├── environments/
│   ├── dev/
│   │   └── main.tf    # usa os módulos acima
│   ├── staging/
│   │   └── main.tf
│   └── prod/
│       └── main.tf

Módulos são a unidade de reuso em Terraform. Um módulo bem escrito encapsula um conjunto de recursos com uma interface de variáveis e outputs — como uma função em código de aplicação. O Terraform Registry tem módulos oficiais para VPC, EKS, RDS e praticamente qualquer serviço AWS/GCP/Azure.

OpenTofu — o fork open source

Em 2023, a HashiCorp mudou a licença do Terraform de MPL (Mozilla Public License) para BSL (Business Source License) — que proíbe uso comercial de produtos que competem com a HashiCorp. A comunidade criou o OpenTofu (fork do Terraform 1.5.x) sob a Linux Foundation. OpenTofu mantém compatibilidade total com HCL do Terraform e é a escolha para quem quer Terraform sem dependência da HashiCorp. Para uso interno (não competindo com HashiCorp), Terraform BSL é permitido — mas muitas empresas migraram para OpenTofu por princípio.

Pulumi — IaC com linguagem de programação real

O problema fundamental do HCL é que ele não é uma linguagem de programação. Loops (count, for_each), condicionais (dynamic), e abstração (módulos) existem mas são limitados. Para lógica complexa — "criar 3 security groups com regras derivadas de uma lista de serviços" — HCL fica verboso e difícil de testar.

Pulumi resolve isso usando linguagens reais: TypeScript, Python, Go, C#, Java. A infraestrutura é definida em código de verdade, com tipos, funções, loops, e testes unitários reais:

# Python — Pulumi criando cluster EKS
import pulumi
import pulumi_aws as aws
import pulumi_eks as eks

config = pulumi.Config()
env = config.get("environment", "dev")

vpc = aws.ec2.Vpc(
    f"vpc-{env}",
    cidr_block="10.0.0.0/16",
    enable_dns_hostnames=True,
    tags={"Environment": env, "ManagedBy": "pulumi"}
)

cluster = eks.Cluster(
    f"eks-{env}",
    vpc_id=vpc.id,
    subnet_ids=subnets,
    instance_type="t3.medium",
    desired_capacity=3,
    min_size=1,
    max_size=10,
)

pulumi.export("cluster_name", cluster.eks_cluster.name)
pulumi.export("kubeconfig", cluster.kubeconfig)

O workflow Pulumi é análogo ao Terraform: pulumi preview (= terraform plan) → review → pulumi up (= terraform apply). State é armazenado no Pulumi Cloud (gratuito para uso individual) ou em S3/Azure Blob/GCS para uso self-hosted.

A vantagem real do Pulumi aparece em duas situações:

1. Lógica complexa: derivar configurações de infraestrutura de uma lista de serviços, calcular CIDRs programaticamente, validar configurações antes de aplicar
2. Times de desenvolvimento: engenheiros que já sabem Python ou TypeScript não precisam aprender HCL — podem usar as ferramentas de teste (pytest, jest) que já conhecem

AWS CDK — constructs com escape hatches

O AWS Cloud Development Kit (CDK) permite definir infraestrutura AWS em TypeScript, Python, Java, ou C# — mas diferente do Pulumi, o CDK compila para CloudFormation. Isso significa que toda infra CDK é infraestrutura CloudFormation por baixo.

O modelo de abstração do CDK é baseado em constructs com três níveis:

• L1 (Cfn): mapeamento 1:1 para recursos CloudFormation — CfnBucket, CfnTable. Verboso, mas acesso total.
• L2 (padrão): abstrações com defaults seguros — Bucket, Table. Um Bucket CDK configura automaticamente criptografia, versionamento, e block public access por padrão.
• L3 (patterns): composições de múltiplos recursos para patterns comuns — ApplicationLoadBalancedFargateService cria ALB + ECS + ECR + IAM roles em uma linha.

O escape hatch permite sair de um nível para outro quando o L2/L3 não oferece o que você precisa:

import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';

const bucket = new s3.Bucket(this, 'MeuBucket', {
  encryption: s3.BucketEncryption.S3_MANAGED,
  versioned: true,
  removalPolicy: cdk.RemovalPolicy.RETAIN,
});

// Escape hatch: acessar o recurso CloudFormation subjacente
// para configurar algo que o L2 não expõe
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;
cfnBucket.addOverride('Properties.ObjectOwnership', 'BucketOwnerEnforced');

CDK é a escolha natural para equipes profundamente investidas em AWS que querem reusar componentes como bibliotecas npm/PyPI. O custo é o lock-in total em AWS e dependência de CloudFormation (com seus próprios limites de escala e depuração). Para multi-cloud ou portabilidade, Terraform ou Pulumi são mais adequados.

Comparação de ferramentas

IaC no CI/CD — plan no PR, apply no merge

IaC sem automação de CI/CD é metade do valor. O padrão completo:

# .github/workflows/terraform.yml
on:
  pull_request:
    paths: ['infra/**']
  push:
    branches: [main]
    paths: ['infra/**']

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # Para OIDC — sem AWS keys no repositório
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/github-actions-plan
          aws-region: us-east-1
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
        working-directory: infra/environments/prod
      - id: plan
        run: terraform plan -no-color -out=tfplan
        working-directory: infra/environments/prod
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              body: '## Terraform Plan\n```\n' + process.env.PLAN + '\n```'
            })

  apply:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: producao   # Requer aprovação manual configurada no GitHub
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/github-actions-apply
          aws-region: us-east-1
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init && terraform apply -auto-approve
        working-directory: infra/environments/prod

O padrão crítico aqui é OIDC para autenticação AWS: o workflow GitHub Actions não tem AWS access keys armazenadas como secrets. Em vez disso, o GitHub emite um token OIDC que a AWS troca por credenciais temporárias via AssumeRoleWithWebIdentity. As credenciais expiram após a execução — eliminando o risco de keys permanentes vazadas no repositório (ver Módulo 11 · Secrets Management).

Como praticar

1. Criar VPC com subnets públicas e privadas + Internet Gateway via Terraform. Configure um backend S3 para state remoto (pode usar LocalStack para não gerar custos). Escreva os recursos de VPC, subnets em múltiplas AZs, Internet Gateway, e route tables. Execute terraform plan e analise o output antes de aplicar.
   Critério: O terraform plan deve mostrar exatamente os recursos que serão criados antes do apply. Após o apply, terraform state list deve listar todos os recursos. Um segundo terraform apply sem mudanças deve retornar "No changes" — confirmando idempotência.
2. Refatorar código Terraform inline para módulo reutilizável. Pegue um conjunto de recursos relacionados (ex: subnet + route table + association) e extraia para um módulo com variáveis bem definidas e outputs. Instancie o módulo duas vezes com parâmetros diferentes (pública e privada) e verifique que o plan mostra as diferenças corretas.
   Critério: O módulo deve ter variables.tf com tipos e descrições, outputs.tf com os IDs dos recursos criados, e main.tf sem hardcode de valores. O código que usa o módulo deve ser significativamente menor que o original inline. O terraform plan deve mostrar zero mudanças após a refatoração (apenas reorganização, não recriação de recursos).
3. Configurar CI/CD de Terraform com plan em PR e apply no merge. Em um repositório GitHub, configure OIDC com uma conta AWS (ou LocalStack) e implemente o workflow com dois jobs: plan comentado no PR e apply automático no merge para main. Abra um PR com uma mudança de tag em um recurso existente e verifique que o plan aparece como comentário.
   Critério: O workflow de plan deve rodar em PRs e postar o output como comentário no GitHub. O workflow de apply deve rodar apenas em merges para main, usar credenciais OIDC (sem AWS_ACCESS_KEY_ID nos secrets), e completar com sucesso. Verificar no CloudTrail (ou log do LocalStack) que as credenciais usadas são temporárias (AssumedRole, não IAMUser).
4. Usar terraform import para trazer recurso existente para o state. Crie manualmente um S3 bucket via AWS CLI (simulando infra não gerenciada). Escreva o recurso correspondente em HCL e execute terraform import aws_s3_bucket.meu_bucket <nome-do-bucket>. Verifique que o plan seguinte não quer recriar o recurso — apenas as configurações que diferem do HCL escrito.
   Critério: Após o import, terraform state show aws_s3_bucket.meu_bucket deve exibir o estado atual do recurso. O terraform plan deve mostrar apenas as diferenças entre o HCL escrito e a configuração real — sem propor destroy + create do bucket inteiro.
5. Escrever um teste de infra com Terratest ou com terraform test. Para o módulo de VPC do exercício 2, escreva um teste que: cria a infra em uma conta de teste, verifica que as subnets existem e têm os CIDRs corretos, e destrói tudo ao final. Use Terratest (Go) ou o comando nativo terraform test (disponível a partir do Terraform 1.6).
   Critério: O teste deve passar em CI sem intervenção manual. Deve verificar pelo menos um atributo do recurso criado via chamada à API AWS (não apenas verificar que o plan não tem erros). Deve fazer cleanup (defer terraform.Destroy no Terratest) mesmo se o teste falhar — garantindo que recursos de teste não ficam rodando.