Terraform: infraestrutura como código sem aquele frio na barriga do primeiro Apply

Existe uma sensação muito particular em executar terraform plan e encontrar uma lista enorme de recursos que serão criados, modificados ou, no pior dos cenários, destruídos.

É quase como assistir a um contrato sendo lido em voz alta antes de assinar. Você sabe que precisa continuar, mas começa a prestar atenção em cada linha, principalmente naquela que diz que alguma coisa será removida.

O Terraform trouxe uma maneira diferente de administrar infraestrutura, permitindo criar e gerenciar servidores, redes, bancos de dados e diversos outros recursos utilizando código, em vez de depender exclusivamente de interfaces gráficas e configurações manuais.

Neste artigo, vamos entender como a ferramenta funciona, conhecer seus principais comandos e organizar os primeiros arquivos de um projeto sem cometer aqueles erros clássicos que fazem qualquer administrador de sistemas questionar suas escolhas profissionais.

O que é Terraform e por que tanta gente utiliza?

Criado pela HashiCorp, o Terraform popularizou o conceito de Infraestrutura como Código (IaC), permitindo descrever recursos de infraestrutura em arquivos de texto e controlar suas alterações de maneira organizada.

A ideia é relativamente simples: em vez de acessar o painel de um provedor de nuvem, clicar em diversas opções e configurar tudo manualmente, você descreve o que deseja em arquivos utilizando uma linguagem chamada HCL, ou HashiCorp Configuration Language.

Por exemplo, você pode declarar que precisa de três servidores, uma rede virtual com determinada configuração e um balanceador de carga distribuindo as conexões entre essas instâncias.

O Terraform interpreta essas declarações, consulta o estado conhecido da infraestrutura e calcula quais alterações precisam ser realizadas para alcançar o resultado desejado.

Essa abordagem é chamada de declarativa.

Em vez de escrever um roteiro detalhado dizendo exatamente qual comando executar primeiro, segundo e terceiro, você informa o estado final esperado e deixa a ferramenta determinar as operações necessárias.

É uma mudança importante na maneira de pensar infraestrutura. O foco deixa de ser apenas executar comandos e passa a ser manter o ambiente alinhado com aquilo que foi definido no código.

Entendendo a estrutura básica de um projeto

Um projeto Terraform pode começar com poucos arquivos, cada um responsável por uma parte da configuração.

Uma organização inicial bastante comum é:

meu-projeto/
│
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf
├── terraform.tfvars
└── .gitignore

Cada arquivo possui uma finalidade específica.

main.tf concentra as declarações dos recursos que serão gerenciados.

variables.tf define as variáveis utilizadas para parametrizar o projeto.

outputs.tf informa quais resultados devem ser apresentados após a execução.

providers.tf configura os provedores utilizados, como AWS, Azure ou Google Cloud.

terraform.tfvars armazena valores atribuídos às variáveis, permitindo personalizar a configuração de cada ambiente.

.gitignore impede que arquivos locais, temporários ou sensíveis sejam adicionados acidentalmente ao controle de versão.

Essa separação não é obrigatória, pois o Terraform consegue interpretar vários arquivos .tf dentro do mesmo diretório. Ainda assim, organizar o projeto desde o início facilita bastante a manutenção, principalmente quando outras pessoas começam a trabalhar nele.

Os três comandos que você precisa conhecer

O fluxo básico de trabalho do Terraform gira em torno de três comandos principais: init, plan e apply.

1. terraform init, preparando o terreno

O primeiro passo é inicializar o diretório de trabalho.

terraform init

Esse comando prepara o projeto, identifica os provedores declarados na configuração e baixa os plugins necessários para estabelecer comunicação com os serviços correspondentes.

Também inicializa o backend configurado para armazenar o estado da infraestrutura.

É o equivalente a preparar todas as ferramentas antes de começar uma instalação.

2. terraform plan, a hora de conferir antes de mexer

Depois da inicialização, chega o momento de verificar o que será feito.

terraform plan

