Antes de Migrar: 5 Comportamentos do Ingress-NGINX que Podem Surpreender sua Operação

Como anunciado em novembro de 2025, o projeto Kubernetes descontinuará oficialmente o Ingress-NGINX em março de 2026. Apesar de ser uma das soluções mais utilizadas no ecossistema, o Ingress-NGINX é repleto de comportamentos padrão e efeitos colaterais que, se ignorados, podem comprometer a estabilidade do seu ambiente durante a transição.

Este artigo analisa esses comportamentos sob uma ótica estratégica para que times de engenharia no Brasil possam planejar uma migração segura para a Gateway API, decidindo conscientemente quais lógicas preservar. O padrão de risco é constante: uma tradução de configuração que parece correta pode causar outages se não considerar as particularidades do Ingress-NGINX.

É importante distinguir: estamos falando do Ingress-NGINX, mantido pela comunidade Kubernetes, e não do NGINX Ingress comercial da F5. Embora ambos usem o NGINX no dataplane, suas implementações de controle são distintas.

1. Matches de Regex são baseados em prefixo e Case Insensitive

Imagine que você precise rotear requisições onde o caminho possui exatamente três letras maiúsculas para o serviço httpbin. Você aplicaria a annotation nginx.ingress.kubernetes.io/use-regex: "true" com o padrão /[A-Z]{3}.

CopiarapiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: regex-match-ingress
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: regex-match.example.com
    http:
      paths:
      - path: "/[A-Z]{3}"
        pathType: ImplementationSpecific
        backend:
          service:
            name: httpbin
            port:
              number: 8000

No Ingress-NGINX, como os matches de regex são por padrão insensíveis a maiúsculas/minúsculas e baseados em prefixo, ele roteará qualquer requisição que comece com três letras (ex: /uuid) para o backend.

Na Gateway API, implementações baseadas em Envoy (como Istio, Envoy Gateway e Kgateway) realizam matches de RegularExpression de forma estrita e sensível ao caso. Se o seu time criar uma HTTPRoute esperando o comportamento antigo sem ajustar o regex para (?i)/[a-zA-Z]{3}.*, requisições legítimas que antes funcionavam retornarão 404 Not Found, interrompendo o serviço.

2. A annotation 'use-regex' afeta todos os caminhos do host

Um comportamento crítico e pouco intuitivo: se você ativar use-regex: "true" em um objeto Ingress, essa configuração vaza para todos os outros Ingresses que compartilham o mesmo hostname no Ingress-NGINX.

Isso significa que um path definido como Exact em outro arquivo pode acabar sendo interpretado como uma expressão regular prefixada, aceitando tráfego que não deveria.

Ao migrar para a Gateway API, essa "contaminação" de configuração não existe. Cada regra na HTTPRoute é isolada. Se o tráfego da sua aplicação dependia involuntariamente dessa interpretação frouxa do Ingress-NGINX, a migração para um modelo mais rigoroso exigirá uma revisão minuciosa dos tipos de match (Exact, Prefix ou RegularExpression).

3. Rewrite Target implica em Regex automático

O uso da annotation nginx.ingress.kubernetes.io/rewrite-target ativa silenciosamente o modo regex para todos os caminhos daquele host, mesmo que você não tenha declarado explicitamente a flag de regex.

Copiarannotations:
  nginx.ingress.kubernetes.io/rewrite-target: "/uuid"

Na Gateway API, o filtro URLRewrite é explícito e não altera a semântica dos matches de path. Para empresas brasileiras com pipelines complexos de CI/CD, este é um ponto de atenção em FinOps e Governança: a mudança de comportamento pode levar a erros de roteamento que aumentam a latência ou o consumo de recursos por tentativas de retentativa (retries) desnecessárias.

4. Redirecionamento automático de Trailing Slash

Se você define um path como /meu-caminho/, o Ingress-NGINX redireciona automaticamente requisições enviadas para /meu-caminho (sem a barra) via 301 Moved Permanently.

Implementações em conformidade com a Gateway API não configuram redirecionamentos silenciosos. Se seus clientes ou APIs legadas dependem dessa barra final automática, a migração resultará em erro 404. Você deve configurar explicitamente um filtro requestRedirect na sua HTTPRoute para manter a compatibilidade:

Copiarfilters:
  requestRedirect:
    statusCode: 301
    path:
      type: ReplaceFullPath
      replaceFullPath: /meu-caminho/

5. Normalização de URLs

O Ingress-NGINX realiza a normalização de URLs (conforme a RFC 3986) antes de processar as regras. Isso inclui remover segmentos como . e resolver .., além de colapsar barras consecutivas (//).

Embora a maioria das implementações de Gateway API (como Istio e Envoy) também habilite a normalização por padrão, os detalhes da implementação podem variar. É fundamental validar se o seu backend depende de uma normalização específica para evitar falhas de segurança ou de roteamento.

Conclusão

A descontinuação do Ingress-NGINX é um marco para a infraestrutura Kubernetes. Embora a transição para a Gateway API traga maior expressividade e padronização, os efeitos colaterais aqui listados mostram que a migração não é apenas uma troca de sintaxe YAML, mas uma mudança de comportamento do plano de dados.

A recomendação para gestores de TI e engenheiros de DevOps é iniciar testes de carga e interoperabilidade utilizando ferramentas como o Ingress2Gateway, que já suporta a tradução de várias dessas annotations para o novo padrão.

---

Artigo originalmente publicado em Kubernetes Blog.