Kubernetes Gateway API no Node.js

A Kubernetes Gateway API no Node.js oferece recursos mais expressivos para publicar APIs, definir rotas HTTP, controlar TLS e delegar configurações entre equipes. Ela evolui conceitos tradicionalmente associados ao Ingress e separa responsabilidades entre infraestrutura, plataforma e aplicação.

Gateway API não é um proxy por si só. É um conjunto de APIs Kubernetes implementado por controllers compatíveis. Antes de criar objetos, confirme qual implementação está instalada, quais recursos são suportados e quais versões CRD estão disponíveis no cluster.

Neste guia, você aprenderá a configurar Gateway, HTTPRoute, listeners, TLS, filtros, canary, timeouts, políticas de acesso e observabilidade para uma aplicação Node.js.

O que é Gateway API?

A documentação oficial da Kubernetes Gateway API apresenta uma família de recursos orientada a papéis. Os objetos principais são:

• GatewayClass: identifica a implementação do controller.
• Gateway: define pontos de entrada, listeners e TLS.
• HTTPRoute: associa hosts, caminhos, filtros e backends.
• ReferenceGrant: autoriza referências entre namespaces.
• GRPCRoute: roteia serviços gRPC quando suportado.

Separação de responsabilidades

Uma equipe de infraestrutura administra GatewayClass. A equipe de plataforma cria Gateways compartilhados. Equipes de aplicação publicam HTTPRoutes autorizadas. Essa separação evita que cada serviço configure diretamente load balancers e certificados globais.

Pré-requisitos

Verifique CRDs e controllers:

kubectl get gatewayclasses
kubectl api-resources | grep gateway.networking.k8s.io

A lista de implementações da Gateway API mostra controllers e níveis de conformidade. Recursos experimentais ou estendidos variam entre fornecedores.

Aplicação Node.js

Considere uma API publicada por um Service:

apiVersion: v1
kind: Service
metadata:
  name: orders-api
  namespace: orders
spec:
  selector:
    app: orders-api
  ports:
    - name: http
      port: 80
      targetPort: 3000

O Deployment deve ter readiness correta para o Service enviar tráfego somente a Pods prontos. Veja Kubernetes Deployment no Node.js e Probes Kubernetes em Node.js.

Criando um Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: platform
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-example-com
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: public

O listener aceita rotas apenas de namespaces com uma label específica. Isso reduz publicação acidental.

Namespace autorizado

apiVersion: v1
kind: Namespace
metadata:
  name: orders
  labels:
    gateway-access: public

Labels de autorização devem ser controladas por administradores ou políticas de admissão, não por qualquer desenvolvedor.

HTTPRoute básica

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: orders-api
  namespace: orders
spec:
  parentRefs:
    - name: public-gateway
      namespace: platform
      sectionName: https
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /orders
      backendRefs:
        - name: orders-api
          port: 80

O sectionName seleciona o listener. O hostname e o listener precisam ser compatíveis.

Status da rota

kubectl get httproute orders-api -n orders -o yaml

Observe condições como Accepted, ResolvedRefs e mensagens do controller. Um apply bem-sucedido não significa que o tráfego foi configurado.

Correspondência por método

matches:
  - method: POST
    path:
      type: Exact
      value: /orders

Não use roteamento como substituto para autorização. A API Node.js continua validando autenticação, tenant e permissões.

Headers

matches:
  - headers:
      - name: X-API-Version
        value: v2
    path:
      type: PathPrefix
      value: /orders

Headers podem direcionar versões ou testes, mas clientes não devem controlar privilégios por um cabeçalho não autenticado.

Redirecionamento HTTP para HTTPS

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect-https
  namespace: platform
spec:
  parentRefs:
    - name: public-gateway
      sectionName: http
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

O Gateway precisa ter um listener HTTP correspondente.

URL rewrite

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /

Confirme suporte do controller. Rewrites podem alterar a semântica esperada pela aplicação e precisam de testes com encoding e query strings.

RequestHeaderModifier

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      set:
        - name: X-Forwarded-Proto
          value: https
      remove:
        - X-Internal-Debug

Não confie cegamente em headers encaminhados. Configure proxies confiáveis no framework Node.js e remova valores enviados diretamente pelo cliente.

Canary por peso

backendRefs:
  - name: orders-api-v1
    port: 80
    weight: 90
  - name: orders-api-v2
    port: 80
    weight: 10

Pesos distribuem tráfego aproximadamente. Monitore erros, latência e métricas por versão. Veja Canary Deploy no Node.js.

Blue-green

