Gateway API x Ingress no Kubernetes: qual escolher

Se você está começando um projeto novo no Kubernetes hoje, a resposta curta é: use Gateway API. Se você já tem Ingress em produção, a resposta é mais matizada — mas a direção é a mesma. Vamos entender por quê.

O fato que resolve a maior parte da dúvida

A documentação oficial do Kubernetes é direta sobre isso. A página de Ingress afirma textualmente: "The Kubernetes project recommends using Gateway instead of Ingress". Não é uma sugestão de comunidade ou uma opinião de terceiros — é o texto oficial do projeto (kubernetes.io/docs/concepts/services-networking/ingress).

E tem um detalhe técnico que reforça essa recomendação: o Ingress atingiu o status Stable desde a v1.19, o que no vocabulário de APIs do Kubernetes significa que ele está congelado (frozen). A API é GA, segue as garantias de estabilidade de uma API GA, o projeto não tem planos de removê-la — mas também não vai receber novas mudanças ou atualizações. Ou seja: o que o Ingress faz hoje é o que ele vai fazer para sempre.

Isso não é um defeito de implementação, é uma decisão de design. O Ingress nasceu para resolver um problema específico (expor HTTP/HTTPS para fora do cluster) e qualquer coisa além disso — matching por header, traffic weighting, roteamento por protocolo — ficou de fora da especificação. Esse vácuo foi preenchido por anotações proprietárias de cada controller, o que quebra a portabilidade entre implementações.

Critérios para decidir

1. O que você precisa expor

O Ingress é explícito sobre sua limitação: ele não expõe portas ou protocolos arbitrários, apenas HTTP e HTTPS. Para qualquer outra coisa, a documentação recomenda recorrer a um Service do tipo NodePort ou LoadBalancer.

A Gateway API não tem essa limitação por design. Ela já nasce "protocol-aware" e tem kinds dedicados — HTTPRoute para HTTP e GRPCRoute para gRPC, por exemplo. Se seu roadmap inclui expor gRPC, TCP ou outros protocolos L4/L7 pelo mesmo mecanismo de roteamento, o Ingress não vai te atender sem gambiarra de Service externo.

2. Quem opera o quê na sua organização

Esse é o ponto mais subestimado na comparação. O Ingress é um recurso único: quem cria o objeto Ingress mistura, no mesmo manifesto, decisão de infraestrutura (qual controller, qual classe) e decisão de roteamento de aplicação (paths, hosts, backend).

A Gateway API separa isso em camadas com papéis organizacionais explícitos:

• Infrastructure Provider — gerencia a infraestrutura que atende múltiplos clusters ou tenants (ex.: um cloud provider).
• Cluster Operator — define políticas, acesso de rede e permissões via GatewayClass e Gateway.
• Application Developer — cuida só do roteamento da própria aplicação via HTTPRoute, sem precisar tocar em infraestrutura.

Se você opera uma plataforma com múltiplos times de desenvolvimento compartilhando um cluster, essa separação de responsabilidades é o argumento mais forte para migrar. O time de plataforma controla o Gateway, cada time de produto controla seu próprio HTTPRoute, e ninguém precisa de permissão sobre o recurso do outro.

Se você é um time pequeno operando um único cluster sem essa divisão de papéis, esse ganho é menos relevante na prática — ainda que a documentação não trate isso como pré-requisito para adoção.

3. Recursos de roteamento que você já usa via anotação

Se seu Ingress atual depende de anotações do controller para fazer header matching, traffic splitting/weighting ou canary release, isso é um sinal direto de que você está pedindo à Gateway API sem saber. A documentação lista esses dois casos — matching por header e traffic weighting — como exemplos explícitos de recursos que a especificação da Gateway API suporta nativamente, enquanto no Ingress "só eram possíveis via anotações customizadas".

Anotação customizada significa dependência de implementação: o manifesto que funciona no NGINX Ingress Controller não necessariamente funciona no Traefik ou no AWS Load Balancer Controller sem reescrita. A Gateway API resolve isso porque as specs são definidas como custom resources portáveis, suportados por várias implementações — a documentação não especifica a lista completa de controllers, então valide suporte à Gateway API no controller específico que você usa antes de migrar.

Modelo de recursos: o que muda no manifesto

Com Ingress, você escreve um objeto só:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
spec:
  ingressClassName: nginx-example
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80

Com Gateway API, o mesmo cenário se divide em pelo menos dois (ou três) objetos, cada um sob responsabilidade de um papel diferente:

# Gerenciado pelo cluster operator (ou pelo controller)
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-class
spec:
  controllerName: example.com/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.example.com"
    allowedRoutes:
      namespaces:
        from: Same
---
# Gerenciado pelo application developer
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: test-route
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /testpath
    backendRefs:
    - name: test
      port: 80

Vale notar o allowedRoutes.namespaces.from: Same no Gateway: por padrão, um Gateway só aceita rotas do mesmo namespace. Se você precisa que HTTPRoute de outros namespaces se conectem a esse Gateway — cenário comum em cluster multi-tenant — isso precisa ser configurado explicitamente. É esse mecanismo que a documentação chama de "modelo de confiança bidirecional" entre Gateway e rotas: o Gateway decide quem pode se anexar a ele, e a rota decide a qual Gateway quer se anexar.

Outro detalhe prático: se você não especificar spec.addresses no Gateway, o controller da implementação atribui um endereço ou hostname automaticamente — comportamento equivalente ao que já acontece com LoadBalancer Services na maioria dos ambientes de nuvem.

Pré-requisito que não muda

Em ambos os modelos, o objeto por si só não faz nada. Tanto Ingress quanto Gateway API dependem de um controller instalado no cluster que implemente a especificação. Criar um Ingress ou um Gateway sem o controller correspondente rodando resulta em um recurso inerte — sem roteamento real acontecendo.

O que este resumo não cobre (e por que importa)

A documentação oficial usada como base para este post não traz comparativos de adoção entre implementações específicas (Istio, NGINX Gateway Fabric, Contour, Envoy Gateway, etc.), nem benchmarks de performance entre Ingress e Gateway API, nem a versão exata em que a Gateway API atingiu GA, nem um guia passo a passo de migração — apenas a recomendação textual de usar Gateway API no lugar de Ingress. Se sua decisão depende de qual controller específico tem suporte maduro a Gateway API no seu provedor de nuvem, essa validação precisa ser feita separadamente, consultando a documentação do controller em questão.

Também não há, no material oficial consultado, detalhes sobre configuração de TLS em nenhum dos dois modelos além de menções de referência — então trate TLS como um tópico a validar na documentação específica antes de ir para produção.

Recomendação condicionada

• Projeto novo, sem Ingress legado: comece direto em Gateway API. Não há razão para investir em uma API congelada quando a alternativa recomendada pelo próprio projeto já está disponível.
• Ingress em produção, funcionando, sem necessidade de header matching/weighting/multi-protocolo: não há urgência técnica para migrar agora. O Ingress continua GA e suportado — só não vai evoluir.
• Ingress em produção com anotações proprietárias do controller para contornar limitações de roteamento: isso é o sinal mais forte para planejar a migração, porque você já está pagando o custo de vendor lock-in sem o benefício de portabilidade que a Gateway API oferece.
• Cluster compartilhado por múltiplos times: avalie a separação de papéis da Gateway API como ganho organizacional, independente de features de roteamento.

Antes de migrar qualquer workload real, confirme no controller que você usa hoje se o suporte a Gateway API já está em versão estável — essa informação não estava disponível nas fontes consultadas para este post e precisa ser verificada na documentação do seu controller específico.