Terraform

O que é

O Terraform é uma ferramenta de infraestrutura como código criada pela HashiCorp em 2014. Você descreve em arquivos .tf a infraestrutura que quer (redes, máquinas, bancos, DNS, filas, usuários, até repositórios no GitHub) e o Terraform compara essa descrição com o que existe, mostra o que vai mudar e, com a sua confirmação, faz as chamadas de API necessárias.

Os arquivos são escritos em HCL (HashiCorp Configuration Language), uma linguagem declarativa feita para ser lida por pessoas. O nome vem de terraformar: transformar um planeta vazio num lugar habitável.

O problema

Sem uma ferramenta assim, a infraestrutura nasce de cliques no console da nuvem (o famoso ClickOps) ou de scripts imperativos. Os dois caminhos levam aos mesmos problemas:

• Ninguém sabe exatamente o que existe. O conhecimento fica na cabeça de quem clicou.
• Ambientes divergem. Homologação e produção deveriam ser iguais, mas cada um recebeu ajustes manuais diferentes.
• Mudanças não são revisadas. Uma regra de firewall aberta demais vai para produção sem passar por ninguém.
• Scripts não sabem o estado atual. Rodar duas vezes o script que cria uma VM cria duas VMs.
• Recriar é arqueologia. Se uma conta é comprometida ou uma região cai, reconstruir o ambiente leva dias.

O Terraform resolve isso tratando a infraestrutura como código: versionada no git, revisada em pull request e aplicada de forma idempotente (aplicar duas vezes dá o mesmo resultado que aplicar uma).

Como funciona

O Terraform em si (o core) não sabe nada sobre AWS, Azure ou Docker. Ele lê a configuração, monta um grafo de dependências, compara com o state e delega cada operação a um provider: um plugin que traduz “crie este recurso” em chamadas à API de um serviço.

Os providers são baixados do Terraform Registry no terraform init. É por isso que o mesmo fluxo serve para qualquer coisa que tenha uma API: há providers oficiais e da comunidade para nuvens, bancos, SaaS, monitoramento e muito mais.

O ciclo de trabalho

A diferença entre plan e apply é o coração da segurança do Terraform: toda mudança é mostrada antes de acontecer.

Laboratório: um container com Terraform

Para experimentar sem conta na nuvem, o provider de Docker cria containers na sua máquina. Este exemplo é baseado no tutorial oficial de introdução da HashiCorp. Com Docker e Terraform instalados (brew install hashicorp/tap/terraform ou o binário em developer.hashicorp.com), crie uma pasta com um main.tf:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {}

resource "docker_image" "nginx" {
  name         = "nginx:latest"
  keep_locally = false
}

resource "docker_container" "web" {
  name  = "web"
  image = docker_image.nginx.image_id # referência: cria a dependência

  ports {
    internal = 80
    external = 8080
  }
}

terraform init      # baixa o provider e cria o .terraform.lock.hcl
terraform plan      # "Plan: 2 to add, 0 to change, 0 to destroy."
terraform apply     # confirme com "yes" e abra http://localhost:8080

Agora veja o Terraform reagir a mudanças:

# 1. Mude external = 8080 para 8081 no main.tf e rode:
terraform plan      # o container será substituído (-/+): porta não muda "no lugar"

# 2. Apague o container por fora do Terraform e rode o plan de novo:
docker rm -f web
terraform plan      # o Terraform percebe que ele sumiu e planeja recriá-lo

terraform destroy   # limpa tudo

O segundo experimento mostra o drift: a realidade mudou sem passar pelo código, e o próximo plan revela a diferença.

Lendo um plano

O plano é o que você revisa antes de cada mudança, e cada símbolo tem um peso diferente:

A linha que mais merece atenção é # forces replacement: ela indica qual atributo obriga a substituição. Trocar o nome de um banco gerenciado, por exemplo, costuma significar apagar o banco.

Em times, o padrão é gravar o plano e aplicar exatamente o que foi revisado:

terraform plan -out=tfplan
terraform apply tfplan      # aplica este plano, sem recalcular

A linguagem: os blocos principais

Um exemplo na AWS juntando os blocos:

variable "environment" {
  type    = string
  default = "staging"

  validation {
    condition     = contains(["staging", "production"], var.environment)
    error_message = "Use staging ou production."
  }
}

locals {
  tags = { Environment = var.environment, ManagedBy = "terraform" }
}

data "aws_availability_zones" "available" {}

resource "aws_s3_bucket" "assets" {
  bucket = "acme-assets-${var.environment}"
  tags   = local.tags
}

output "bucket_arn" {
  value = aws_s3_bucket.assets.arn
}

Muitos recursos parecidos: count e for_each

resource "aws_s3_bucket" "logs" {
  for_each = toset(["app", "audit", "billing"])
  bucket   = "acme-logs-${each.key}"
}

Prefira for_each a count para coleções. Com count, cada recurso é identificado pela posição (logs[0], logs[1]); remover o primeiro item da lista desloca todos os outros, e o Terraform planeja destruir e recriar recursos que não mudaram. Com for_each, a identidade é a chave (logs["audit"]) e não depende da ordem.

