Kubernetes: Configurando um Ingress Controller (NGINX)

🇺🇸 English version here.

Até aqui, para expor uma aplicação fora do cluster, usamos Services do tipo NodePort ou LoadBalancer. Essas abordagens funcionam bem para um serviço isolado, mas se tornam limitadas quando o cluster hospeda várias aplicações, cada uma precisando de seu próprio domínio (ou subdomínio), possivelmente com HTTPS — gerenciar uma porta NodePort diferente para cada aplicação não escala bem.

É para resolver esse problema que existe o Ingress: um objeto do Kubernetes que centraliza o roteamento HTTP/HTTPS de múltiplos domínios para os Services corretos, através de um único ponto de entrada. Para o Ingress funcionar, é preciso ter um Ingress Controller instalado no cluster — neste artigo, usamos o mais popular deles, o ingress-nginx.

Instalando o Ingress Controller via Helm

O projeto oficial do ingress-nginx disponibiliza um chart Helm pronto para uso:

🔗 https://kubernetes.github.io/ingress-nginx/

Para instalar (ou atualizar, caso já exista) o controller em um namespace dedicado:

helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx --create-namespace

Vale reparar no uso de helm upgrade --install em vez de helm install: essa combinação instala o chart caso ele ainda não exista, ou atualiza a instalação existente — útil tanto para a primeira instalação quanto para futuras atualizações de versão, sem precisar decorar dois comandos diferentes.

A flag --create-namespace cria automaticamente o namespace ingress-nginx, caso ele ainda não exista.

Criando um Ingress

Com o controller instalado, o próximo passo é criar os manifestos do tipo Ingress, que definem as regras de roteamento — qual domínio (host) direciona para qual Service do cluster.

Um exemplo com múltiplos domínios, cada um apontando para um Service diferente:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-hosts
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: api.bagarote.com.br
    http:
      paths:
      - pathType: "Prefix"
        path: "/"
        backend:
          service:
            name: api
            port:
              number: 8082
  - host: adm.bagarote.com.br
    http:
      paths:
      - pathType: "Prefix"
        path: "/"
        backend:
          service:
            name: adm
            port:
              number: 80
  - host: site.bagarote.com.br
    http:
      paths:
      - pathType: "Prefix"
        path: "/"
        backend:
          service:
            name: site
            port:
              number: 80

Repare na estrutura:

• Cada item em rules representa um domínio diferente (host);
• Dentro de cada regra, paths define quais caminhos daquele domínio são roteados e para qual service (com o respectivo port) o tráfego deve ir;
• pathType: "Prefix" significa que qualquer URL começando com o path informado (neste caso, /, ou seja, tudo) será roteada para aquele backend.

Nesse exemplo, três domínios diferentes (api, adm e site, todos sob bagarote.com.br) são roteados através do mesmo Ingress Controller, cada um para o Service correspondente já existente no cluster.

Aplicando o manifesto:

kubectl apply -f ingress.yaml

Apontando o DNS

Para que esse Ingress funcione na prática, os domínios configurados (api.bagarote.com.br, adm.bagarote.com.br, site.bagarote.com.br, no exemplo) precisam ter seus registros DNS apontando para o IP externo do Ingress Controller — geralmente o IP de um dos nós do cluster (ou de um load balancer, em ambientes com um provisionado).

Para descobrir o IP e a porta expostos pelo controller:

kubectl get service -n ingress-nginx

Considerações finais

Com o Ingress Controller instalado e os domínios roteados corretamente, o cluster passa a expor múltiplas aplicações através de um único ponto de entrada, usando nomes de domínio em vez de portas avulsas — uma configuração muito mais próxima do que se espera de um ambiente de produção. O próximo passo natural a partir daqui é adicionar HTTPS a esses domínios, automatizando a emissão de certificados TLS — tema do próximo artigo desta série de addons, sobre o cert-manager.