O que o terraform validate realmente verifica?

O terraform validate é um subcomando embutido do Terraform que faz análise estática dos seus arquivos de configuração. Ele lê cada arquivo .tf e .tfvars do diretório de trabalho atual (e, recursivamente, os módulos locais), analisa e verifica se a configuração é internamente consistente e estruturalmente válida.

Análise estática, não execução

A característica principal do terraform validate é ser totalmente estático. Nenhuma conexão de rede é feita, nenhuma API de provedor é chamada e nenhum arquivo de estado é lido. A verificação acontece inteiramente em memória, na máquina que executa o comando. Isso o torna seguro em qualquer ambiente, inclusive runners de CI sem credenciais de nuvem, e ele termina em menos de dois segundos na maioria das configurações reais.

Isso contrasta com o terraform plan, que faz todas essas verificações estáticas e então se conecta às APIs dos provedores para calcular um diff em relação à infraestrutura real. O validate é o primeiro filtro leve; o plan é o filtro completo antes de aplicar. Rodar os dois em sequência dá a maior cobertura antes de você assumir qualquer mudança de infraestrutura.

Os três modos de operação

• Modo padrão: roda após o terraform init; verifica sintaxe, esquema contra os plugins de provedor baixados e referências entre arquivos
• Sem init: se o diretório .terraform não existir, o validate ainda roda, mas pula as verificações de esquema do provedor e reporta apenas erros de análise HCL e problemas de referência que consegue resolver sem metadados do provedor
• Modo JSON (-json): emite um objeto JSON estruturado com um booleano valid, um inteiro error_count e um array diagnostics adequado para análise em CI e integrações com editores

Entender as três categorias cobertas pelo terraform validate ajuda a saber exatamente o que passar na validação garante, e onde essa garantia termina.

1. Correção da sintaxe HCL

A primeira passada analisa cada arquivo .tf em busca de sintaxe HCL2 válida. Isso captura chaves não fechadas, sinais de igual ausentes em atribuições de atributos, definições de bloco inválidas, uso incorreto da sintaxe heredoc e qualquer outra construção que não seja HCL válido. Um arquivo que falha nessa verificação não pode ser lido pelo Terraform de forma alguma: plan e apply também falhariam. O validate captura esses erros imediatamente, com o caminho do arquivo e o número da linha.

2. Conformidade com o esquema do provedor

Depois da análise, o validate verifica cada bloco de recurso, bloco de fonte de dados e configuração de provedor contra o esquema definido pelo plugin de provedor correspondente. Os esquemas especificam quais argumentos são válidos, quais são obrigatórios e quais opcionais, e qual tipo cada argumento espera (string, number, bool, list, map, object). O validate captura um argumento que não existe para determinado tipo de recurso, um argumento com tipo errado (por exemplo, passar uma string onde se espera um número) e um argumento obrigatório totalmente ausente.

3. Validade das referências internas

A terceira categoria é a verificação de referências cruzadas dentro da configuração. Configurações Terraform referenciam com frequência outros recursos, variáveis, locals, saídas de módulos e fontes de dados por nome. O validate verifica se cada referência (por exemplo var.region, local.common_tags, aws_vpc.main.id, module.networking.subnet_ids) aponta para algo realmente declarado em algum lugar da configuração. Uma variável não declarada, um erro de digitação em uma referência de recurso ou uma saída de módulo ausente serão detectados aqui.

Os limites do terraform validate são tão importantes quanto o que ele cobre. Muitos desenvolvedores descobrem esses limites quando uma configuração que passou na validação falha na hora de aplicar. Cada uma dessas categorias exige terraform plan, testes de integração ou ferramentas de política como tflint ou Checkov.

Valores reais dos argumentos de recursos

O validate verifica se um argumento existe e tem o tipo certo, mas não consegue verificar se o valor é válido no mundo real. Um recurso aws_instance pode ter um argumento ami que seja string (correto em tipo), mas o validate não tem como saber se aquele AMI ID específico existe na sua conta ou região da AWS. Um AMI inválido, um ID de security group inexistente ou um nome de zona de disponibilidade incorreto passam no validate e só falham no plan ou no apply.