O grafo de dependências

Você não diz ao Terraform em que ordem criar as coisas. Cada referência de um recurso a outro (aws_subnet.private.id) vira uma aresta num grafo, e o Terraform cria primeiro o que não depende de nada, em paralelo sempre que possível (10 operações simultâneas por padrão).

Na destruição, o grafo é percorrido ao contrário: a instância some antes da subnet, que some antes da VPC. O depends_on existe para dependências que o Terraform não consegue enxergar pelas referências (uma permissão IAM que precisa existir antes de a aplicação subir, por exemplo). Use com moderação: ele torna o plano mais conservador.

Para ver o grafo da sua configuração: terraform graph | dot -Tsvg > graph.svg.

O state

O state (por padrão, o arquivo terraform.tfstate) é o mapa entre o seu código e o mundo real: ele registra que aws_instance.app no código corresponde à instância i-0abc123 na AWS, junto com todos os atributos conhecidos. Sem ele, o Terraform não saberia quais recursos são dele nem o que mudou.

Três regras sobre o state:

1. Nunca no git. Ele contém atributos sensíveis em texto puro (senhas de banco, chaves geradas) e muda a cada apply.
2. Nunca edite à mão. Use os comandos terraform state (list, show, mv, rm) ou, melhor, os blocos de refatoração descritos adiante.
3. Em equipe, use um backend remoto com lock. Se duas pessoas rodam apply ao mesmo tempo com cópias locais do state, uma sobrescreve a outra.

Backend remoto e lock

Um backend remoto guarda o state num lugar compartilhado (S3, Azure Blob, GCS, HCP Terraform) e impede execuções simultâneas com um lock:

Na AWS, até pouco tempo atrás o lock exigia uma tabela no DynamoDB. Desde a versão 1.11 (fevereiro de 2025), o próprio S3 faz o lock com um arquivo .tflock, e o uso do DynamoDB para isso está depreciado:

terraform {
  backend "s3" {
    bucket       = "acme-terraform-state"
    key          = "network/production.tfstate"
    region       = "us-east-1"
    use_lockfile = true   # lock nativo do S3 (1.11+)
  }
}

Ative o versionamento e a criptografia no bucket: um state corrompido ou apagado se recupera da versão anterior.

Segredos fora do state

Historicamente, qualquer senha passada a um recurso acabava gravada no state. Duas adições recentes atacam o problema:

• Valores e recursos efêmeros (1.10): variáveis, outputs e recursos marcados como ephemeral existem só durante a execução e não vão para o plano nem para o state (por exemplo, ler um segredo do cofre só para configurar um provider).
• Atributos write-only (1.11): o provider pode declarar atributos que são enviados à API mas nunca gravados no state, como a senha inicial de um banco.

Ambos dependem de suporte do provider; atributos antigos continuam indo para o state.

Módulos

Um módulo é só uma pasta com arquivos .tf. Toda configuração já é um módulo (o root module); chamar outra pasta com o bloco module é como chamar uma função, com variáveis de entrada e outputs de saída:

module "network" {
  source  = "terraform-aws-modules/vpc/aws"  # do Registry
  version = "~> 6.0"                         # sempre fixe a versão

  name = "acme-${var.environment}"
  cidr = "10.0.0.0/16"
}

resource "aws_instance" "app" {
  subnet_id = module.network.private_subnets[0]
  # ...
}