O Terraform compara a configuração declarada com o estado conhecido dos recursos e apresenta um plano das alterações necessárias.

Nesse momento, você consegue identificar quais recursos serão criados, atualizados ou removidos.

É justamente aqui que vale a pena respirar fundo e revisar tudo com calma.

Se aparecer uma alteração inesperada em um banco de dados de produção, por exemplo, talvez seja melhor investigar antes de continuar.

O plan não aplica as mudanças na infraestrutura, mas é importante lembrar que ele pode consultar APIs e realizar operações de leitura nos provedores.

3. terraform apply, agora é para valer

Quando o plano estiver revisado e aprovado, chega a hora de executar as alterações.

terraform apply

O Terraform apresenta o plano e solicita confirmação antes de prosseguir, salvo quando opções específicas alteram esse comportamento.

Após a aprovação, os recursos são criados, modificados ou removidos conforme necessário.

Em ambientes críticos, o ideal é que essa etapa faça parte de um processo controlado, com revisão de código, aprovação e registro das alterações.

Porque clicar em confirmar sem entender o que será destruído é uma experiência que ninguém precisa repetir.

State: o arquivo que merece respeito

Um dos conceitos mais importantes do Terraform é o gerenciamento do estado, conhecido como state.

O arquivo tradicional terraform.tfstate mantém o mapeamento entre os recursos declarados no código e os objetos reais existentes no provedor de infraestrutura.

É por meio desse estado que o Terraform acompanha informações sobre os recursos que administra e consegue calcular as diferenças entre a configuração desejada e o ambiente conhecido.

Agora imagine perder esse arquivo ou trabalhar com uma versão desatualizada.

A ferramenta pode deixar de reconhecer corretamente recursos existentes, dificultando o gerenciamento e exigindo procedimentos de recuperação ou importação.

Isso não significa que todos os recursos serão automaticamente destruídos, mas perder o controle do estado pode transformar uma manutenção simples em uma investigação bastante desagradável.

State local ou remoto?

Em projetos pessoais e laboratórios, armazenar o estado localmente pode ser suficiente.

Mas, quando existe uma equipe trabalhando na mesma infraestrutura, essa abordagem rapidamente começa a apresentar limitações.

Imagine duas pessoas executando alterações simultaneamente, cada uma utilizando uma cópia diferente do estado.

O resultado pode ser conflito, divergência de informações e operações inesperadas.

Por isso, ambientes compartilhados devem utilizar um backend remoto compatível com o provedor escolhido, preferencialmente com mecanismos de bloqueio de estado (locking) quando disponíveis.

Esses mecanismos ajudam a impedir alterações concorrentes que poderiam comprometer a consistência das operações.

Também é fundamental proteger o acesso ao estado, manter versões recuperáveis e utilizar controles de acesso adequados.

Afinal, o arquivo de state pode conter informações sensíveis sobre a infraestrutura, incluindo dados que não deveriam circular livremente em um repositório Git.

Variáveis e Outputs: código reutilizável sem copiar e colar tudo

Uma das grandes vantagens do Terraform é permitir que a mesma configuração seja utilizada em ambientes diferentes.

É aí que entram as variáveis.

Imagine que você precise criar uma instância de máquina virtual para desenvolvimento e outra para produção.

Em vez de duplicar toda a configuração, pode utilizar variáveis para definir características como tamanho da instância, região, nome e faixa de rede.

Exemplo:

variable "instance_type" {
  description = "Tipo da instância"
  type        = string
  default     = "t3.micro"
}

Dessa forma, o valor pode ser alterado conforme a necessidade, sem precisar modificar diretamente a declaração do recurso.

Já os Outputs permitem apresentar informações importantes geradas durante a execução.

Por exemplo, o endereço IP público de uma instância recém-criada ou o identificador de uma rede virtual.

output "instance_id" {
  description = "Identificador da instância"
  value       = aws_instance.web.id
}

Esses resultados podem ser utilizados por outros módulos, scripts externos ou simplesmente consultados para confirmar que a implantação ocorreu conforme esperado.

