Terraform para OpenTofu: a migração segura começa pelo backup do estado

Para migrar do Terraform para o OpenTofu sem recriar recursos, preserve uma cópia recuperável do estado e do código, inicialize a configuração com OpenTofu e examine o primeiro plano antes de aplicar mudanças. O guia de migração do OpenTofu orienta essa sequência e recomenda testar depois uma alteração pequena e não crítica.

Se o plano mostrar criação, exclusão ou substituição inesperada, pare antes do apply. Confirme que a ferramenta acessou o estado, o workspace, as variáveis e os provedores pretendidos; só avance quando entender cada diferença. O backup permite investigar ou preparar o retorno sem depender de uma cópia de estado que já tenha sido alterada.

Registre o ambiente antes da troca

Faça um inventário da configuração em uso: versão do Terraform, restrições e versões dos provedores, arquivo de dependências, módulos, workspace ativo e backend de cada estado. Registre as variáveis e credenciais fornecidas pela automação, sem colocar segredos no inventário. Essas informações ajudam a separar uma diferença de acesso ou de versão de uma mudança efetiva na infraestrutura.

Reserve uma janela sem outras execuções sobre o mesmo estado e suspenda temporariamente os pipelines capazes de aplicar mudanças. Se houver alterações pendentes, obtenha um plano de referência com Terraform e guarde a configuração correspondente no controle de versão. Compare esse plano com o do OpenTofu usando o mesmo workspace e as mesmas entradas; caso contrário, a comparação mistura a migração com mudanças que já estavam previstas.

Preserve o estado antes de inicializar

O estado guarda a associação entre recursos declarados e objetos reais. A documentação de estado do Terraform explica essa função, desaconselha editar diretamente o arquivo JSON e alerta que armazenamento sem bloqueio e controle de acesso pode causar perda de dados ou exposição de segredos. Proteja o backup com o mesmo cuidado dado ao estado ativo.

Para estado local, copie o arquivo terraform.tfstate e qualquer cópia anterior disponível para um local separado antes de executar tofu init. Se houver vários workspaces, identifique e preserve o estado correspondente a cada um. Para estado remoto, use o procedimento de snapshot ou versionamento oferecido pelo backend e registre qual versão foi preservada. Confirme também a origem da cópia: um arquivo sem vínculo claro com o workspace e a configuração não oferece um retorno confiável.

Estado remoto: confira o destino antes do tofu init

Com um backend remoto, o estado ativo pode estar fora do diretório do projeto. Antes da inicialização, reúna as informações necessárias para que a nova execução encontre o mesmo estado:

• Localização: confira o backend, o endereço ou caminho do estado e o workspace. Um destino vazio pode produzir um plano de criação de recursos já existentes.
• Acesso e bloqueio: confira quem pode ler e gravar o estado e se o backend oferece bloqueio para operações concorrentes.
• Recuperação: identifique o snapshot preservado, o procedimento de restauração e quem tem permissão para executá-lo.
• Automação: impeça que execuções de Terraform e OpenTofu gravem o mesmo estado durante a transição.

Execute tofu init após essas conferências. Se a inicialização propuser migrar o estado para outro backend, interrompa a operação e revise a configuração do destino antes de aceitar. Alterar a ferramenta e o armazenamento na mesma etapa torna mais difícil localizar a causa de uma divergência no plano.

Use o primeiro plano como ponto de decisão

Depois da inicialização, execute tofu plan com o workspace e as entradas registrados no inventário. Um plano sem mudanças indica que a configuração e a infraestrutura estão alinhadas naquele momento. Se o plano anterior do Terraform já mostrava alterações pendentes, compare as ações por recurso, em vez de exigir que o resultado seja vazio.

Examine especialmente criação, destruição e substituição de recursos, além de diferenças de identificadores e de provedores. Se algo não corresponder ao esperado, confira o backend, o workspace, as credenciais, as versões instaladas e as variáveis antes de gerar outro plano. Não aprove o apply apenas porque o total de mudanças parece pequeno: uma única substituição pode ser a diferença decisiva. Mesmo um apply sem alterações aparentes na infraestrutura pode atualizar o formato do estado, por isso a cópia anterior deve continuar disponível.

Configurações interdependentes exigem uma ordem própria

Quando uma configuração lê saídas de outra por terraform_remote_state, mapeie primeiro qual estado cada configuração produz e quais estados consome. O guia do OpenTofu para configurações interdependentes orienta migrar as consumidoras antes das produtoras: uma configuração em OpenTofu pode ler o estado ainda escrito pelo Terraform, enquanto a leitura no sentido inverso pode enfrentar incompatibilidades, sobretudo com recursos específicos do OpenTofu.

Preserve cópias de todos os estados envolvidos, inclusive daqueles que ainda serão escritos pelo Terraform. Migre uma configuração consumidora por vez, confira seu plano e, após uma gravação de estado, gere também o plano das configurações que dependem dela. Se não estiver claro quem lê determinado estado, complete esse mapa antes do apply. A ordem da migração depende dessas relações, não apenas da ordem em que os projetos aparecem no repositório.

Teste uma mudança pequena e prepare o retorno

Com o primeiro plano compreendido e aprovado, execute tofu apply de forma controlada. Depois, escolha uma alteração pequena e não crítica, examine o novo plano e só então aplique o teste. Adicionar uma tag é um exemplo condicional: confirme antes que o provedor e as regras do ambiente permitam a alteração sem substituir o recurso. Verifique o resultado na infraestrutura e gere outro plano para identificar diferenças remanescentes.

Se precisar voltar antes de qualquer gravação pelo OpenTofu, interrompa seu uso e retome o Terraform com a configuração e o estado preservados; execute terraform init e terraform plan antes de aplicar. Se o OpenTofu já tiver modificado o estado ou recursos reais, interrompa novas execuções e compare a infraestrutura atual com o snapshot escolhido antes de restaurá-lo. Uma restauração cega pode fazer o estado deixar de registrar um recurso que continua existindo. Evite editar o JSON manualmente e só volte a aplicar com Terraform quando seu plano mostrar as mudanças que a equipe pretende executar.

Leia também:

• Mudar de carreira por causa da IA? Comece pelas tarefas, não pelo cargo
• ClickUp ou Trello: mais recursos podem custar semanas de migração
• Agente de IA ganhou uma VM própria — isole rede, segredos e estado na AWS