AWS HubAWS HubSão Paulo operando · 2 eventos no mundo

TerraformComunidade

Nível de dificuldade: Básico (2 de 5)

Equipe reestrutura Terraform em 24 estados depois de um destroy acidental apagar o staging inteiro

Por AWS Hub9 min de leitura

O problema

O relato, publicado em novembro de 2026 na DEV Community pelo autor identificado como garrett_yan, começa num incidente concreto: às 15h47 de uma quinta-feira, um engenheiro rodou terraform destroy para limpar uma VPC de sandbox. Ele estava no workspace errado. O staging inteiro desapareceu: 47 recursos deletados em 90 segundos, incluindo a instância RDS, o cluster EKS e as conexões VPN.

A recuperação levou 6 horas, e não porque faltasse código para reconstruir a infraestrutura. O problema foi que ninguém conseguia entender rapidamente o que o state de staging realmente continha: tudo vivia num único arquivo de 50MB, com 12.000 linhas de JSON, cobrindo os 500+ recursos das 8 contas AWS da empresa ao mesmo tempo.

O destroy acidental foi só o sintoma. A causa era estrutural, e o relato lista os problemas de fundo:

  • Um terraform.tfstate monolítico cobrindo tudo, de todas as contas
  • Nenhum pipeline de CI/CD: cada engenheiro aplicava a partir do próprio laptop
  • Conflitos de lock constantes: 6 engenheiros disputando o mesmo lock do DynamoDB, 12 vezes por semana
  • Nenhum controle de raio de explosão: um terraform apply podia alterar qualquer recurso em qualquer conta
  • Nenhuma detecção de drift: mudanças feitas no console se acumulavam até o próximo plan mostrar 40 diffs inesperados
  • Planos de 15 minutos, que fizeram os engenheiros simplesmente pararem de rodar terraform plan antes de aplicar

Funcionou da última vez não é uma estratégia de implantação.

"It was fine last time" is not a deployment strategy.Garrett Yan, autor do relato publicado na DEV Community

A equipe resume o diagnóstico numa frase que vale para qualquer ambiente com múltiplas contas crescendo sem governança de estado.

Um arquivo de estado é igual a um raio de explosão, que é igual a risco máximo.

one state file = one blast radius = maximum riskGarrett Yan, autor do relato publicado na DEV Community

A arquitetura

A reconstrução levou quatro semanas e se apoiou em dois eixos: separar o estado por domínio e ambiente, e tirar o terraform apply das mãos dos engenheiros. O fluxo final, do commit até o recurso provisionado, funciona assim:

  1. O engenheiro abre uma branch e altera um diretório dentro de infrastructure/, por exemplo infrastructure/data/prod/.
  2. Um workflow do GitHub Actions detecta quais diretórios mudaram (via git diff comparado com GITHUB_OUTPUT) e dispara terraform init e terraform plan só para esses diretórios.
  3. O plano é publicado como comentário na própria pull request, limitado a 65536 caracteres de saída.
  4. Um revisor humano lê o plano e aprova (ou pede ajuste) antes do merge.
  5. Ao mergear na branch main, o workflow roda terraform apply -auto-approve, com max-parallel: 1 para evitar duas aplicações simultâneas.
  6. O resultado da aplicação chega por notificação no Slack.
  7. A autenticação acontece via OIDC: o GitHub Actions assume a role GitHubActionsTerraform na conta shared-services usando aws-actions/configure-aws-credentials, sem chaves estáticas em secrets.
  8. De dentro da conta shared-services, o Terraform assume a role TerraformExecutionRole na conta de destino (prod, staging, dev, sandbox, data), via assume_role no provider, escopada por var.environment.
  9. Cada domínio (networking, eks, data, apps, security, dns) e cada ambiente (prod, staging) tem seu próprio backend S3 e sua própria chave de lock no DynamoDB, então um terraform apply em networking/prod nunca toca o estado de apps/payments-staging.
  10. Referências entre domínios, como o vpc_id que o módulo de EKS precisa, não passam mais por terraform_remote_state: a conta publica o valor num parâmetro do SSM Parameter Store, e o consumidor lê com data.aws_ssm_parameter, desacoplando o replanejamento de um domínio do outro.

