Diagrama de Kubernetes Ingress: o fluxo de tráfego, visualizado

Quase toda documentação de arquitetura tem um: uma caixa escrita "Ingress" e uma seta apontando direto para uma fileira de Pods. Parece certo até alguém, depurando um 502, perguntar onde o TLS termina, qual proxy segura a conexão ou por que uma NetworkPolicy bloqueia um tráfego que "passa pelo Ingress". Um bom diagrama de Kubernetes Ingress responde a essas perguntas antes que alguém precise fazê-las. Neste post você segue o caminho da requisição salto a salto, mapeia um manifesto Ingress mínimo em caixas e setas, vê os erros que mais aparecem em revisões e aprende a montar o mesmo diagrama no Archboard.

O caminho da requisição, salto a salto

Acompanhe https://shop.example.com/api/orders do cliente até um contêiner:

1. Cliente → DNS. O cliente resolve shop.example.com. O registro (A/AAAA, CNAME ou um alias do provedor) aponta para o load balancer da nuvem, não para um node.
2. DNS → load balancer da nuvem. O cliente se conecta ao load balancer. Na maioria dos clusters ele existe porque o Ingress controller é exposto por um Service do type: LoadBalancer, e a integração com a nuvem o provisiona para encaminhar às node ports ou direto aos Pods do controller.
3. Load balancer → Ingress controller. O controller é um workload comum (um Deployment ou DaemonSet) rodando um proxy reverso como NGINX, Envoy, HAProxy ou Traefik. É ele que aceita as conexões e faz o proxy das requisições.
4. Regras do Ingress (host/path). O controller observa os objetos Ingress da sua classe e os transforma em configuração de proxy. O objeto Ingress em si não toca em nenhum pacote. Ele é configuração.
5. Service (ClusterIP). Cada regra aponta para o nome e a porta de um Service. O Service fornece um nome estável e seleciona Pods por label.
6. EndpointSlices. O control plane registra os IPs dos Pods por trás de cada Service, com uma condição ready para cada um, em objetos EndpointSlice. Muitos controllers, inclusive o ingress-nginx, leem os EndpointSlices e mandam o tráfego direto para os IPs dos Pods em vez do ClusterIP. Mesmo assim o Service precisa existir: é por ele que o controller encontra esses endpoints.
7. Pods. A requisição chega a uma porta de contêiner em um dos Pods prontos.

Uma observação sobre o ingress-nginx: o controller comunitário ingress-nginx foi aposentado em março de 2026 e não recebe mais versões, correções de bugs nem patches de segurança. Ele continua sendo o exemplo mais conhecido; para um cluster novo, escolha um controller mantido ou a Gateway API.

Terminação TLS: escolha uma fronteira e desenhe

Há três lugares comuns onde o HTTPS termina:

O Secret precisa estar no mesmo namespace do Ingress que o referencia. Se você termina no load balancer e criptografa de novo até o controller, desenhe dois segmentos TLS, não um.

Roteamento por host vs. por path

• Roteamento por host envia hostnames diferentes para backends diferentes (shop.example.com vs. admin.example.com). Desenhe um grupo de conexões por host.
• Roteamento por path divide um mesmo host pelo caminho da URL. Com pathType: Prefix, a comparação é feita por elementos do caminho separados por /, então /api casa com /api/orders, mas não com /apiv2. Exact casa só com aquele caminho; ImplementationSpecific depende do controller.
• Quando vários paths casam, o mais longo vence. A maioria dos Ingresses reais combina regras de host e de path.

Onde a NetworkPolicy se aplica

A NetworkPolicy filtra o tráfego de Pods em L3/L4, e só quando o plugin de rede do cluster a aplica. Ela não sabe nada de hosts ou paths e não se prende ao objeto Ingress. No diagrama, o salto que ela governa é Pods do controller → Pods da aplicação. Se o namespace da aplicação tem uma policy default-deny de entrada, adicione outra que permita tráfego vindo do namespace do controller, por exemplo com um namespaceSelector em kubernetes.io/metadata.name: ingress-nginx. O salto load balancer → controller é governado pelas regras de firewall da nuvem e pelas policies que existirem no namespace do controller.

Várias classes de Ingress

Clusters costumam rodar mais de um controller: público e interno, ou antigo e novo durante uma migração. Cada controller assume uma IngressClass, e cada Ingress escolhe uma com spec.ingressClassName. Uma classe pode ser marcada como padrão com a anotação ingressclass.kubernetes.io/is-default-class: "true". Dê a cada controller seu próprio caminho a partir do seu próprio load balancer e rotule cada Ingress com sua classe; senão, quem lê vai supor que um único proxy cuida de tudo.