O source pode ser uma pasta local (./modules/network), o Registry, um repositório git (git::https://...?ref=v1.2.0) ou um bucket.

Boas práticas que evitam dor:

• Um módulo, uma responsabilidade (rede, banco, serviço). Módulos que fazem tudo viram parâmetros sem fim.
• Fixe versões de módulos e providers, e faça commit do .terraform.lock.hcl, que trava a versão exata e os hashes dos providers.
• States separados por ambiente e por camada. Um state único com toda a empresa deixa cada plan lento e cada erro perigoso. Dividir (rede, dados, aplicações; staging e produção) limita o raio de impacto.

Refatorando sem destruir

Como o state liga endereços do código a recursos reais, renomear um recurso no código parece, para o Terraform, “destruir o antigo e criar um novo”. Três blocos resolvem isso de forma declarativa, revisável no plano:

# Renomeei aws_instance.web para aws_instance.app (ou movi para um módulo)
moved {
  from = aws_instance.web
  to   = aws_instance.app
}

# Um bucket criado à mão no console passa a ser gerenciado pelo Terraform
import {
  to = aws_s3_bucket.legacy
  id = "acme-legacy-bucket"
}

# Parar de gerenciar sem destruir o recurso real
removed {
  from = aws_s3_bucket.old_logs
  lifecycle {
    destroy = false
  }
}

Os comandos antigos (terraform import, terraform state mv) ainda existem, mas alteram o state na hora, sem plano e sem revisão. Os blocos entram no pull request como qualquer outra mudança.

Drift e o que o Terraform não faz

O Kubernetes também é declarativo, mas roda um loop de reconciliação contínuo: se alguém apaga um pod, outro nasce em segundos. O Terraform não: ele só compara e corrige quando alguém roda plan e apply. Entre uma execução e outra, mudanças manuais (drift) passam despercebidas.

Formas de lidar com isso:

• terraform plan -refresh-only mostra o que mudou fora do Terraform, sem propor alterações nos recursos.
• Rodar plan agendado no CI (diariamente, por exemplo) e alertar quando houver diferença. O HCP Terraform tem detecção de drift embutida.
• Restringir permissões de escrita no console para as contas de produção: se só a pipeline pode alterar, o drift praticamente desaparece.

Testes e validação

Do mais barato ao mais caro:

Um teste fica num arquivo .tftest.hcl:

variables {
  environment = "staging"
}

run "bucket_name_has_environment" {
  command = plan

  assert {
    condition     = aws_s3_bucket.assets.bucket == "acme-assets-staging"
    error_message = "O nome do bucket deveria terminar com o ambiente."
  }
}

Desde a 1.7, mock_provider permite testar sem credenciais, simulando as respostas do provider.

O fluxo em equipe

O padrão que funciona: ninguém roda apply em produção da própria máquina. Cada pull request executa fmt, validate, testes e plan, e o plano aparece como comentário no PR para revisão. O apply acontece só depois do merge, pela pipeline, com credenciais que só ela tem. Ferramentas como Atlantis, HCP Terraform, Spacelift e env0 automatizam esse fluxo.

Licença, IBM e OpenTofu

Até a versão 1.5, o Terraform era open source sob a licença MPL 2.0. Em agosto de 2023, a HashiCorp anunciou a troca para a Business Source License (BSL 1.1) a partir das versões seguintes. A BSL permite usar, modificar e redistribuir o Terraform, inclusive comercialmente, exceto para oferecer um produto que concorra com os da HashiCorp. Para quem só usa o Terraform para gerenciar a própria infraestrutura, nada muda na prática; para empresas que vendiam plataformas de automação de Terraform, mudou tudo.

A reação foi um fork: o OpenTofu, criado em agosto de 2023 (primeiro como OpenTF) e mantido sob a Linux Foundation, com licença MPL. Em fevereiro de 2025, a IBM concluiu a compra da HashiCorp por 6,4 bilhões de dólares.

Os dois projetos partiram do mesmo código e continuam muito parecidos (mesma linguagem, mesmos providers, comandos equivalentes com tofu no lugar de terraform), mas divergem a cada versão:

A migração de Terraform para OpenTofu (ou o contrário) é simples em configurações mais antigas e fica mais trabalhosa conforme você adota recursos exclusivos de um dos lados. Os números de versão não se correspondem: OpenTofu 1.13 não equivale a Terraform 1.13.

Novidades recentes

Fora do CLI, o HCP Terraform (antigo Terraform Cloud) ganhou os Stacks, estáveis desde setembro de 2025: um jeito de implantar vários módulos e ambientes juntos, com as dependências entre eles resolvidas pela plataforma. É um recurso do serviço pago, não do binário.

Sintomas e causas

Limites

• Não é contínuo. Sem execuções periódicas, o drift fica invisível (veja acima).
• O state é um ponto sensível. Ele concentra segredos e é a fonte da verdade; perder ou corromper o state é um incidente.
• apply não é transacional. Se o apply falha no meio, o que já foi criado fica criado. O state registra o progresso, e o próximo apply continua de onde parou, mas não há rollback automático.
• HCL não é uma linguagem de programação completa. Lógica complexa com for, condicionais e funções fica difícil de ler rápido. Quem prefere escrever infraestrutura em TypeScript, Python ou Go costuma escolher o Pulumi ou o CDK.
• A qualidade depende do provider. Recursos novos de uma nuvem podem demorar a chegar ao provider, e cada provider tem suas peculiaridades.
• Não configura o que roda dentro da máquina. Instalar pacotes e configurar o sistema operacional é trabalho para imagens prontas (Packer, containers) ou ferramentas de configuração (Ansible).

Quando usar (e quando não)

Uma divisão comum: o Terraform cria a rede, o cluster Kubernetes e os bancos gerenciados; as aplicações dentro do cluster são implantadas por GitOps.

Veja também: Infraestrutura como código, Kubernetes, Entendendo containers e Os Doze Fatores.

Vídeos

• Terraform in 100 Seconds (Fireship): a ideia geral em menos de dois minutos (é o vídeo embutido no topo).

Referências

• Documentação do Terraform: a referência oficial da linguagem, da CLI e dos backends.
• Tutorial de introdução com Docker: base do laboratório deste guia.
• Backend S3: configuração com use_lockfile e a depreciação do DynamoDB.
• Testes: a sintaxe de .tftest.hcl e mocks.
• Importar recursos: o bloco import e a geração de configuração.
• Changelog do Terraform: o que mudou em cada versão.
• HashiCorp adota a BSL (em inglês): o anúncio da troca de licença, de agosto de 2023.
• OpenTofu: o fork open source, com a documentação e as diferenças em relação ao Terraform.
• Novidades da HashiConf 2025 (em inglês): Stacks estáveis, Terraform search e actions.
• IBM conclui a compra da HashiCorp (TechRepublic, em inglês).