Arquivo de estado e infraestrutura existente

O validate nunca lê o seu arquivo de estado do Terraform. Ele não consegue detectar que um recurso que você está definindo conflita com outro que já existe, que um recurso foi excluído fora do Terraform (desvio de estado) ou que uma mudança planejada viola uma restrição que só pode ser avaliada contra a infraestrutura real atual. Tudo isso são questões das fases de plan e apply.

Expressões dinâmicas que dependem de fontes de dados

Expressões count, for_each e condicionais são HCL válido e o validate as analisa sem problema. Mas se os valores dependerem de uma fonte de dados (por exemplo for_each = toset(data.aws_availability_zones.available.names)), a expressão não pode ser totalmente avaliada no momento da validação, porque a fonte de dados ainda não foi consultada. O validate confirma que a sintaxe da expressão está correta; não consegue confirmar o resultado em execução.

Autenticação e permissões do provedor

O validate não faz nenhuma chamada de API. Ele não detectará que suas credenciais da AWS expiraram, que sua conta de serviço não tem as permissões IAM necessárias ou que a configuração do provedor aponta para a região ou o projeto errados. Todos os erros de autenticação só aparecem na fase de plan ou apply, quando o cliente do provedor é realmente inicializado e as chamadas são feitas.

Políticas de segurança e regras de conformidade

O validate não tem nenhuma noção de política de segurança. Um bucket S3 configurado como público, uma instância EC2 sem criptografia ou um security group com entrada 0.0.0.0/0 na porta 22 passam no validate sem qualquer aviso. Verificações de segurança e conformidade exigem ferramentas de política dedicadas, como Checkov, tfsec ou HashiCorp Sentinel.

A maior fonte de confusão sobre o terraform validate é como ele difere do terraform plan. Eles se sobrepõem bastante, mas operam em níveis diferentes, e os dois são necessários para um fluxo completo antes de aplicar.

O terraform validate verifica se uma configuração é sintaticamente válida e internamente consistente, independentemente das variáveis fornecidas ou do estado existente.

Onde eles se sobrepõem

Os dois comandos analisam seus arquivos HCL e buscam erros de sintaxe. Os dois verificam esquemas de provedor quando os plugins estão disponíveis. Os dois validam referências internas. Um erro de configuração capturado pelo terraform validate também seria capturado pelo terraform plan: o validate é simplesmente mais rápido e não exige credenciais de nuvem nem backend de estado.

Até onde o plan vai além

O terraform plan inicializa clientes de provedor, autentica nas APIs de nuvem, lê o estado atual e consulta fontes de dados. Isso permite capturar o que o validate não consegue: um valor de argumento que a API do provedor rejeita, uma consulta a fonte de dados com resultados inesperados, erros de cota ou limite de requisições e conflitos entre a configuração proposta e a infraestrutura existente registrada no estado.

Rodar o terraform validate é simples, mas as etapas ao redor importam para aproveitar bem o comando.

# Validação básica
terraform validate

# Saída JSON para análise no CI
terraform validate -json

# Exemplo de estrutura da saída JSON
{
  "valid": false,
  "error_count": 2,
  "diagnostics": [
    {
      "severity": "error",
      "summary": "Unsupported argument",
      "detail": "An argument named 'regoin' is not expected here. Did you mean 'region'?",
      "range": {
        "filename": "main.tf",
        "start": { "line": 8, "column": 3 }
      }
    }
  ]
}

O terraform validate se encaixa naturalmente em pipelines de CI porque não exige credenciais de nuvem, roda em segundos e captura a maioria dos erros de autoria antes que consumam uma execução de plan ou cheguem a uma revisão de código. O padrão usual é rodá-lo em cada pull request que altera arquivos .tf.

Exemplo no GitHub Actions

