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
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.tfstatemonolí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 applypodia 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 planantes 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:
- O engenheiro abre uma branch e altera um diretório dentro de
infrastructure/, por exemploinfrastructure/data/prod/. - Um workflow do GitHub Actions detecta quais diretórios mudaram (via
git diffcomparado comGITHUB_OUTPUT) e disparaterraform initeterraform plansó para esses diretórios. - O plano é publicado como comentário na própria pull request, limitado a 65536 caracteres de saída.
- Um revisor humano lê o plano e aprova (ou pede ajuste) antes do merge.
- Ao mergear na branch
main, o workflow rodaterraform apply -auto-approve, commax-parallel: 1para evitar duas aplicações simultâneas. - O resultado da aplicação chega por notificação no Slack.
- A autenticação acontece via OIDC: o GitHub Actions assume a role
GitHubActionsTerraformna conta shared-services usandoaws-actions/configure-aws-credentials, sem chaves estáticas em secrets. - De dentro da conta shared-services, o Terraform assume a role
TerraformExecutionRolena conta de destino (prod, staging, dev, sandbox, data), viaassume_roleno provider, escopada porvar.environment. - 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 applyemnetworking/prodnunca toca o estado deapps/payments-staging. - Referências entre domínios, como o
vpc_idque o módulo de EKS precisa, não passam mais porterraform_remote_state: a conta publica o valor num parâmetro do SSM Parameter Store, e o consumidor lê comdata.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 notoken.actions.githubusercontent.com, a roleGitHubActionsTerraformque o pipeline assume, e a roleTerraformExecutionRoleem cada conta de workload, escopada com a policy gerenciadaPowerUserAccessem vez deAdministratorAccess. - AWS STS: processa o
AssumeRoleWithWebIdentitydo GitHub Actions e ossts:AssumeRoleem cadeia entre shared-services e cada conta de destino. - AWS Systems Manager Parameter Store: substitui o
terraform_remote_statecomo canal de comunicação entre domínios, publicando valores comovpc_idsem 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ão | Ganho | Custo |
|---|---|---|
| 24 estados em vez de 1 | Blast radius de 500+ para ~30 recursos | Mais diretórios e backends para manter |
| CI/CD obrigatório | 0 engenheiros aplicando do laptop | Dependência total do pipeline |
| SSM em vez de remote_state | Desacopla replanejamento entre domínios | Dependência implícita, sem grafo explícito |
| PowerUserAccess em vez de AdministratorAccess | Reduz escopo de dano por role | Ainda é 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étrica | Antes | Depois |
|---|---|---|
| Tempo de plan | 15 min | 45 seg |
| Conflitos de lock por semana | 12 | 0 |
| Incidentes de drift por trimestre | 8 | 0 |
| Tempo para aplicar uma mudança | 45 min | 8 min |
| Destroys acidentais (janela de 6 meses) | 2 | 0 |
| Onboarding de engenheiro | 2 semanas | 2 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:
- Primeiro, pare os applies manuais. Antes de mexer no estado, tire o
terraform applydo 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. - 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 mvcom-statee-state-out, e rodeterraform plannos dois lados depois de cada movimentação para confirmar diff zero. - Desenhe o backend de forma previsível. Um padrão de chave como
dominio/ambiente/terraform.tfstatedentro 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. - Troque
terraform_remote_statepor SSM Parameter Store nos casos em que um domínio só precisa de um valor pontual do outro, como umvpc_id. Isso evita que uma mudança em rede force um replanejamento em todo módulo que depende dela. - Limite a profundidade dos módulos a dois níveis e nunca use
ref=mainem produção: pin de versão viagit tag, comoref=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. - Desenhe interfaces de módulo em termos de negócio, não de implementação da AWS. Uma variável
sizecom validação (small,medium,large,xlarge) que mapeia internamente parainstance_class, armazenamento e IOPS é mais legível e mais segura contra erro de digitação do que exporinstance_classdiretamente.
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ã?