A migração do estado monolítico para os 24 estados novos foi feita com terraform state mv, um domínio por dia ao longo de duas semanas, começando pelo de menor risco (DNS) e rodando terraform plan nos dois lados a cada movimentação para confirmar diff zero antes de seguir para o próximo.

Os serviços envolvidos

A arquitetura final se apoia numa combinação relativamente enxuta de serviços AWS, mais o GitHub Actions como motor de CI/CD:

  • AWS Organizations: estrutura as 8 contas (management, security, shared-services e a OU de workloads com prod, staging, dev, sandbox e data), com SCPs no nível do root.
  • Amazon S3: guarda os 24 arquivos de estado, um por combinação de domínio e ambiente, com versionamento habilitado e criptografia via KMS (aws:kms).
  • Amazon DynamoDB: fornece o lock de estado, em modo PAY_PER_REQUEST, com uma tabela única (terraform-locks) compartilhada mas com chaves de lock independentes por arquivo de estado.
  • AWS IAM: define o provedor OIDC (aws_iam_openid_connect_provider) que confia no token.actions.githubusercontent.com, a role GitHubActionsTerraform que o pipeline assume, e a role TerraformExecutionRole em cada conta de workload, escopada com a policy gerenciada PowerUserAccess em vez de AdministratorAccess.
  • AWS STS: processa o AssumeRoleWithWebIdentity do GitHub Actions e os sts:AssumeRole em cadeia entre shared-services e cada conta de destino.
  • AWS Systems Manager Parameter Store: substitui o terraform_remote_state como canal de comunicação entre domínios, publicando valores como vpc_id sem acoplar o replanejamento.
  • Os próprios recursos de carga de trabalho gerenciados, como VPC, EKS, RDS, S3, CloudFront, Lambda e Route53, continuam existindo; o que mudou foi como o estado deles é guardado e aplicado, não a infraestrutura em si.

Trade-offs

A decisão central, dividir um estado em 24, troca simplicidade operacional por isolamento de risco: é o pilar de confiabilidade do Well-Architected na prática. Antes, um erro de digitação num workspace podia varrer 500 recursos; depois, o blast radius máximo caiu para cerca de 30 recursos por apply, porque cada diretório só enxerga o próprio domínio e ambiente.

Essa mesma divisão tem um custo que o relato não esconde: mais arquivos de backend, mais diretórios para navegar, e uma dependência entre domínios que precisa ser gerenciada explicitamente via SSM Parameter Store em vez de um único main.tf onde tudo é visível. É o preço de trocar um monolito fácil de entender (mas fácil de quebrar) por um conjunto de partes isoladas (mas que exige disciplina para não virar uma teia de referências cruzadas sem documentação).

No eixo de excelência operacional, tirar o terraform apply do laptop dos engenheiros e colocá-lo só no pipeline do GitHub Actions elimina uma classe inteira de erro humano, mas introduz uma dependência forte de CI/CD: se o pipeline quebra, ninguém aplica nada, nem em emergência, a menos que exista um caminho de exceção documentado, que o relato não detalha.

No eixo de segurança, a troca de AdministratorAccess por PowerUserAccess na role de execução do Terraform é uma melhoria real, mas incompleta: PowerUserAccess ainda é uma policy ampla, que cobre a maioria dos serviços. O ganho de segurança vem mais da separação de função (IAM gerenciado pela conta de segurança, não pelo Terraform de workload) do que da policy em si.

DecisãoGanhoCusto
24 estados em vez de 1Blast radius de 500+ para ~30 recursosMais diretórios e backends para manter
CI/CD obrigatório0 engenheiros aplicando do laptopDependência total do pipeline
SSM em vez de remote_stateDesacopla replanejamento entre domíniosDependência implícita, sem grafo explícito
PowerUserAccess em vez de AdministratorAccessReduz escopo de dano por roleAinda é uma policy ampla

Custo estimado

O relato é explícito num ponto raro em artigos desse tipo: a reestruturação teve custo adicional de AWS igual a zero. Os 24 buckets de estado (na prática, prefixos dentro de um bucket) e a tabela DynamoDB em modo PAY_PER_REQUEST custam frações de centavo a mais do que o backend único anterior, porque o volume de dados armazenado é o mesmo, só reparticionado.