Módulos: quando o projeto começa a crescer

No começo, manter tudo em um único arquivo parece perfeitamente aceitável.

O problema aparece quando aquele arquivo começa a acumular centenas de linhas, diferentes ambientes, configurações de rede, servidores, regras de firewall e outros recursos.

Nesse momento, a manutenção começa a ficar parecida com procurar uma agulha em um palheiro.

Os módulos resolvem boa parte dessa dificuldade, permitindo agrupar configurações relacionadas em componentes reutilizáveis.

Por exemplo, uma empresa pode criar um módulo responsável por provisionar redes virtuais seguindo os padrões internos de segurança.

Esse mesmo módulo pode ser utilizado em desenvolvimento, homologação e produção, recebendo parâmetros diferentes conforme o ambiente.

Isso reduz duplicação de código e ajuda a manter consistência entre as implantações.

Também facilita a evolução do projeto, pois melhorias realizadas em um módulo podem ser reaproveitadas em diferentes partes da infraestrutura.

Drift: o perigo de alterar tudo manualmente no painel

Um erro bastante comum acontece quando alguém cria recursos utilizando Terraform e, algum tempo depois, resolve alterar configurações diretamente pelo painel do provedor.

À primeira vista, parece inofensivo.

O problema é que o código continua descrevendo uma configuração, enquanto a infraestrutura real passa a apresentar outra.

Essa divergência é conhecida como configuration drift.

Quando um novo terraform plan é executado, o Terraform pode identificar diferenças entre o estado conhecido, a configuração declarada e as informações consultadas no provedor.

Dependendo do recurso e da alteração realizada, o plano poderá propor atualizações ou substituições para tentar reconciliar o ambiente.

É por isso que, em projetos gerenciados por Terraform, mudanças manuais devem ser evitadas sempre que possível.

Se uma alteração emergencial for necessária diretamente no provedor, ela deve ser documentada e posteriormente reconciliada com o código.

O objetivo é manter o Terraform como referência confiável da infraestrutura, evitando aquele cenário em que ninguém sabe mais qual configuração está valendo.

Segurança: cuidado com credenciais e arquivos sensíveis

Aqui entramos em um assunto que merece atenção especial.

Arquivos de configuração Terraform podem conter informações sensíveis, e o state pode armazenar valores de atributos dos recursos gerenciados.

Por isso, nunca devemos tratar esses arquivos como simples textos sem importância.

Algumas práticas fundamentais incluem:

1. Não armazenar credenciais diretamente no código.

2. Utilizar ferramentas de gerenciamento de segredos sempre que possível.

3. Restringir o acesso ao backend remoto.

4. Evitar publicar arquivos de state em repositórios.

5. Configurar corretamente o .gitignore.

6. Utilizar permissões mínimas necessárias para as contas de serviço.

Um exemplo de .gitignore básico:

.terraform/
*.tfstate
*.tfstate.*
*.tfvars
!*.tfvars.example
crash.log

Esse exemplo exclui arquivos de estado, diretórios locais e arquivos de variáveis, permitindo manter um arquivo de exemplo sem informações sensíveis.

Vale lembrar que o .gitignore não remove arquivos que já foram adicionados ao controle de versão. Se um segredo foi publicado acidentalmente, é necessário tratar o incidente, revogar ou rotacionar as credenciais e avaliar a exposição.

Vazamentos de credenciais de nuvem podem resultar em acessos indevidos, criação de recursos não autorizados e cobranças inesperadas.

E ninguém quer descobrir que alguém utilizou sua conta para levantar uma fazenda de mineração de criptomoedas enquanto você estava tranquilamente tomando café.

Terraform em equipes: infraestrutura também precisa de revisão de código

Em ambientes corporativos, o Terraform funciona muito bem quando integrado a processos de desenvolvimento e entrega contínua.

Uma prática comum é utilizar repositórios Git para armazenar as configurações e exigir revisões antes de aplicar mudanças em ambientes críticos.