Gateway API, em poucas palavras

A Gateway API (gateway.networking.k8s.io) é a alternativa mais nova, orientada a papéis: uma GatewayClass descreve a implementação, um Gateway define listeners e TLS (normalmente responsabilidade do time de plataforma) e as HTTPRoutes carregam as regras de roteamento (normalmente responsabilidade dos times de aplicação). O roteamento HTTP principal é GA desde a v1.0, em 2023. A API Ingress continua GA e suportada, mas está congelada: não recebe novos recursos. O diagrama quase não muda: o Gateway ocupa o lugar do listener do controller, e as HTTPRoutes, o das regras do Ingress.

Um Ingress mínimo, mapeado no diagrama de Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - shop.example.com
      secretName: shop-example-com-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: orders-api
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: storefront
                port:
                  number: 80

/api/orders casa com os dois paths; /api é mais longo, então a requisição vai para orders-api.

Erros comuns

• Desenhar o Ingress como se fosse o proxy. LB → Ingress → Pods dá a entender que o Ingress é um Pod. O proxy é o controller; o Ingress é a configuração que ele lê. Coloque o controller no caminho dos dados e pendure o Ingress nele com uma conexão tracejada.
• Omitir o Service. Os backends de um Ingress referenciam Services, não Pods. Mesmo quando o tráfego vai direto para os IPs dos Pods, é o seletor do Service que quebra quando os labels saem de sincronia, então mantenha-o no diagrama.
• Sem fronteira TLS. Se o diagrama não mostra onde o HTTPS termina, ninguém consegue dizer se o tráfego dentro da VPC trafega em texto puro.
• Uma NetworkPolicy solta. Uma policy sem conexão com o salto que ela governa não explica nada.

Como montar no Archboard

O pack Kubernetes do Archboard tem nós de primeira classe com portas para os objetos acima, incluindo IngressClass, Gateway e Route, e o pack Network cobre o DNS e o load balancer. A versão pronta é o diagrama abaixo, e Abrir no Archboard copia o diagrama para o seu espaço de trabalho; /examples/kubernetes-ingress-flow é um esboço menor de Ingress → Service → Pods. Para montar por conta própria:

1. Crie um diagrama e posicione um cliente (uma Box ou um Icon do Core, ou uma Person do C4), depois um node de DNS e um node de load balancer do pack Network.
2. Adicione um frame Namespace chamado ingress-nginx com um Deployment e um Pod para o controller. A conexão vinda do load balancer vai para esse Pod, porque ele é o proxy.
3. Adicione um segundo frame Namespace chamado shop. Dentro dele, coloque o Ingress, um Secret (shop-example-com-tls) e dois nodes Service, orders-api e storefront, cada um ligado a um Deployment e a um Pod.
4. Conecte as portas ao longo do caminho dos dados: cliente → DNS → load balancer → Pod do controller → cada Service (rotule as conexões /api e /) → Pods. Rotule as conexões Service → Pod como "EndpointSlices" para mostrar como o tráfego chega aos Pods.
5. Ligue o controller ao Ingress com uma conexão tracejada "observa", e o Secret ao Ingress.
6. Adicione um node NetworkPolicy no frame shop e ligue-o ao salto controller → aplicação que ele permite.
7. Marque a fronteira TLS com um Frame ou uma Box do Core em volta do segmento criptografado, indicando onde ela termina.
8. Cole o YAML do Ingress em um bloco Markdown no canvas, ao lado das caixas que ele descreve.

O plano Free permite 15 nós de diagrama por diagrama, mais 150 notas e textos. A montagem completa acima usa 18, então tire os três nodes Deployment, incluindo o do controller, e ligue os Services direto aos Pods; o caminho do tráfego continua intacto. Exporte como SVG ou PNG (com marca d'água no Free) ou como JSON estruturado para guardar junto dos seus manifestos. Para a visão geral do cluster, veja /examples/kubernetes-microservices e Archboard para Kubernetes. A referência oficial é a documentação do Kubernetes sobre Ingress.

Perguntas frequentes

O Ingress fica dentro do namespace da aplicação? Sim. Ingress é um objeto com namespace e só pode referenciar Services e Secrets TLS do próprio namespace. O controller normalmente roda em um namespace separado.

O tráfego passa pelo ClusterIP do Service? Depende do controller. Muitos fazem proxy direto para os IPs dos Pods a partir dos EndpointSlices. Desenhe o Service mesmo assim e rotule a conexão.

Ingress ou Gateway API para um cluster novo? Gateway API, se o seu controller suportar: a API Ingress está congelada. O método do diagrama é o mesmo.

Comece grátis — um assento, sem cartão de crédito