O que é Ingress no Kubernetes
Ingress é um objeto de API do Kubernetes que gerencia o acesso externo aos serviços dentro de um cluster, funcionando como um gerenciador de tráfego HTTP/HTTPS. Ele atua na camada 7 (aplicação) do modelo OSI, permitindo roteamento inteligente baseado em hostname, path e outros atributos da requisição. Sem o Ingress, você estaria limitado a usar NodePort ou LoadBalancer, soluções que não escalam bem e não oferecem flexibilidade de roteamento.
O Ingress não é apenas uma definição — é um conceito que precisa de um controlador para funcionar. O controlador (como Nginx Ingress Controller) monitora objetos Ingress no cluster e configura automaticamente um reverse proxy para rotear o tráfego conforme as regras definidas. Essa separação entre especificação e implementação é um padrão elegante do Kubernetes, permitindo múltiplas implementações.
Nginx Ingress Controller: Arquitetura e Instalação
Entendendo o Componente
O Nginx Ingress Controller é um pod que roda um servidor Nginx e fica continuamente observando os recursos Ingress no cluster. Quando você cria ou modifica um Ingress, o controlador traduz aquelas definições em configurações Nginx nativas e recarrega o servidor. O controlador expõe um serviço LoadBalancer (ou NodePort) que recebe o tráfego externo e o distribui aos pods da aplicação.
A arquitetura é simples: cliente envia requisição para o IP do LoadBalancer → Nginx roda a lógica de roteamento → requisição chega ao serviço apropriado → load balancer do Kubernetes (kube-proxy) entrega ao pod correto. Toda essa cadeia é gerenciada declarativamente através do manifesto Ingress.
Instalando o Nginx Ingress Controller
Você pode instalar o Nginx Ingress Controller usando Helm, que simplifica bastante o processo. O Helm é um gerenciador de pacotes do Kubernetes que empacota componentes complexos em charts reutilizáveis.
# Adicionar o repositório oficial do Nginx Ingress
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
# Instalar em um namespace dedicado
kubectl create namespace ingress-nginx
helm install nginx-ingress ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--set controller.service.type=LoadBalancer
Após a instalação, você terá um pod do controlador rodando e um serviço LoadBalancer aguardando requisições. Verifique o status:
kubectl get svc -n ingress-nginx
kubectl get pods -n ingress-nginx
Caso você esteja em um ambiente local (like Minikube ou Docker Desktop), o LoadBalancer pode ficar em estado pending. Use minikube tunnel ou configure o tipo como NodePort para testes locais.
Roteamento de Tráfego com Ingress
Criando um Ingress Simples
Vamos começar com um exemplo prático. Suponha que você tenha um serviço chamado web-app rodando na porta 8080 e quer expô-lo através de um domínio. Aqui está o manifesto Ingress:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-app-ingress
namespace: default
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-app
port:
number: 8080
Este manifesto diz: "Todo tráfego HTTP para app.example.com deve ser roteado para o serviço web-app na porta 8080". O ingressClassName: nginx explicitamente diz ao cluster qual controlador deve gerenciar este Ingress. O pathType: Prefix significa que qualquer path começando com / será capturado (é o mais comum).
Para aplicar:
kubectl apply -f ingress.yaml
kubectl get ingress
kubectl describe ingress web-app-ingress
Roteamento Baseado em Path
Um padrão muito comum é ter múltiplos serviços e rotear diferentes paths para cada um. Imagine que você tem um backend em um serviço e um frontend em outro:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: multi-service-ingress
namespace: default
spec:
ingressClassName: nginx
rules:
- host: myapp.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api-service
port:
number: 3000
- path: /
pathType: Prefix
backend:
service:
name: web-service
port:
number: 80
Aqui, requisições para myapp.com/api/users vão para api-service, enquanto myapp.com/ (incluindo myapp.com/login) vai para web-service. A ordem importa: o Nginx avalia os paths de cima para baixo, então caminhos mais específicos devem vir primeiro.
Roteamento Baseado em Hostname
Você também pode ter múltiplos hostnames apontando para serviços diferentes no mesmo Ingress:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: virtual-hosts-ingress
namespace: default
spec:
ingressClassName: nginx
rules:
- host: api.mycompany.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api-backend
port:
number: 5000
- host: www.mycompany.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: website
port:
number: 80
- host: admin.mycompany.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: admin-panel
port:
number: 8888
Isso permite você economizar IPs públicos e gerenciar múltiplos serviços com um único ponto de entrada. O Nginx verifica o header Host da requisição e roteia automaticamente.
HTTPS e Certificados TLS
Para usar HTTPS, você precisa adicionar um certificado TLS ao cluster como um Secret e referenciar no Ingress:
# Criar um certificado autoassinado para teste (não use em produção!)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes \
-subj "/CN=myapp.com"
# Criar o Secret
kubectl create secret tls myapp-tls \
--cert=cert.pem \
--key=key.pem \
--namespace=default
Agora referencie no Ingress:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: secure-ingress
namespace: default
spec:
ingressClassName: nginx
tls:
- hosts:
- myapp.com
secretName: myapp-tls
rules:
- host: myapp.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-app
port:
number: 8080
O Nginx automaticamente configurará SSL/TLS e redireciona HTTP para HTTPS por padrão. Em produção, use certificados gerados pelo cert-manager com Let's Encrypt em vez de certificados autoassinados.
Configurações Avançadas e Troubleshooting
Annotations para Controle Fino
O Nginx Ingress Controller aceita annotations que permitem ajustar comportamentos específicos sem modificar o Nginx manualmente. Algumas das mais úteis:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: advanced-ingress
namespace: default
annotations:
# Redirecionar HTTP para HTTPS
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
# Rate limiting (máximo 10 requisições por segundo por IP)
nginx.ingress.kubernetes.io/limit-rps: "10"
# CORS habilitado
nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
# Reescrever URL (remover /api do path antes de enviar ao backend)
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /api(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: backend
port:
number: 3000
A annotation rewrite-target é particularmente poderosa. Se o seu backend espera /users mas o cliente chama /api/users, você reescreve removendo o prefixo /api.
Debugging e Troubleshooting
Quando algo não funciona, comece verificando os logs do controlador:
# Ver logs do Nginx Ingress Controller
kubectl logs -n ingress-nginx deployment/nginx-ingress-ingress-nginx-controller -f
# Verificar configuração gerada pelo Nginx
kubectl exec -it -n ingress-nginx deployment/nginx-ingress-ingress-nginx-controller -- cat /etc/nginx/nginx.conf | head -100
# Verificar status do Ingress
kubectl describe ingress seu-ingress-name
kubectl get ingress -A -o wide
Um erro comum é não ter o serviço backend pronto ou com o port incorreto. Verifique sempre:
# Confirmar que o serviço existe e está rodando
kubectl get svc seu-servico
kubectl get endpoints seu-servico
# Testar conectividade diretamente
kubectl port-forward svc/seu-servico 8080:8080
# Agora acesse localhost:8080 no seu navegador
Outro problema frequente: o domínio não resolve. Em desenvolvimento, edite seu /etc/hosts (ou C:\Windows\System32\drivers\etc\hosts no Windows):
192.168.1.100 app.example.com
Substitua o IP pelo IP do seu LoadBalancer (veja com kubectl get svc -n ingress-nginx).
Conclusão
O Ingress do Kubernetes com Nginx Controller oferece uma forma declarativa e escalável de gerenciar o acesso externo aos seus serviços. O conceito central é simples — definir regras de roteamento em YAML — mas a flexibilidade é imensa: você controla roteamento por hostname, path, HTTPS, rate limiting e muitos outros aspetos sem tocar em uma única linha de configuração Nginx.
Dois aprendizados práticos que você nunca deve esquecer: primeiro, o Ingress é apenas especificação; o Nginx Ingress Controller é quem materializa aquilo em configuração real, então sem o controlador instalado, seus manifestos Ingress são apenas dados ociosos. Segundo, debugging é sua melhor ferramenta — os logs do controlador e a configuração gerada do Nginx contam toda a história do que está acontecendo e por quê.