O fluxo pode incluir:

1. Desenvolvedor cria uma alteração no código.

2. Abre um Pull Request para revisão.

3. Pipeline executa validações e verifica a configuração.

4. O plano de execução é analisado pela equipe.

5. Alterações críticas recebem aprovação.

6. O apply é executado de maneira controlada.

Esse processo ajuda a identificar erros antes que cheguem à infraestrutura real.

Também permite manter histórico das alterações, identificar responsáveis e facilitar auditorias.

Ferramentas complementares, como Terragrunt, podem ajudar a organizar configurações e dependências em projetos maiores. Workspaces e pipelines de automação também podem fazer parte da estratégia, desde que utilizados de acordo com as necessidades do ambiente.

O importante é não transformar a automação em uma máquina de executar mudanças sem supervisão.

Terraform não está sozinho nessa história

Embora seja uma das ferramentas mais conhecidas de infraestrutura como código, o Terraform não é a única opção disponível.

O Pulumi, por exemplo, permite definir infraestrutura utilizando linguagens convencionais como Python, TypeScript e Go.

Já o CloudFormation oferece integração nativa com a AWS, enquanto o Bicep é uma alternativa declarativa voltada ao Azure.

Cada solução possui características próprias, vantagens e limitações.

O Terraform se destaca pelo ecossistema de provedores e pela possibilidade de trabalhar com diferentes plataformas utilizando uma abordagem consistente.

Isso pode ser especialmente interessante para organizações que operam em ambientes híbridos ou multicloud.

A escolha deve considerar familiaridade da equipe, requisitos técnicos, governança e ferramentas já utilizadas pela organização.

Por onde começar sem transformar o projeto em um incidente?

Se você está começando com Terraform, meu conselho é simples: comece pequeno.

Não tente migrar toda a infraestrutura da empresa em um único fim de semana, especialmente se ainda está aprendendo como a ferramenta gerencia estado e dependências.

Escolha um componente isolado e de baixo risco, como um bucket de armazenamento ou uma rede virtual de laboratório.

Depois, pratique o fluxo completo:

1. Escreva a configuração.

2. Execute terraform init.

3. Revise o resultado do terraform plan.

4. Aplique as alterações em um ambiente de teste.

5. Consulte os recursos criados.

6. Teste alterações e remoções controladas.

7. Entenda como o state se comporta durante todo o processo.

Antes de avançar para ambientes críticos, estabeleça procedimentos de backup, recuperação e revisão das mudanças.

E lembre-se de que nem toda alteração pode ser revertida simplesmente executando outro apply. Alguns recursos podem ser substituídos ou removidos, e determinados dados podem ser irrecuperáveis sem backups apropriados.

Planejamento continua sendo parte fundamental da automação.

Conclusão: infraestrutura como código exige disciplina, não apenas comandos

Aprender Terraform é, em muitos sentidos, aprender a pensar infraestrutura de outra maneira.

Em vez de depender exclusivamente de configurações manuais e comandos executados individualmente, passamos a descrever o estado desejado, versionar mudanças e utilizar automação para manter o ambiente consistente.

Essa abordagem traz ganhos importantes de repetibilidade, rastreabilidade e padronização, mas também exige responsabilidade no gerenciamento de estado, segurança das credenciais e revisão das alterações.

O primeiro terraform apply pode parecer assustador, principalmente quando o plano apresenta dezenas de recursos e algumas operações de substituição.

Mas, com prática e processos bem definidos, essa sensação dá lugar à confiança de saber exatamente o que será alterado antes de executar qualquer mudança.

E existe uma satisfação especial em ver a infraestrutura sendo criada conforme o código que você escreveu.

É quase poético.

Principalmente quando o terraform plan termina sem nenhuma surpresa e ninguém precisa perguntar por que o servidor de produção desapareceu.

Porque, no mundo da infraestrutura como código, a melhor automação não é aquela que executa tudo sozinha.

É aquela que executa exatamente o que deveria, de maneira previsível, segura e documentada.