O Que é Gateway API e Por Que Ela é o Futuro
A Gateway API é uma evolução significativa da forma como gerenciamos tráfego de entrada em clusters Kubernetes. Enquanto o Ingress tradicional oferece uma solução básica para roteamento HTTP(S), a Gateway API foi projetada pelo SIG (Special Interest Group) Network do Kubernetes para fornecer uma abstração mais poderosa, flexível e expressiva. Em essência, ela separa as responsabilidades entre operadores de infraestrutura (que gerenciam gateways) e desenvolvedores de aplicações (que definem rotas), criando uma hierarquia clara de responsabilidades.
A Gateway API não substitui imediatamente o Ingress, mas oferece um caminho evolutivo com recursos que o Ingress simplesmente não consegue expressar: suporte nativo a protocolos além de HTTP(S), roteamento baseado em peso entre serviços, reescrita de headers mais sofisticada, e capacidades de TLS mais avançadas. Você pode pensar na Gateway API como um "Ingress 2.0" que aprendeu com os erros e limitações da primeira geração.
Diferenças Fundamentais entre Ingress e Gateway API
O Ingress é monolítico — um único recurso que concentra toda a lógica de roteamento. A Gateway API distribui essa responsabilidade em dois objetos principais: Gateway (a infraestrutura de rede, geralmente gerenciada por operadores) e *Route (as regras de roteamento para aplicações específicas, gerenciadas por desenvolvedores). Isso permite que múltiplas equipes trabalhem sem conflitos e que operadores mantenham a infraestrutura sem interferência das aplicações.
Outra diferença crítica é o suporte a protocolos. Enquanto Ingress focou em HTTP(S), a Gateway API possui suporte nativo para TCP, UDP e até mesmo WebSocket de forma mais elegante. Além disso, a Gateway API permite expressividade de roteamento muito maior, incluindo matching por hostname, path, header, query parameter, e método HTTP com regras de precedência bem definidas.
Componentes Principais da Gateway API
Gateway e GatewayClass
Um GatewayClass é como uma "classe" que descreve o tipo de gateway — similar a um StorageClass para volumes. Ela identifica qual implementação de gateway será usada (por exemplo, nginx, istio, aws-alb). Um operador de infraestrutura cria a GatewayClass uma única vez, configurando-a com parâmetros específicos da implementação.
O Gateway é a instância concreta de um GatewayClass. É o recurso que realmente escuta em portas e IPs, gerenciando certificados TLS e listeners. Diferentemente do Ingress que é tipicamente um por cluster, você pode ter múltiplos Gateways em diferentes namespaces ou endereços IP.
# gateway-class.yaml - Criado pelo operador de infraestrutura
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: nginx-gatewayclass
spec:
controllerName: k8s.io/nginx-gateway-controller
description: "Gateway class para roteamento HTTP(S) com NGINX"
parametersRef:
group: nginx.org
kind: NginxGatewayClassConfig
name: nginx-config
---
# gateway.yaml - Ainda operador, mas pode estar em namespace específico
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: main-gateway
namespace: infrastructure
spec:
gatewayClassName: nginx-gatewayclass
listeners:
- name: http
port: 80
protocol: HTTP
- name: https
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- name: tls-cert
namespace: infrastructure
HTTPRoute, TCPRoute e GRPCRoute
As rotas são onde desenvolvedores de aplicações definem como o tráfego deve ser direcionado. HTTPRoute é a mais comum, permitindo roteamento por hostname, path, header, query parameters e método HTTP. TCPRoute fornece roteamento em nível de camada 4, sem interpretação de HTTP. GRPCRoute é otimizada para gRPC, respeitando a semântica HTTP/2 que gRPC utiliza.
Uma rota é sempre vinculada a um Gateway através de parentRefs. Desenvolvedores definem suas rotas e o controlador do gateway as reconcilia com a configuração do gateway.
# http-route.yaml - Criado por desenvolvedores
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api-route
namespace: default
spec:
parentRefs:
- name: main-gateway
namespace: infrastructure
port: 443
hostnames:
- "api.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /v1
backendRefs:
- name: api-v1-service
port: 8080
weight: 80
- name: api-v2-service
port: 8080
weight: 20
filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
X-Forwarded-By: "gateway"
timeouts:
request: 30s
- matches:
- path:
type: PathPrefix
value: /health
backendRefs:
- name: health-check-service
port: 9000
Implementando Gateway API na Prática
Instalação e Configuração Inicial
Para usar Gateway API, você precisa de um controlador que implemente a especificação. Existem várias opções maduras: nginx-gateway-controller (mantido pela NGINX), Istio com seu Gateway, AWS ALB Controller, e outras. Vamos usar o NGINX como exemplo por ser amplamente acessível.
# Instale o CRD da Gateway API (requerido em clusters < 1.29)
kubectl apply -k github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.0.0
# Instale o controlador NGINX Gateway
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm install nginx-gateway nginx-stable/nginx-gateway \
--namespace nginx-gateway \
--create-namespace \
--set service.type=LoadBalancer
Depois de instalado, o controlador observa recursos Gateway e HTTPRoute no cluster e configura o NGINX automaticamente. Esse é um grande diferencial — a declaratividade completa sem scripts de inicialização manuais.
Exemplo Prático Completo: Aplicação Multi-Tenant
Vamos construir um cenário realista onde você tem três ambientes diferentes (staging, canary, production) usando um único Gateway com múltiplas rotas.
---
# Namespace para infraestrutura
apiVersion: v1
kind: Namespace
metadata:
name: infrastructure
---
# GatewayClass
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: nginx
spec:
controllerName: k8s.io/nginx-gateway-controller
---
# Gateway principal
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: production-gateway
namespace: infrastructure
spec:
gatewayClassName: nginx
listeners:
- name: http
port: 80
protocol: HTTP
- name: https
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- name: tls-wildcard
---
# Secret com certificado TLS
apiVersion: v1
kind: Secret
metadata:
name: tls-wildcard
namespace: infrastructure
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTi... # Base64 do seu certificado
tls.key: LS0tLS1CRUdJTi... # Base64 da sua chave privada
---
# HTTPRoute para staging
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: staging-route
namespace: staging
spec:
parentRefs:
- name: production-gateway
namespace: infrastructure
hostnames:
- "staging.example.com"
rules:
- matches:
- path:
type: Exact
value: /
backendRefs:
- name: staging-app-service
port: 3000
---
# HTTPRoute para canary (com canary deployment)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: canary-route
namespace: production
spec:
parentRefs:
- name: production-gateway
namespace: infrastructure
hostnames:
- "api.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: app-service-stable
port: 8080
weight: 90
- name: app-service-canary
port: 8080
weight: 10
filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
X-Served-By: "gateway-api"
---
# Serviços exemplo
apiVersion: v1
kind: Service
metadata:
name: staging-app-service
namespace: staging
spec:
selector:
app: staging-app
ports:
- port: 3000
targetPort: 3000
---
apiVersion: v1
kind: Service
metadata:
name: app-service-stable
namespace: production
spec:
selector:
app: myapp
version: stable
ports:
- port: 8080
targetPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: app-service-canary
namespace: production
spec:
selector:
app: myapp
version: canary
ports:
- port: 8080
targetPort: 8080
Monitoramento e Debugging
Para verificar se suas rotas foram aplicadas corretamente, use:
# Listar todos os gateways
kubectl get gateways -A
# Detalhes de um gateway específico
kubectl describe gateway main-gateway -n infrastructure
# Listar rotas HTTP
kubectl get httproutes -A
# Verificar o status de uma rota
kubectl get httproute api-route -n default -o yaml
# Logs do controlador
kubectl logs -n nginx-gateway -l app.kubernetes.io/name=nginx-gateway --tail=100
# Testar conectividade (após expor o gateway)
curl -H "Host: api.example.com" http://localhost/api/test
Vantagens Reais e Casos de Uso
Quando Usar Gateway API ao Invés de Ingress
Gateway API brilha quando você precisa de separação clara de responsabilidades. Em organizações com múltiplas equipes, o fato de operadores gerenciarem Gateways e desenvolvedores gerenciarem Routes elimina conflitos e facilita auditoria. Se seu cluster executa diferentes tipos de tráfego (HTTP, gRPC, TCP), a Gateway API oferece abstração unificada enquanto Ingress força workarounds.
Canary deployments, blue-green deployments e teste A/B ficam muito mais simples com o suporte nativo a roteamento com peso. Você não precisa mais de ferramentas externas como Istio para isso — está no padrão Kubernetes. Para empresas com requisitos estritos de segurança e conformidade, a possibilidade de definir RBAC fino por recurso é invaluável.
Limitações Atuais
Apesar do potencial, a Gateway API ainda é um padrão em evolução. Nem todas as implementações suportam todos os recursos, e algumas features experimentais podem mudar entre versões. Adoption no ecossistema ainda está crescendo — nem todos os provedores (como AWS ALB Controller) possuem suporte completo. Em clusters muito antigos (< 1.19), você terá dificuldade em encontrar suporte.
A documentação de algumas implementações ainda é escassa comparada ao Ingress. Para migrações em larga escala, você terá que planejar cuidadosamente a coexistência entre Ingress e Gateway API durante a transição, pois ainda não há ferramenta padrão de migração automática.
Conclusão
A Gateway API representa uma evolução genuína na forma como gerenciamos ingress em Kubernetes. Aprendemos que ela não é apenas um "Ingress melhorado", mas sim uma arquitetura fundamentalmente diferente que separa infraestrutura (Gateways) de aplicação (Routes), permitindo múltiplas equipes trabalharem de forma independente. Sua expressividade — suporte a múltiplos protocolos, roteamento com peso, filtros sofisticados — torna problemas complexos como canary deployments triviais de resolver. Por fim, embora ainda em adoção, a Gateway API é o futuro inequívoco do roteamento em Kubernetes, e investir tempo em compreendê-la agora coloca você à frente da curva de evolução da plataforma.