O custo real foi de engenharia: quatro semanas de trabalho para desenhar a nova estrutura, migrar o estado domínio por domínio com terraform state mv, e construir o pipeline do GitHub Actions. A fonte não detalha quantas pessoas-semana isso representou, só que a migração em si levou duas semanas, a um domínio por dia.

O retorno aparece nos números operacionais que a própria equipe publicou, antes e depois da mudança:

MétricaAntesDepois
Tempo de plan15 min45 seg
Conflitos de lock por semana120
Incidentes de drift por trimestre80
Tempo para aplicar uma mudança45 min8 min
Destroys acidentais (janela de 6 meses)20
Onboarding de engenheiro2 semanas2 horas

Em resumo: não há tabela de custo de infraestrutura para comparar, porque praticamente não existe. O ganho é medido em horas de engenharia recuperadas, não em fatura da AWS, o que faz sentido num projeto que troca estrutura e processo, não tipo ou quantidade de recurso provisionado.

Como adaptar

Para quem mantém Terraform em mais de uma conta AWS hoje, o relato sugere uma ordem de prioridades que não exige reescrever tudo de uma vez:

  1. Primeiro, pare os applies manuais. Antes de mexer no estado, tire o terraform apply do laptop das pessoas. Um workflow simples de GitHub Actions com OIDC (sem chaves estáticas) já elimina a causa mais comum de erro humano, mesmo antes de dividir o estado.
  2. Divida o estado pelo domínio de menor risco primeiro. O relato começou por DNS exatamente porque um erro ali é mais fácil de reverter do que um erro em rede ou banco de dados. Use terraform state mv com -state e -state-out, e rode terraform plan nos dois lados depois de cada movimentação para confirmar diff zero.
  3. Desenhe o backend de forma previsível. Um padrão de chave como dominio/ambiente/terraform.tfstate dentro de um único bucket S3 versionado, com uma tabela DynamoDB de lock e criptografia via KMS, é suficiente para dezenas de estados sem precisar de um bucket por domínio.
  4. Troque terraform_remote_state por SSM Parameter Store nos casos em que um domínio só precisa de um valor pontual do outro, como um vpc_id. Isso evita que uma mudança em rede force um replanejamento em todo módulo que depende dela.
  5. Limite a profundidade dos módulos a dois níveis e nunca use ref=main em produção: pin de versão via git tag, como ref=v2.3.1, promovido manualmente de staging para produção depois de um período de observação, evita que uma mudança em módulo compartilhado se propague sem aviso.
  6. Desenhe interfaces de módulo em termos de negócio, não de implementação da AWS. Uma variável size com validação (small, medium, large, xlarge) que mapeia internamente para instance_class, armazenamento e IOPS é mais legível e mais segura contra erro de digitação do que expor instance_class diretamente.

O relato não resolve tudo: as seções sobre detecção de drift e experiência do desenvolvedor aparecem no sumário do artigo original, mas o material disponível detalha mais a fundo a divisão de estado, a estratégia multi-conta, a composição de módulos e o pipeline de CI/CD. Para quem decide adaptar esse padrão, vale night tratar a divisão do estado como projeto de várias semanas, não como refactor de uma tarde, e medir o antes e depois com números próprios, como a equipe do relato fez com tempo de plan, conflitos de lock e incidentes de drift.

Fonte: DEV Community — #aws

Serviços neste textoTerraformWell-Architected

Leve para a sua IA

Decida com o seu assistente, com o contexto deste texto já montado.

1. O que você quer saber

Ver o prompt
Li no AWS Hub: "Equipe reestrutura Terraform em 24 estados depois de um destroy acidental apagar o staging inteiro" (https://awshub.com.br/comunidade/equipe-reestrutura-terraform-em-24-estados-depois-de-um-destroy-acidental-apagar).
Resumo: Um relato publicado na DEV Community mostra como uma equipe saiu de um estado monolítico de 50MB, com 500+ recursos em 8 contas AWS, para 24 estados isolados por domínio e ambiente, depois que um terraform destroy no workspace errado derrubou o staging inteiro.
Serviços: Terraform, Well-Architected

Minha stack: [descreva em uma linha: serviços, linguagem, volume, região]

Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?

Newsletter semanal

A semana da AWS, em português

Os lançamentos que importam, o que chegou à região São Paulo e o melhor tutorial da semana. Toda sexta, gratuita.