# Como consumir API de CPF em Kubernetes com ConfigMaps e Secrets

> Aprenda a consumir a API de consulta de CPF da CPFHub.io em Kubernetes usando ConfigMaps, Secrets e boas práticas de deploy.

**Publicado:** 02/04/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://owasp.org) e da [documentação oficial do Kubernetes](https://kubernetes.io/docs). 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:

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

Ou via manifesto YAML (encode em base64):

```yaml
# 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
```

```bash
kubectl apply -f cpfhub-secret.yaml
```

---

## 2. Crie o ConfigMap para configurações

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

```yaml
# 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"
```

```bash
kubectl apply -f cpfhub-configmap.yaml
```

---

## 3. Deployment da aplicação

Crie o Deployment referenciando o Secret e o ConfigMap:

```yaml
# 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"
```

```bash
kubectl apply -f cpf-validator-deployment.yaml
```

---

## 4. Service e Ingress

Exponha a aplicação via Service e Ingress:

```yaml
# 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:

```javascript
// 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**](https://www.cpfhub.io/)

```json
{
 "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:

```yaml
# 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:

```bash
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](https://owasp.org) 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](https://kubernetes.io/docs) deixa explícito que Secrets devem ser usados para credenciais, tokens e chaves de API. O [OWASP](https://owasp.org) 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.

### Leia também

- [SLA de API de CPF: níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [Como implementar cache inteligente em respostas de API de CPF](https://cpfhub.io/blog/como-implementar-cache-inteligente-respostas-api-cpf)
- [Como implementar retry e backoff exponencial em consultas de API de CPF](https://cpfhub.io/blog/como-implementar-retry-backoff-exponencial-consultas-api-cpf)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)

---

## 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](https://www.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.