Como consumir API de CPF em Kubernetes com ConfigMaps e Secrets

Para consumir a API de CPF da CPFHub.io em Kubernetes, armazene a chave de API em um Secret (nunca em um ConfigMap), injete a URL base e o timeout via ConfigMap, e referencie ambos no Deployment por variáveis de ambiente. Esse padrão garante que credenciais nunca apareçam em texto plano nos manifestos e segue as recomendações de gestão de secrets do OWASP e da documentação oficial do Kubernetes. A API retorna dados do titular em ~300ms e não bloqueia consultas ao ultrapassar o limite do plano.

1. Crie o Secret para a chave de API

Nunca armazene chaves de API em ConfigMaps ou no código. Use Secrets do Kubernetes:

kubectl create secret generic cpfhub-credentials \
    --from-literal=api-key=SUA_CHAVE_DE_API

Ou via manifesto YAML (encode em base64):

# cpfhub-secret.yaml
apiVersion: v1
kind: Secret
metadata:
    name: cpfhub-credentials
    namespace: default
type: Opaque
data:
    api-key: U1VBX0NIQVZFX0RFX0FQSQ== # base64 de SUA_CHAVE_DE_API

kubectl apply -f cpfhub-secret.yaml

2. Crie o ConfigMap para configurações

Armazene configurações não sensíveis em um ConfigMap:

# cpfhub-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
    name: cpfhub-config
    namespace: default
data:
    base-url: "https://api.cpfhub.io"
    timeout: "5000"
    rate-limit-delay: "2000"

kubectl apply -f cpfhub-configmap.yaml

3. Deployment da aplicação

Crie o Deployment referenciando o Secret e o ConfigMap:

# cpf-validator-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
    name: cpf-validator
    labels:
    app: cpf-validator
spec:
    replicas: 2
    selector:
    matchLabels:
    app: cpf-validator
    template:
    metadata:
    labels:
    app: cpf-validator
    spec:
    containers:
    - name: cpf-validator
    image: cpf-validator:latest
    ports:
    - containerPort: 3000
    env:
    - name: CPFHUB_API_KEY
    valueFrom:
    secretKeyRef:
    name: cpfhub-credentials
    key: api-key
    - name: CPFHUB_BASE_URL
    valueFrom:
    configMapKeyRef:
    name: cpfhub-config
    key: base-url
    - name: REQUEST_TIMEOUT
    valueFrom:
    configMapKeyRef:
    name: cpfhub-config
    key: timeout
    livenessProbe:
    httpGet:
    path: /health
    port: 3000
    initialDelaySeconds: 10
    periodSeconds: 30
    readinessProbe:
    httpGet:
    path: /health
    port: 3000
    initialDelaySeconds: 5
    periodSeconds: 10
    resources:
    requests:
    memory: "128Mi"
    cpu: "100m"
    limits:
    memory: "256Mi"
    cpu: "200m"

kubectl apply -f cpf-validator-deployment.yaml

4. Service e Ingress

Exponha a aplicação via Service e Ingress:

# cpf-validator-service.yaml
apiVersion: v1
kind: Service
metadata:
    name: cpf-validator-service
spec:
    selector:
    app: cpf-validator
    ports:
    - protocol: TCP
    port: 80
    targetPort: 3000
    type: ClusterIP

5. Código da aplicação

A aplicação Node.js lê as variáveis de ambiente injetadas pelo Kubernetes:

// app.js
const express = require('express');
const app = express();

const CPFHUB_BASE_URL = process.env.CPFHUB_BASE_URL;
const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY;
const REQUEST_TIMEOUT = parseInt(process.env.REQUEST_TIMEOUT || '5000', 10);
const PORT = process.env.PORT || 3000;

if (!CPFHUB_API_KEY) {
    console.error('ERRO: CPFHUB_API_KEY não configurada');
    process.exit(1);
}