Uma HTTPRoute pode apontar inicialmente para o Service blue e depois ser alterada para green. A mudança não reverte banco ou tarefas assíncronas. Consulte Blue-Green Deploy no Node.js.

Backend em outro namespace

Referências entre namespaces exigem autorização no namespace de destino:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-platform-route
  namespace: shared-services
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: orders
  to:
    - group: ""
      kind: Service
      name: payments-api

Use referências cruzadas apenas quando a arquitetura realmente exigir. Elas ampliam acoplamento e superfície de acesso.

TLS

O Secret do certificado deve ficar no mesmo namespace do Gateway, salvo extensão ou autorização compatível. Proteja chaves privadas, automatize renovação e monitore expiração.

Cert-manager

Controllers podem integrar com cert-manager por annotations ou políticas específicas. Confirme o padrão da implementação. Não dependa de uma annotation proprietária sem documentar portabilidade.

Timeouts

Gateway API possui recursos de timeout conforme versão e suporte do controller. Defina limites coerentes com a API:

• timeout do cliente;
• timeout do gateway;
• timeout do servidor Node.js;
• timeout de dependências;
• graceful shutdown.

Um gateway com timeout de 30 segundos não corrige uma consulta que deveria terminar em dois.

Retries

Retries na camada de gateway podem duplicar operações. Só habilite para métodos e falhas seguras, considerando idempotência. Consulte Idempotência em APIs Node.js.

Rate limiting

Rate limit costuma ser recurso estendido ou policy do controller, não parte uniforme do core. Aplique limites por identidade, rota e tenant. Um limite por IP pode bloquear NATs compartilhados ou ser contornado por redes distribuídas.

Autenticação externa

Algumas implementações oferecem filtros de autenticação. Mesmo assim, a aplicação deve validar claims, audience e autorização de negócio. O gateway não conhece ownership de recursos.

gRPC

Para serviços gRPC, use GRPCRoute quando a implementação suportar. Veja gRPC com Node.js. Configure HTTP/2, TLS, deadlines e códigos de status corretamente.

WebSockets e SSE

Verifique suporte e timeouts do controller. Conexões longas afetam draining, autoscaling e atualização de Pods. Para SSE, desative buffering quando necessário.

Gateway API e Ingress

Ingress é amplamente suportado e simples. Gateway API oferece papéis, listeners, rotas tipadas e extensibilidade mais clara. Migre gradualmente, compare recursos do controller e mantenha testes de tráfego.

Políticas de segurança

• Restrinja namespaces que podem anexar rotas.
• Use hostnames explícitos.
• Controle ReferenceGrants.
• Proteja Secrets TLS.
• Valide imagens e ServiceAccounts.
• Não exponha dashboards administrativos.
• Aplique NetworkPolicy entre gateway e backends.

NetworkPolicy

Permita tráfego para a API somente a partir dos namespaces ou Pods do gateway. O Service por si só não limita origem.

Observabilidade

Monitore:

• requisições por host e rota;
• status HTTP;
• latência no gateway e backend;
• retries e resets;
• erros TLS;
• backends sem endpoints;
• condições de Gateway e HTTPRoute;
• tráfego por versão em canary.

Propague trace context e request IDs sem aceitar valores malformados ilimitados.

Testes

Depois do apply:

curl --resolve api.example.com:443:GATEWAY_IP \
  https://api.example.com/orders

Teste host incorreto, caminhos, redirects, TLS, headers, backends indisponíveis e rollback.

GitOps

Mantenha Gateway e HTTPRoutes em repositórios compatíveis com a divisão de equipes. A plataforma pode revisar mudanças no Gateway, enquanto aplicações controlam apenas rotas autorizadas.

Erros comuns

• Controller ausente: objetos existem, mas nada configura o tráfego.
• Route não aceita: listener ou namespace não autoriza o vínculo.
• Hostname incompatível: a rota não se conecta ao listener.
• Confiar em header do cliente: identidade pode ser falsificada.
• Retry em POST: operações são duplicadas.
• ReferenceGrant amplo: namespaces acessam backends indevidos.
• Canary sem métricas: falhas alcançam usuários sem detecção.
• TLS sem renovação: certificado expira.

Conclusão

A Kubernetes Gateway API no Node.js fornece recursos tipados para publicar APIs, configurar TLS, rotas, filtros e distribuição de tráfego. GatewayClass, Gateway e HTTPRoute separam responsabilidades entre infraestrutura e aplicações.

Confirme suporte da implementação, restrinja namespaces e valide o status das rotas. Combine Gateway API com probes, NetworkPolicy, autorização na aplicação e observabilidade. Assim, a entrada do cluster evolui sem transformar o gateway em uma camada de confiança irrestrita.