Após o encerramento do ingress-nginx: validar uma migração paralela para Gateway API

O que é

Situação em 25 de outubro de 2026: o aviso de encerramento do Ingress NGINX da comunidade Kubernetes estabeleceu março de 2026 como o fim da manutenção feita conforme a capacidade disponível, sem novos lançamentos, correções de bugs ou atualizações de segurança depois disso. As implantações existentes e os artefatos de instalação continuam utilizáveis. Antes de planejar uma mudança, conferir novamente o aviso de encerramento e a documentação de suporte e conformidade do controlador escolhido para substituição. Isso diz respeito ao projeto comunitário ingress-nginx; identificar o controlador real em vez de classificar da mesma forma tudo que leva o nome NGINX. Aviso de encerramento.

Por que importa

Uma imagem disponível ou um endpoint em funcionamento não demonstra manutenção contínua. Gateway API muda o modelo de configuração: um Gateway descreve os pontos de entrada, enquanto HTTPRoute descreve o roteamento da aplicação. Anotações específicas de controladores precisam de um mapeamento explícito. O guia geral de migração explica a conversão, mas declara expressamente que não fornece um procedimento completo de migração em operação. Modelo de migração.

O procedimento em etapas a seguir é um plano operacional proposto. Seus critérios de aceitação devem abranger os requisitos existentes de roteamento e segurança da aplicação.

Como aplicar

• Inventariar os controladores em todos os clusters cujo acesso seja autorizado. O aviso de encerramento sugere kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx. Revisar também os deployments e as imagens dos controladores: uma consulta por rótulo, por si só, não exclui a presença de instalações renomeadas ou personalizadas. Registrar os recursos Ingress, as classes, as anotações, as referências TLS e a configuração dos controladores.

• Escolher uma implementação de Gateway API que receba manutenção e cuja conformidade e suporte a extensões cubram as funcionalidades necessárias. Atribuir responsáveis pelos pontos de entrada e pelas rotas. O guia oficial de introdução admite executar o novo controlador ao lado do ingress-nginx com um IP externo diferente; portanto, preparar um endpoint separado de validação antes de alterar o tráfego público. Orientações para migração paralela.

• Com uma instalação revisada do ingress2gateway, gerar uma versão preliminar a partir de manifestos exportados. O anúncio oficial da versão 1.0 documenta esta forma:

  ingress2gateway print --input-file ingress.yaml --providers=ingress-nginx > gateway-draft.yaml
  

  Revisar os recursos gerados e todos os avisos antes de aplicar qualquer coisa. Selecionar a GatewayClass efetivamente usada na substituição e verificar nomes, namespaces e referências a backends. Orientações de conversão.

• Resolver explicitamente cada funcionalidade sem suporte. Esse anúncio identifica trechos de configuração não convertidos, conversões aproximadas de tempos limite, limites de tamanho do corpo sem equivalente padrão em seu exemplo e diferenças de normalização de URL. Conferir novamente esses mapeamentos em relação à API atual e à implementação selecionada; não transformar uma limitação histórica do conversor em uma afirmação permanente sobre a especificação.

• Validar o endpoint separado com o nome de host e a identidade TLS pretendidos. Testar redirecionamentos, requisitos de autenticação, precedência de rotas, uploads, requisições de longa duração e o comportamento de rejeição esperado. Fazer isso como testes normais da aplicação, sem payloads de ataque. Comparar os resultados com os requisitos documentados, sem se limitar a verificar se ambos os endpoints retornam uma resposta bem-sucedida.

• Transferir o tráfego pelo processo controlado de mudança de DNS ou balanceador de carga do site. Observar erros da aplicação e logs de acesso, manter um caminho de reversão por tempo limitado e remover o controlador antigo e os recursos sem uso após a conclusão satisfatória do período de observação.

Armadilhas

Não presumir que o YAML gerado preserve controles de acesso nem que extensões personalizadas sejam portáveis entre controladores. A implantação paralela também exige responsabilidades claras por DNS e automação de certificados. Evitar deixar o controlador descontinuado exposto indefinidamente como uma reserva não documentada. O sucesso da conversão, a prontidão do controlador e o comportamento correto da aplicação são verificações separadas.