Migração do ingress-nginx: Transição para o Gateway API com Traefik
Este artigo detalha o processo de migração de ingress-nginx para o Traefik, explorando os benefícios e desafios, com foco na preparação para a adoção do Gateway API no Kubernetes.
MundiX News·09 de junho de 2026·8 min de leitura·👁 7 views
Na jornada contínua de otimização de infraestruturas Kubernetes, a escolha do ingress controller adequado é crucial. Após uma análise de opções, a equipe optou por testar o Traefik, visando uma transição suave do ingress-nginx e preparando o terreno para a adoção futura do Gateway API. Essa migração busca minimizar interrupções e a necessidade de reescrita massiva de serviços existentes.
As principais razões para a escolha do Traefik incluem sua maturidade, documentação robusta, capacidade de descoberta automática de novos serviços, alta performance e complexidade de configuração moderada. Um fator decisivo foi o suporte ao Gateway API e, crucialmente, a existência de um provedor específico para Kubernetes Ingress NGINX. Este provedor, conforme documentado, permite a migração do ingress-nginx com alterações mínimas nos objetos Ingress. Ele monitora os objetos Ingress no Kubernetes que possuem ingressClassName: nginx e os traduz para a configuração do Traefik. Muitas configurações que antes eram definidas via anotações nos objetos Ingress, agora são suportadas pelo provedor Kubernetes Ingress NGINX do Traefik, facilitando a migração.
No entanto, a migração através do provedor Kubernetes Ingress NGINX do Traefik apresenta desafios, especialmente para configurações de ingress mais complexas que dependem de anotações específicas do ingress-nginx. Atualmente, o provedor suporta apenas um subconjunto dessas anotações. Anotações frequentemente utilizadas, como nginx.ingress.kubernetes.io/rewrite-target, nginx.ingress.kubernetes.io/upstream-vhost, nginx.ingress.kubernetes.io/configuration-snippet, entre outras, podem não ser totalmente suportadas. Embora a lista de anotações suportadas esteja em constante expansão, com atualizações recentes adicionando suporte básico para rewrite-target, a estabilidade dessas funcionalidades pode levar tempo para chegar a um release oficial. Em casos onde a funcionalidade desejada ainda não é suportada, a adaptação manual das configurações se torna necessária. Para contornar a falta de suporte a anotações como rewrite-target, foi implementado um middleware customizado no Traefik para realizar a manipulação de caminhos de requisição, como a remoção de prefixos. Esse middleware é então referenciado nos objetos Ingress do Traefik, permitindo a migração gradual e a possibilidade de reverter para o ingress-nginx simplesmente alterando o ingressClassName.
A transição para o Gateway API é vista como o próximo passo lógico, especialmente quando a reescrita de configurações de Ingress já é necessária. O Traefik pode operar simultaneamente com ambos os modelos, Ingress API e Gateway API. Um exemplo de configuração utilizando o Gateway API demonstra como o middleware app-strip-prefixes pode ser aplicado a um HTTPRoute, que por sua vez é associado a um Gateway. Essa abordagem híbrida permite que diferentes rotas em um mesmo host coexistam, algumas utilizando objetos Ingress tradicionais e outras o novo padrão Gateway API. A flexibilidade oferecida pelos middlewares do Traefik permite implementar funcionalidades que ainda não são nativamente suportadas pelo Gateway API ou que eram complexas de configurar via anotações no Ingress API.
O plano de migração delineado envolve a instalação paralela do Traefik ao lado do ingress-nginx, mantendo os objetos Ingress existentes que utilizam anotações suportadas e migrando configurações complexas diretamente para o Gateway API. O princípio fundamental é uma transição gradual com capacidade de rollback. A estratégia inclui a inventariação dos recursos de ingress, a instalação do novo controller, testes em serviços piloto cobrindo diversos cenários (Ingress API, Gateway API, TLS, roteamento), a migração de serviços com configurações simples para o Traefik e, posteriormente, a migração de serviços com configurações complexas para o Gateway API. A fase atual de testes e migração de serviços iniciais está em andamento, com os maiores esforços concentrados nos testes de cenários e na reescrita de configurações complexas. A conclusão é que, para configurações simples, a migração para Traefik pode ser quase imperceptível. Para infraestruturas que utilizam intensamente mecanismos avançados, a migração direta para o Gateway API é mais eficiente do que reescrever configurações duas vezes. A adoção do Gateway API é vista como o futuro do ecossistema Kubernetes, exigindo um planejamento cuidadoso, auditoria de configurações, avaliação de riscos e alocação de recursos adequados.
Atualização: Com o lançamento da versão v3.7.0 do Traefik e do chart Helm v4.0.0, o suporte a um número significativamente maior de anotações do ingress-nginx, incluindo rewrite-target, foi adicionado. Testes em múltiplos clusters confirmaram que a migração agora requer pouquíssimas alterações nos objetos Ingress.
Na jornada contínua de otimização de infraestruturas Kubernetes, a escolha do ingress controller adequado é crucial. Após uma análise de opções, a equipe optou por testar o Traefik, visando uma transição suave do ingress-nginx e preparando o terreno para a adoção futura do Gateway API. Essa migração busca minimizar interrupções e a necessidade de reescrita massiva de serviços existentes.
As principais razões para a escolha do Traefik incluem sua maturidade, documentação robusta, capacidade de descoberta automática de novos serviços, alta performance e complexidade de configuração moderada. Um fator decisivo foi o suporte ao Gateway API e, crucialmente, a existência de um provedor específico para Kubernetes Ingress NGINX. Este provedor, conforme documentado, permite a migração do ingress-nginx com alterações mínimas nos objetos Ingress. Ele monitora os objetos Ingress no Kubernetes que possuem ingressClassName: nginx e os traduz para a configuração do Traefik. Muitas configurações que antes eram definidas via anotações nos objetos Ingress, agora são suportadas pelo provedor Kubernetes Ingress NGINX do Traefik, facilitando a migração.
No entanto, a migração através do provedor Kubernetes Ingress NGINX do Traefik apresenta desafios, especialmente para configurações de ingress mais complexas que dependem de anotações específicas do ingress-nginx. Atualmente, o provedor suporta apenas um subconjunto dessas anotações. Anotações frequentemente utilizadas, como nginx.ingress.kubernetes.io/rewrite-target, nginx.ingress.kubernetes.io/upstream-vhost, nginx.ingress.kubernetes.io/configuration-snippet, entre outras, podem não ser totalmente suportadas. Embora a lista de anotações suportadas esteja em constante expansão, com atualizações recentes adicionando suporte básico para rewrite-target, a estabilidade dessas funcionalidades pode levar tempo para chegar a um release oficial. Em casos onde a funcionalidade desejada ainda não é suportada, a adaptação manual das configurações se torna necessária. Para contornar a falta de suporte a anotações como rewrite-target, foi implementado um middleware customizado no Traefik para realizar a manipulação de caminhos de requisição, como a remoção de prefixos. Esse middleware é então referenciado nos objetos Ingress do Traefik, permitindo a migração gradual e a possibilidade de reverter para o ingress-nginx simplesmente alterando o ingressClassName.
A transição para o Gateway API é vista como o próximo passo lógico, especialmente quando a reescrita de configurações de Ingress já é necessária. O Traefik pode operar simultaneamente com ambos os modelos, Ingress API e Gateway API. Um exemplo de configuração utilizando o Gateway API demonstra como o middleware app-strip-prefixes pode ser aplicado a um HTTPRoute, que por sua vez é associado a um Gateway. Essa abordagem híbrida permite que diferentes rotas em um mesmo host coexistam, algumas utilizando objetos Ingress tradicionais e outras o novo padrão Gateway API. A flexibilidade oferecida pelos middlewares do Traefik permite implementar funcionalidades que ainda não são nativamente suportadas pelo Gateway API ou que eram complexas de configurar via anotações no Ingress API.
O plano de migração delineado envolve a instalação paralela do Traefik ao lado do ingress-nginx, mantendo os objetos Ingress existentes que utilizam anotações suportadas e migrando configurações complexas diretamente para o Gateway API. O princípio fundamental é uma transição gradual com capacidade de rollback. A estratégia inclui a inventariação dos recursos de ingress, a instalação do novo controller, testes em serviços piloto cobrindo diversos cenários (Ingress API, Gateway API, TLS, roteamento), a migração de serviços com configurações simples para o Traefik e, posteriormente, a migração de serviços com configurações complexas para o Gateway API. A fase atual de testes e migração de serviços iniciais está em andamento, com os maiores esforços concentrados nos testes de cenários e na reescrita de configurações complexas. A conclusão é que, para configurações simples, a migração para Traefik pode ser quase imperceptível. Para infraestruturas que utilizam intensamente mecanismos avançados, a migração direta para o Gateway API é mais eficiente do que reescrever configurações duas vezes. A adoção do Gateway API é vista como o futuro do ecossistema Kubernetes, exigindo um planejamento cuidadoso, auditoria de configurações, avaliação de riscos e alocação de recursos adequados.
Atualização: Com o lançamento da versão v3.7.0 do Traefik e do chart Helm v4.0.0, o suporte a um número significativamente maior de anotações do ingress-nginx, incluindo rewrite-target, foi adicionado. Testes em múltiplos clusters confirmaram que a migração agora requer pouquíssimas alterações nos objetos Ingress.