app.get('/api/cpf/:cpf', async (req, res) => {
    const cpf = req.params.cpf.replace(/\D/g, '');

    if (cpf.length !== 11) {
    return res.status(400).json({ error: 'CPF deve conter 11 dígitos' });
    }

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT);

    try {
    const response = await fetch(`${CPFHUB_BASE_URL}/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);

    if (!response.ok) {
    return res.status(response.status).json({
    error: `API retornou HTTP ${response.status}`
    });
    }

    const data = await response.json();
    res.json(data);
    } catch (error) {
    clearTimeout(timeoutId);
    res.status(502).json({ error: 'Timeout ou falha na consulta de CPF' });
    }
});

app.get('/health', (req, res) => {
    res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

app.listen(PORT, () => {
    console.log(`Servidor rodando na porta ${PORT}`);
});

6. Exemplo de resposta da API

A API da CPFHub.io

{
    "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. Horizontal Pod Autoscaler

Para escalar automaticamente com base na carga:

# cpf-validator-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
    name: cpf-validator-hpa
spec:
    scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: cpf-validator
    minReplicas: 2
    maxReplicas: 10
    metrics:
    - type: Resource
    resource:
    name: cpu
    target:
    type: Utilization
    averageUtilization: 70

8. Sealed Secrets para GitOps

Se você usa GitOps (ArgoCD, Flux), nunca comite Secrets em texto plano no repositório. Use Sealed Secrets para criptografar:

kubeseal --format yaml < cpfhub-secret.yaml > cpfhub-sealed-secret.yaml
kubectl apply -f cpfhub-sealed-secret.yaml

O Sealed Secret é seguro para ser versionado no Git e será descriptografado apenas dentro do cluster.

9. Boas práticas

• Secrets -- Sempre use Secrets para chaves de API. Nunca armazene em ConfigMaps ou variáveis em texto plano nos manifestos. O OWASP recomenda rotação periódica de credenciais e controle de acesso granular por service account.

• Timeout -- Configure timeout na aplicação (5 segundos) e nos probes do Kubernetes para detectar falhas rapidamente. A API da CPFHub.io opera com latência de ~300ms, então um timeout de 5s oferece margem adequada sem travar pods.

• Probes -- Use liveness e readiness probes para garantir que pods com falhas sejam reiniciados ou removidos do balanceador.

• Resource limits -- Defina requests e limits para evitar que um pod consuma recursos demais.

• RBAC -- Restrinja o acesso a Secrets apenas aos service accounts que precisam.

• Rotação de chaves -- Atualize o Secret e faça rolling restart dos pods sem downtime.

Perguntas frequentes

Por que a chave de API da CPFHub.io deve ficar em um Secret e não em um ConfigMap?

ConfigMaps são projetados para dados de configuração não sensíveis e são armazenados sem criptografia no etcd do cluster. A documentação do Kubernetes deixa explícito que Secrets devem ser usados para credenciais, tokens e chaves de API. O OWASP também recomenda não misturar configurações sensíveis e não sensíveis no mesmo recurso, para facilitar o controle de acesso via RBAC.

Como rotacionar a chave de API sem downtime nos pods?

Gere a nova chave no painel da CPFHub.io, atualize o Secret com kubectl create secret generic cpfhub-credentials --from-literal=api-key=NOVA_CHAVE --dry-run=client -o yaml | kubectl apply -f - e em seguida execute kubectl rollout restart deployment/cpf-validator. O Kubernetes fará o rolling update, substituindo os pods gradualmente sem interrupção de tráfego.

Qual é o impacto da latência de ~300ms da API no dimensionamento do cluster?

Com ~300ms por consulta, um único pod Node.js consegue processar em torno de 60 a 100 consultas por minuto em condições normais, dependendo da concorrência configurada. O HPA garante que novos pods sejam adicionados automaticamente quando a utilização de CPU ultrapassar o threshold definido. Para cargas previsíveis, é recomendável configurar um mínimo de 2 réplicas para garantir disponibilidade durante o rollout.

O que acontece se a API retornar erro durante um deploy em produção?

A configuração de readiness probe impede que pods com falha de comunicação com a API recebam tráfego antes de estarem prontos. O endpoint /health deve validar não só que a aplicação subiu, mas que a variável CPFHUB_API_KEY está presente. A API da CPFHub.io não bloqueia ao atingir o limite do plano — consultas excedentes são cobradas a R$0,15 cada, o que evita interrupções em picos de carga inesperados.

Conclusão

Configurar a integração com a API da CPFHub.io em Kubernetes é direto quando você separa responsabilidades desde o início: Secret para a chave de API, ConfigMap para URL e timeout, Deployment referenciando ambos via variáveis de ambiente. Essa estrutura garante que credenciais nunca apareçam em texto plano nos manifestos e facilita rotações de chave sem downtime.

Com liveness e readiness probes configurados e o HPA ajustando as réplicas automaticamente, a aplicação absorve picos de carga de forma controlada. A API da CPFHub.io responde em ~300ms e nunca bloqueia por volume — consultas acima da cota mensal são cobradas a R$0,15 cada, sem interrupção do serviço.

Comece agora com o plano gratuito em cpfhub.io — 50 consultas por mês sem cartão. O plano Pro (R$149/mês) inclui 1.000 consultas e é adequado para a maioria das operações em produção.