O workflow abaixo instala o Terraform, roda init com -backend=false para não precisar de credenciais de state e roda validate. Se o validate falhar, o workflow termina com código diferente de zero e bloqueia a fusão do pull request.

name: Terraform Validate

on:
  pull_request:
    paths:
      - '**.tf'
      - '**.tfvars'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: '1.8.0'

      - name: Terraform Init (no backend)
        run: terraform init -backend=false

      - name: Terraform Validate
        run: terraform validate -json | tee validate-output.json
        # Exit code 1 on any error - fails the workflow automatically

Combinar o validate com o tflint

O tflint é um linter que captura problemas que o terraform validate deixa passar: verificações de regras específicas do provedor (como tipos de instância da AWS inválidos), declarações não usadas e regras de política próprias. Rodar o tflint depois do validate no mesmo job de CI dá cobertura de análise estática mais ampla. O tflint tem plugins de regras específicos para AWS, Azure e GCP que verificam valores de argumentos contra opções válidas conhecidas, capturando erros que a verificação genérica de esquema do validate não vê.

• terraform fmt -check: verifica se o código segue as convenções de estilo do Terraform (falha se algum arquivo precisar de reformatação)
• terraform validate: verifica sintaxe, conformidade com o esquema e referências internas
• tflint: regras específicas do provedor, detecção de variáveis não usadas, aplicação de políticas próprias
• Checkov ou tfsec: varredura de políticas de segurança e conformidade
• terraform plan: validação em execução em um ambiente de staging com credenciais reais

O terraform validate é uma base, não um teto. Um fluxo de trabalho maduro com Terraform combina várias técnicas de validação para capturar diferentes classes de erro no ponto certo do ciclo de desenvolvimento.

Formate antes de validar

Rode terraform fmt antes do validate em todo fluxo, local e de CI. A formatação canônica de HCL não é só estilo: evita casos-limite em que espaçamento ou posição de comentário inconsistentes escondem erros reais na saída da análise. O Formatador HCL do Aback Tools oferece a mesma normalização no navegador sem precisar do Terraform instalado, útil para revisões rápidas ou para editar em máquinas onde você não pode rodar terraform fmt.

Sempre rode init antes do validate no CI

Rodar o validate sem init dá apenas análise parcial: análise HCL e verificação de referências, mas sem validação do esquema do provedor. Pular as verificações de esquema significa que você pode fundir uma configuração que usa um nome de argumento com erro de digitação ou passa o tipo errado para um atributo de recurso. Os poucos segundos extras que o init -backend=false adiciona ao job de CI valem a cobertura.

Use -json para saída estruturada no CI

A saída legível padrão do validate é clara para depuração local, mas a saída JSON é muito mais útil em pipelines automatizados. Com -json, você pode analisar o array diagnostics para extrair caminhos de arquivo e números de linha, anotar diffs de pull request com comentários de erro na linha usando a API do GitHub Checks, ou enviar erros para uma notificação personalizada no Slack. Analise primeiro o booleano valid: se for true, o array diagnostics ainda pode conter avisos que valem a pena mostrar.

Valide todos os módulos independentemente

O terraform validate em um módulo raiz também verifica os módulos locais chamados, mas módulos remotos só são verificados depois que o init os baixa. Para repositórios de módulos, rode o validate separadamente em cada diretório de módulo durante o desenvolvimento. Isso revela erros de esquema no próprio módulo antes que consumidores cheguem a referenciá-lo.

Mantenha os arquivos .tf formatados antes de commitar

Use um hook de pre-commit que rode terraform fmt -check e falhe se algum arquivo .tf não estiver no formato canônico. Isso mantém todo o código consistente, evita diffs apenas de estilo nas revisões e faz a saída do validate ser mais fácil de ler, porque o código tem estrutura limpa. Remova comentários de desenvolvimento das configurações de produção com o Removedor de comentários do Terraform HCL para manter os arquivos commitados limpos e legíveis.