Terraform e OpenTofu

iac

Os comandos valem para terraform e tofu — troque o binário. Não misture os dois no mesmo state.

Ciclo básico

Comando	O que faz
`terraform init`	Baixa providers e configura o backend
`terraform init -upgrade`	Atualiza providers dentro das restrições
`terraform init -backend=false`	Só providers, sem tocar no state
`terraform plan`	Calcula as mudanças
`terraform plan -out=plano.bin`	Salva o plano para aplicar exatamente ele
`terraform apply plano.bin`	Aplica o plano salvo
`terraform apply -auto-approve`	Sem confirmação (use só no pipeline)
`terraform destroy`	Destrutivo: remove tudo do state
`terraform apply -target=aws_s3_bucket.x`	Aplica um recurso (emergência apenas)
`terraform plan -refresh-only`	Mostra drift, sem propor mudança
`terraform plan -detailed-exitcode`	Sai com 2 se houver diferença (útil em CI)

Símbolos do plano: + cria, ~ altera, - destrói, -/+ destrói e recria — este último merece parar e investigar em recurso com estado.

State

Comando	O que faz
`terraform state list`	Recursos gerenciados
`terraform state show <endereco>`	Atributos de um recurso
`terraform state pull > backup.tfstate`	Backup — faça antes de mexer
`terraform state push arquivo.tfstate`	Sobrescreve o state remoto
`terraform state mv <de> <para>`	Renomeia sem recriar
`terraform state rm <endereco>`	Esquece o recurso (não o destrói)
`terraform import <endereco> <id>`	Traz recurso existente para o state
`terraform force-unlock <id>`	Libera lock preso (confirme que ninguém aplica)
`terraform refresh`	Obsoleto; use `apply -refresh-only`

Blocos preferíveis aos comandos, porque são versionados e revisáveis:

import { to = aws_s3_bucket.relatorios, id = "empresa-relatorios-prod" }
moved  { from = aws_s3_bucket.antigo,   to = aws_s3_bucket.novo }
removed { from = aws_db_instance.legado, lifecycle { destroy = false } }

Formatação, validação e saída

Comando	O que faz
`terraform fmt -recursive`	Formata
`terraform fmt -check -recursive`	Falha se não formatado (CI)
`terraform validate`	Sintaxe e coerência de tipos
`terraform show -json plano.bin > plano.json`	Plano legível por máquina
`terraform output` / `terraform output -raw url`	Saídas
`terraform graph \| dot -Tsvg > grafo.svg`	Grafo de dependências
`terraform providers`	Providers exigidos e versões
`terraform test`	Testes nativos (`*.tftest.hcl`)

Depuração

TF_LOG=DEBUG terraform apply 2> debug.log     # TRACE, DEBUG, INFO, WARN, ERROR
TF_LOG_PROVIDER=DEBUG terraform plan          # só o provider
TF_LOG_PATH=./tf.log TF_LOG=TRACE terraform plan

terraform console            # avalia expressões interativamente
> length(var.subnets)
> [for s in aws_subnet.privada : s.id]
> cidrsubnet("10.20.0.0/16", 4, 3)

Cuidado: TF_LOG=TRACE imprime valores sensíveis. Não guarde esse log em artefato do CI.

Workspaces

Comando	O que faz
`terraform workspace list`	Lista
`terraform workspace show`	Atual — confirme antes de aplicar
`terraform workspace new dev`	Cria
`terraform workspace select dev`	Troca

Workspaces servem para ambientes efêmeros com a mesma configuração. Para separar produção de desenvolvimento, prefira diretórios, backends e credenciais distintos.

Expressões úteis

for_each = toset(["a", "b"])          # chave estável, melhor que count para listas
count    = var.criar ? 1 : 0          # existe ou não existe

lookup(var.mapa, "chave", "padrao")
try(var.opcional.campo, "padrao")
coalesce(var.a, var.b, "padrao")
merge(local.tags_base, var.tags)
one(aws_instance.este[*].id)          # 0 ou 1 elemento → valor ou null

lifecycle {
  prevent_destroy       = true
  create_before_destroy = true
  ignore_changes        = [tags["ultima-modificacao"]]
}

Variáveis de ambiente

Variável	Efeito
`TF_VAR_nome=valor`	Define a variável `nome`
`TF_LOG` / `TF_LOG_PATH`	Nível de log / arquivo
`TF_INPUT=0`	Não pergunta nada (CI)
`TF_IN_AUTOMATION=1`	Reduz dicas interativas na saída
`TF_CLI_ARGS_plan="-lock=false"`	Argumentos padrão por comando

Pegadinhas

O state guarda valores em texto claro, inclusive segredos: proteja e criptografe.
state rm deixa o recurso órfão — continua existindo e cobrando.
-target mascara problemas de dependência; use só em emergência e volte ao plano completo.
count endereça por posição: remover o primeiro item recria os seguintes.
Sem -out, o apply recalcula e pode aplicar algo diferente do que você revisou.
prevent_destroy bloqueia o destroy, mas não impede recriação por mudança de campo imutável.
Commite o .terraform.lock.hcl.