kubectl + cURL - Validando APIs internas em Kubernetes

Quando um microserviço roda dentro do cluster, bater nele via curl parece simples mas pode não ser, pois podem aparecer erros 404, dúvidas de namespace, ou incertezas sobre qual é a rota real/correta.
Este guia reúne o fluxo completo pra você sair do zero até um teste confiável com comandos prontos para serem utilizados. Ao final, você vai ser capaz de validar com tranquilidade se seu serviço está rodando e com as rotas publicadas.

Cenário

Imagine o seguinte cenário onde você consegue acessar o cluster com o kubectl e quer testar endpoints HTTP de um serviço interno. Por exemplo:

• API: ms-my-service-api
• Namespace: ms-my-service
• Service Port: 80

1. Descubra em qual cluster/contexto você está:

Primeiro, valide o contexto ativo no kubectl:

kubectl config current-context

Para ver todos os contextos disponíveis:

kubectl config get-contexts

Para ver apenas o cluster do contexto atual:

kubectl config view --minify -o jsonpath='{.contexts[0].context.cluster}{"\n"}'

Para ver URL do API server:

kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}{"\n"}'

2. Descubra/valide namespace e service

Para listar os namespaces disponíveis:

kubectl get ns

Buscar service em todos os namespaces:

kubectl get svc -A | grep ms-my-service-api

Inspecionar os detalhes do service:

kubectl -n ms-my-service get svc ms-my-service-api -o yaml

Exemplo de trecho relevante encontrado no arquivo YAML de detalhes do service:

ports:
  - port: 80
    protocol: TCP
    targetPort: 8080

3. Faça port-forward do service

Com os dados acima, o comando fica:

kubectl -n ms-my-service port-forward svc/ms-my-service-api 8080:80

Agora, no seu host local, o serviço responde em http://localhost:8080.

(!) NÃo feche o terminal onde você rodou o port-forward. Ele deve ficar em execução durante os testes.

4. Teste básico com curl

Sem path específico:

curl -i http://localhost:8080/

Healthchecks comuns:

curl -i http://localhost:8080/health
curl -i http://localhost:8080/ready
curl -i http://localhost:8080/metrics

5. Entendendo o 404 page not found

Se o port-forward está ativo e você recebe 404, isso normalmente significa:

1. O túnel está ok.
2. A rota chamada não existe na aplicação naquele path/método.

Por exemplo: se GET /metrics retornar 404, pode indicar:

• path incorreto (/api/v1/metrics etc.)
• método incorreto (endpoint espera POST, por exemplo)
• rota publicada só via gateway com rewrite (prefixo diferente)
• docs/roteamento não carregados no ambiente

6. Como listar “rotas publicadas”

O Kubernetes não lista rotas HTTP da sua aplicação. Ele conhece service, porta e endpoints (IP dos pods).

Pra descobrir as rotas da que sua API possui, use:

6.1 Swagger/OpenAPI (se existir)

curl -i http://localhost:8080/swagger
curl -i http://localhost:8080/swagger/index.html
curl -i http://localhost:8080/openapi.json
curl -i http://localhost:8080/docs

6.2 Código da aplicação (quando você tem acesso)

Procurar definições de rotas/handlers no projeto.

7. Como listar pods de um service

Primeiro, veja qual é o selector do seu service:

kubectl -n ms-my-service get svc ms-my-service-api -o yaml

Depois, liste os pods pelo selector (exemplo)

kubectl -n ms-my-service get pods -l app=ms-my-service-api

Alternativa direta pra ver quem está atrás do service:

kubectl -n ms-my-service get endpoints ms-my-service-api

Ou, uma visão completa:

kubectl -n ms-my-service describe svc ms-my-service-api

8. Checklist rápido de troubleshooting

Se algo não funcionar, valida as informações nessa ordem:

1. Contexto certo
   • kubectl config current-context
2. Namespace certo
   • kubectl get svc -A | grep <service>
3. Service existe e porta confere
   • kubectl -n <ns> get svc <svc> -o yaml
4. Endpoints ativos (pods saudáveis)
   • kubectl -n <ns> get endpoints <svc>
5. Port-forward subiu sem erro
   • terminal do port-forward precisa ficar aberto
6. Rota/método corretos
   • teste /, /health, docs e OpenAPI

Conclusão

Para testar uma API interna no Kubernetes com rapidez e previsibilidade:

• valide contexto/namespace,
• confirme porta real do service,
• use port-forward para o seu localhost,
• e trate 404 como problema de roteamento da aplicação, não de conexão com cluster.

Esse fluxo evita “tentativa e erro” e acelera muito a depuração de APIs internas.