Como consumir API de CPF em Terraform para validação em deploys

Para consumir a API de CPF em Terraform, use o data source http com o endpoint https://api.cpfhub.io/cpf/{CPF} e o header x-api-key. Combine com postcondition para interromper o deploy caso a API não responda com sucesso — um padrão útil em pipelines de onboarding, compliance e smoke tests de integração.

O Terraform é a ferramenta de infraestrutura como código mais adotada no mercado. Em cenários onde a infraestrutura precisa provisionar serviços que dependem de validação de CPF — como ambientes de onboarding, compliance ou testes de integração — é possível incluir validações de API diretamente no pipeline de deploy. A documentação oficial do Terraform descreve os provisioners local-exec como o mecanismo recomendado para executar scripts externos durante o provisionamento.

1. Cenários de uso

• Smoke test em deploy -- Verificar se a API da CPFHub.io está acessível antes de provisionar recursos que dependem dela.

• Validação de configuração -- Confirmar que a chave de API é válida durante o terraform apply.

• Provisionamento de serviços -- Configurar variáveis de ambiente com dados da API para containers e lambdas.

• Ambientes de teste -- Validar a integração em ambientes de staging antes de promover para produção.

2. Data source HTTP para teste de conectividade

O Terraform possui o data source http que permite fazer requisições GET durante o planejamento. Use-o para verificar se a API está acessível:

variable "cpfhub_api_key" {
    description = "Chave de API da CPFHub.io"
    type = string
    sensitive = true
}

variable "cpf_teste" {
    description = "CPF para teste de conectividade"
    type = string
    default = "12345678900"
}

data "http" "cpfhub_health_check" {
    url = "https://api.cpfhub.io/cpf/${var.cpf_teste}"

    request_headers = {
    "x-api-key" = var.cpfhub_api_key
    "Accept" = "application/json"
    }

    request_timeout_ms = 5000
}

output "cpfhub_status" {
    value = data.http.cpfhub_health_check.status_code
}

output "cpfhub_response" {
    value = jsondecode(data.http.cpfhub_health_check.response_body)
    sensitive = true
}

3. Validação condicional com precondition

Use precondition para bloquear o deploy caso a API não responda com sucesso:

data "http" "cpfhub_validation" {
    url = "https://api.cpfhub.io/cpf/${var.cpf_teste}"

    request_headers = {
    "x-api-key" = var.cpfhub_api_key
    "Accept" = "application/json"
    }

    request_timeout_ms = 5000

    lifecycle {
    postcondition {
    condition = self.status_code == 200
    error_message = "CPFHub API não está acessível. Deploy bloqueado."
    }
    }
}

resource "aws_ssm_parameter" "cpfhub_api_key" {
    depends_on = [data.http.cpfhub_validation]

    name = "/app/cpfhub/api-key"
    type = "SecureString"
    value = var.cpfhub_api_key
}

Se a API retornar um código diferente de 200, o terraform apply será interrompido com a mensagem de erro.

4. Provisionamento de variáveis para containers

Após validar a API, provisione as variáveis de ambiente para seus containers:

resource "aws_ecs_task_definition" "app" {
    family = "app-service"
    container_definitions = jsonencode([
    {
    name = "app"
    image = "sua-imagem:latest"
    environment = [
    {
    name = "CPFHUB_BASE_URL"
    value = "https://api.cpfhub.io"
    }
    ]
    secrets = [
    {
    name = "CPFHUB_API_KEY"
    valueFrom = aws_ssm_parameter.cpfhub_api_key.arn
    }
    ]
    }
    ])
}

5. Script de validação com local-exec

Para validações mais elaboradas, use o provisioner local-exec com um script que consulta a API:

resource "null_resource" "cpfhub_integration_test" {
    provisioner "local-exec" {
    command = <<-EOT
    response=$(curl -s -w "\n%%{http_code}" \
    --max-time 5 \
    -H "x-api-key: ${var.cpfhub_api_key}" \
    -H "Accept: application/json" \
    "https://api.cpfhub.io/cpf/${var.cpf_teste}")

    http_code=$(echo "$response" | tail -1)
    body=$(echo "$response" | head -1)

    if [ "$http_code" != "200" ]; then
    echo "ERRO: API CPFHub retornou HTTP $http_code"
    exit 1
    fi

    echo "API CPFHub validada com sucesso: $body"
    EOT
    }

    triggers = {
    always_run = timestamp()
    }
}

6. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON com os dados cadastrais do titular em ~900ms:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

7. Variáveis e backend seguro

Armazene a chave de API de forma segura, nunca em texto plano nos arquivos .tf:

# terraform.tfvars (não comitar no repositório)
cpfhub_api_key = "SUA_CHAVE_DE_API"

Ou passe via variável de ambiente:

export TF_VAR_cpfhub_api_key="SUA_CHAVE_DE_API"
terraform apply

Adicione terraform.tfvars ao .gitignore para evitar exposição acidental.

8. Boas práticas

• Timeout -- Sempre configure request_timeout_ms no data source HTTP e --max-time no cURL para evitar que o pipeline trave indefinidamente.

• Sensitive -- Marque variáveis com sensitive = true para ocultar valores nos logs do Terraform.

• Postcondition -- Use postconditions para bloquear deploys quando dependências externas estão indisponíveis.

• Idempotência -- O data source HTTP é lido a cada plan/apply. Use null_resource com triggers para controlar quando a validação é executada.

• Ambientes -- Mantenha chaves de API diferentes para staging e produção usando workspaces ou backend separado.

Perguntas frequentes

Por que usar o data source HTTP do Terraform para validar a API de CPF?

O data source http executa durante o terraform plan, antes de qualquer recurso ser criado. Isso significa que a falha de conectividade com a API é detectada antes do deploy, evitando provisionamento parcial em ambientes que dependem da consulta de CPF para funcionar corretamente.

Como armazenar a chave de API do CPFHub.io de forma segura no Terraform?

Nunca escreva a chave diretamente em arquivos .tf. Use variáveis do tipo sensitive = true e passe o valor via variável de ambiente (TF_VAR_cpfhub_api_key) ou via AWS Secrets Manager / HashiCorp Vault. Adicione terraform.tfvars ao .gitignore para evitar exposição acidental em repositórios.

O postcondition bloqueia o deploy se a API estiver lenta?

O postcondition verifica apenas o código HTTP retornado — se for 200, o deploy prossegue. Para evitar falsos bloqueios por latência, configure request_timeout_ms com valor adequado (recomendado: 5000ms a 10000ms), já que a API tem latência média de ~900ms.

Posso usar a validação de CPF no Terraform para ambientes de staging e produção ao mesmo tempo?

Sim. Use workspaces do Terraform ou backends separados para cada ambiente, com variáveis de API key distintas por workspace. Isso garante que um smoke test de staging não consuma cota do ambiente de produção e vice-versa.

Conclusão

Integrar a validação da API da CPFHub.io diretamente no pipeline Terraform adiciona uma camada de segurança ao processo de deploy: se a dependência externa não estiver disponível ou mal configurada, o provisionamento para antes de criar recursos com comportamento incorreto. É uma prática especialmente útil em ambientes de onboarding e compliance, onde a consulta de CPF é crítica para o funcionamento do serviço.

Comece com o data source http para smoke tests simples e evolua para null_resource com local-exec quando precisar de validações mais elaboradas — como comparação de dados ou geração de evidências de auditoria.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.