O NGINX do app routing do AKS acabou: como migrar para o Gateway API
O NGINX gerenciado do app routing do AKS só recebe patch crítico até novembro de 2026. O substituto é o Gateway API com a classe approuting-istio. O que muda, como habilitar, o que ele não faz e um passo a passo de migração sem downtime.
Roda isso no seu cluster:
kubectl get ingress -A
Se a coluna CLASS voltar com webapprouting.kubernetes.azure.com ou nginx, este post é para você. Essa é a classe do NGINX gerenciado pelo add-on de application routing do AKS. E esse NGINX recebe patch crítico de segurança só até novembro de 2026. Este mês.
Eu sei como isso acontece. O add-on resolve o ingress em um comando, o Ingress funciona, ninguém mexe mais. Já deixei controller de ingress rodando anos sem olhar a versão, porque "está funcionando". O problema é que "está funcionando" e "está recebendo patch" são coisas diferentes, e a partir de dezembro só a primeira continua verdadeira.
Então vamos lá: o que acaba e quando, o que muda para quem usa a classe do add-on, como ligar o substituto, o que ele não faz e como migrar sem derrubar ninguém.
O que acaba, e quando
A história começa fora da Microsoft. O SIG Network do Kubernetes, junto com o Security Response Committee, anunciou a aposentadoria do projeto Ingress NGINX, o kubernetes/ingress-nginx. A manutenção do projeto terminou em março de 2026.
O NGINX do app routing é baseado nesse projeto. Então a Microsoft ficou com um controller gerenciado em cima de um upstream que ninguém mais mantém. O que ela fez foi segurar a ponte: suporte oficial para patches críticos de segurança dos recursos de NGINX Ingress do app routing até novembro de 2026. Depois disso, a documentação do Gateway API do app routing é direta: o NGINX gerenciado para de receber suporte do Azure, e quem usa precisa migrar para a implementação de Gateway API do app routing, ou para outra implementação suportada.
[IMAGEM: linha do tempo com três marcos: "SIG Network aposenta o Ingress NGINX", "manutenção encerrada: março de 2026", "Microsoft: patches críticos até novembro de 2026"]
Ponto importante: a documentação fala em fim de suporte e de patch, não em desligar o seu controller. O Deployment do NGINX continua lá, o Ingress continua roteando. O que some é alguém corrigindo o que quebrar. E um proxy exposto para a internet sem patch é exatamente o tipo de coisa que você não quer descobrir pelo boletim de CVE.
E tem um motivo menos falado para não tratar isso como burocracia: a própria documentação avisa que o NGINX gerenciado não isola tenants por namespace. Um Ingress num namespace pode adicionar path num host de outro namespace, e o controller lê Secrets de todos eles. Se o seu cluster é compartilhado entre times, isso já era risco antes da aposentadoria.
O que muda para quem usa webapprouting.kubernetes.azure.com
Direto ao ponto: muda a API. Você sai do Ingress e vai para o Gateway API, que o AKS adota como o padrão de longo prazo para ingress e tráfego L7, alinhado ao upstream do Kubernetes.
O guia de migração da Microsoft resume as diferenças assim:
| Aspecto | NGINX do add-on | Gateway API do app routing |
|---|---|---|
| API | networking.k8s.io/v1 Ingress |
gateway.networking.k8s.io/v1 Gateway e HTTPRoute |
| Flag no Azure CLI | --enable-app-routing |
--enable-app-routing-istio (com --enable-gateway-api) |
| Classe | webapprouting.kubernetes.azure.com |
approuting-istio |
| Service do data plane | nginx em app-routing-system |
<nome-do-gateway>-approuting-istio no namespace do Gateway |
| DNS do Azure e TLS do Key Vault | embutido | integração própria do operator de app routing |
A última linha merece atenção. No NGINX, você ligava Key Vault e zona DNS com --attach-kv e --attach-zones, usando a identidade gerenciada do próprio add-on. A documentação deixa claro que essas flags são da experiência legada do NGINX e não valem para o Gateway API. No modelo novo, a autenticação é por Workload Identity: você cria a sua user-assigned managed identity, dá os roles e cria as federated credentials.
E as suas anotações de NGINX não migram sozinhas. Cada nginx.ingress.kubernetes.io/... que você usa precisa de um equivalente em Gateway API, ou de uma decisão consciente de que ele não tem equivalente. Já já chego nessa parte, porque é onde a migração morde.
O substituto: approuting-istio
O nome assusta um pouco, então deixa eu descomplicar. A implementação de Gateway API do app routing sobe um control plane do Istio, o istiod, no namespace aks-istio-system. Só que esse Istio é enxuto: ele só reconcilia recursos de Gateway API da GatewayClass approuting-istio. Sem sidecar, sem os CRDs do Istio (VirtualService, DestinationRule e companhia). Não é service mesh. É um ingress que usa o Envoy do Istio como proxy.
A diferença para o add-on de service mesh Istio fica assim:
| Gateway API do app routing | Add-on de service mesh Istio | |
|---|---|---|
| GatewayClass | approuting-istio |
istio |
| Sidecar e CRDs do Istio | não suportado | suportado |
| Upgrade | sem revisão, in-place para minor e patch | com revisão, canary upgrade para minor |
Essa última linha é a que mais pesa no dia a dia. No app routing, a versão do Istio acompanha a versão do AKS, e o upgrade acontece no lugar: patch sobe junto com as releases do AKS, e minor sobe quando você atualiza o AKS ou quando sai uma versão nova do Istio para a sua versão do cluster. Por exemplo, segundo a documentação, um cluster AKS 1.34 roda no máximo o Istio 1.28 (dado de março de 2026).
O status também importa. A implementação approuting-istio e a instalação gerenciada do Gateway API viraram GA na release 20260428 do AKS, segundo o blog do time do AKS. E a documentação diz que, a partir do AKS 1.36, todo cluster novo de AKS Automatic já nasce com o Gateway API via app routing ligado. Para produção no Automatic, é o modelo de ingress recomendado.
Habilitando no cluster
Antes do comando, três pré-requisitos que dão erro se você pular:
- Azure CLI 2.86.0 ou superior.
az --versionpara conferir,az upgradepara atualizar. - Managed Gateway API. Os CRDs do Gateway API precisam vir da instalação gerenciada do AKS. CRD instalado por você não é suportado com o app routing. Se já existe CRD no cluster, só o canal
standardé aceito; os do canalexperimentalprecisam sair antes. - Sem o add-on de service mesh Istio. Os dois não rodam juntos. Se o cluster tem o add-on Istio, você desliga, e depois apaga os CRDs do Istio e a GatewayClass
istio, porque eles ficam no cluster e impedem o control plane do app routing de subir.
A limpeza da documentação apaga também os recursos do Istio que existirem (VirtualService, DestinationRule e outros), então roda com cuidado:
kubectl delete crd $(kubectl get crd -o name | grep -E 'istio\.io')
kubectl delete gatewayclass istio
Com isso resolvido, num cluster existente é um comando:
az aks update \
--resource-group rg-aks \
--name aks-prod \
--enable-gateway-api \
--enable-app-routing-istio
O --enable-gateway-api instala os CRDs gerenciados; o --enable-app-routing-istio liga a implementação. Num cluster novo, as mesmas duas flags vão no az aks create. E o NGINX continua servindo tráfego enquanto isso, porque os dois data planes convivem no mesmo cluster.
Para conferir que subiu:
kubectl -n aks-istio-system rollout status deploy/istiod --timeout=5m
kubectl get gatewayclass approuting-istio
A GatewayClass approuting-istio precisa aparecer com True na coluna ACCEPTED.
Do Ingress para Gateway e HTTPRoute
Vamos pegar um Ingress típico do add-on. Host, path e um Service atrás:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: httpbin
namespace: demo
spec:
ingressClassName: webapprouting.kubernetes.azure.com
rules:
- host: httpbin.contoso.com
http:
paths:
- path: /get
pathType: Prefix
backend:
service:
name: httpbin
port:
number: 8000
O equivalente em Gateway API são dois recursos:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: httpbin-gateway
namespace: demo
spec:
gatewayClassName: approuting-istio
listeners:
- name: http
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: httpbin
namespace: demo
spec:
parentRefs:
- name: httpbin-gateway
hostnames: ["httpbin.contoso.com"]
rules:
- matches:
- path:
type: PathPrefix
value: /get
backendRefs:
- name: httpbin
port: 8000
Repara na separação. O Gateway diz onde o tráfego entra: classe, porta, protocolo e quem pode se pendurar nele (allowedRoutes, aqui só rotas do mesmo namespace). O HTTPRoute diz para onde o tráfego vai: o parentRefs aponta para o Gateway, o backendRefs aponta para o Service. No Ingress, isso tudo estava num objeto só. No Gateway API, o time de plataforma pode ser dono do Gateway e cada time de aplicação dono das suas rotas.
[IMAGEM: YAML do Ingress riscado de um lado; do outro, Gateway e HTTPRoute com setas: parentRefs até o Gateway, backendRefs até o Service httpbin]
Quando você aplica o Gateway, o app routing cria quatro coisas com o nome httpbin-gateway-approuting-istio: um Deployment com o proxy, um Service do tipo LoadBalancer, um HorizontalPodAutoscaler e um PodDisruptionBudget. O HPA começa com no mínimo duas réplicas e o PDB garante pelo menos uma disponível, justamente para segurar o tráfego durante os upgrades in-place do Istio. Na saída de exemplo da documentação, o HPA vai de 2 a 5 réplicas com alvo de 80% de CPU.
Para pegar o IP e testar:
kubectl wait --for=condition=Programmed -n demo \
gateways.gateway.networking.k8s.io/httpbin-gateway --timeout=5m
GW_IP=$(kubectl get gateway -n demo httpbin-gateway \
-o jsonpath='{.status.addresses[0].value}')
curl -sS -o /dev/null -w '%{http_code}\n' \
--resolve "httpbin.contoso.com:80:${GW_IP}" \
http://httpbin.contoso.com/get
Esse exemplo cria um load balancer externo. Para IP interno, a configuração é por anotação no Gateway, documentada na página do Gateway API do add-on Istio.
E o HTTPS?
Se o seu Ingress terminava TLS com certificado do Key Vault, o caminho recomendado é a integração automática do operator de app routing. Você coloca duas opções no listener e ele cria o SecretProviderClass, sincroniza o certificado como Secret kubernetes.io/tls e preenche o certificateRefs para você:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: httpbin-gateway
namespace: demo
spec:
gatewayClassName: approuting-istio
listeners:
- name: https
hostname: httpbin.contoso.com
port: 443
protocol: HTTPS
tls:
mode: Terminate
options:
kubernetes.azure.com/tls-cert-keyvault-uri: https://kv-prod.vault.azure.net/certificates/httpbin
kubernetes.azure.com/tls-cert-service-account: approuting-sa
allowedRoutes:
namespaces:
from: Same
Use a URI do certificado sem versão, para o operator pegar a rotação sozinho. A ServiceAccount precisa estar no mesmo namespace do Gateway, ligada por Workload Identity a uma managed identity com o role Key Vault Secrets User no vault. O cluster também precisa do add-on de app routing (--enable-app-routing, que roda o operator), de Workload Identity com OIDC issuer e do provider do Key Vault para o Secrets Store CSI Driver. DNS segue a mesma lógica, com ClusterExternalDNS e ExternalDNS publicando registros A no Azure DNS.
O que ele não faz
Aqui está a parte que ninguém coloca no slide de "migre já". A implementação de Gateway API do app routing não configura:
- limite de tamanho de header e de body da requisição;
- scripts Lua;
- rate limiting, nem local nem global.
O motivo é simples: o Gateway API não tem campo padrão para nada disso, e a implementação do app routing não suporta EnvoyFilter, que seria a porta dos fundos. Então se o seu Ingress tem anotação de rate limit ou de tamanho de body, ela não tem para onde ir nesse modelo.
Um detalhe curioso: se você estava no NGINX gerenciado, Lua já era meio caminho fechado. O add-on bloqueia snippet com _by_lua e lua_package, entre outros valores. Quem sente falta de Lua de verdade, na maioria das vezes, vem do ingress-nginx open source instalado na mão.
E a lista continua, com coisas menores mas que pegam:
- não roda junto com o add-on de service mesh Istio;
- não faz gerenciamento de tráfego de egress;
- o access log do Envoy vem ligado por padrão no stdout do proxy, mas formato, escopo e provider não podem ser customizados pela API
Telemetrydo Istio; - customização do Gateway via ConfigMap só passa pelo que está na allow list; os webhooks gerenciados barram o resto;
- sidecar de terceiro (telemetria, segurança) dentro do pod do proxy tem só suporte best-effort.
Na prática, a pergunta para fazer antes de migrar é uma: o que meu Ingress faz além de rotear HTTP e HTTPS por host e path? Se a resposta é "nada", o approuting-istio resolve. Se a resposta inclui rate limit, limite de body ou Lua, você precisa de outra rota.
As alternativas, e o preço de cada uma
A documentação aponta dois caminhos.
Gateway API com o add-on de service mesh Istio
Mesma API (Gateway, HTTPRoute), GatewayClass istio. Você não precisa injetar sidecar nos workloads para usar só como ingress. E aqui o EnvoyFilter é permitido: você aplica um EnvoyFilter com escopo no gateway e configura o que faltava.
Só que tem letra miúda, e ela é importante:
- Problemas causados por
EnvoyFilterficam fora do suporte do Azure. Você ganha a feature e perde o suporte nela. - Upgrade de revisão minor do Istio é canary e manual: você inicia e conclui, mesmo usando o Istio só para ingress.
- Cada substituto de anotação ou snippet do NGINX precisa ser testado contra a sua revisão do Istio. O exemplo da própria documentação: o buffer filter do Envoy, que impõe limite de body, segura o body inteiro em memória antes de encaminhar. Não faz spill para disco. Limite de body alto com muito upload simultâneo vira conta de memória no proxy.
Application Gateway for Containers
O AGC é outra proposta. É um serviço gerenciado de load balancing L7 em que o data plane roda fora do cluster, operado pelo Azure. Dentro do cluster fica o ALB Controller, que lê Ingress, Gateway, HTTPRoute e traduz para o AGC. Ele aceita Ingress API e Gateway API, o que permite migrar aos poucos sem reescrever tudo de uma vez.
A lista de features é longa: WAF, validação de JWT, mTLS, header rewrite, URL rewrite, traffic splitting, retries, gRPC, WebSocket. Mas, olhando a página de visão geral, rate limit e Lua não aparecem na lista. Então não trate o AGC como "o lugar onde o rate limit do NGINX vai morar" sem testar. Duas restrições práticas: o listener do Gateway só aceita as portas 80 e 443, e o AGC é cobrado à parte. Brazil South está na lista de regiões.
Depende do contexto, mas a minha regra seria esta: HTTP e HTTPS simples, approuting-istio. Precisa de WAF e quer o proxy fora do cluster, AGC. Precisa de EnvoyFilter e aceita operar canary upgrade sem suporte no filtro, add-on Istio.
Passo a passo da migração sem downtime
O truque da migração é que não existe troca in-place. O NGINX e o Gateway ganham cada um o seu IP de frontend no Azure Load Balancer. Você roda os dois em paralelo, valida o caminho novo e move os clientes por DNS. O guia da Microsoft tem oito passos; aqui vai a versão com os comandos.
1. Inventário. O add-on pode ter mais de um controller NGINX, cada um com sua classe e seu IP. Liste todos:
kubectl get nginxingresscontrollers \
-o custom-columns=NAME:.metadata.name,CLASS:.spec.ingressClassName
kubectl get ingress -A
Anote os hosts (coluna HOSTS) e o IP de cada controller (coluna ADDRESS). Inclua o que aponta para esse IP de fora do cluster: origin do Front Door, endpoint do Traffic Manager, allow list de firewall de cliente.
2. Habilitar o Gateway API. Os comandos da seção anterior. O NGINX continua atendendo.
3. Baixar o TTL do DNS. Para 60 segundos, em cada host que aponta para o IP do NGINX. E espere o TTL antigo expirar: se era uma hora, espere uma hora. Se pular isso, resolver com cache vai mandar cliente para o NGINX depois da virada.
4. Traduzir cada Ingress. À mão, como no exemplo acima, ou com o ingress2gateway, ferramenta do SIG Network que lê Ingress (incluindo anotações do ingress-nginx) e gera Gateway API. Cuidado: por padrão ele só lê Ingress com classe nginx. Passe --providers=ingress-nginx --ingress-nginx-ingress-class=webapprouting.kubernetes.azure.com e rode uma vez por classe. E trate a saída como ponto de partida, não como verdade.
5. TLS no Gateway. Antes de mexer no DNS, nunca depois.
6. Validar sem mexer no DNS. O curl --resolve força o host para o IP novo:
curl -sS -o /dev/null -w '%{http_code}\n' \
--resolve "httpbin.contoso.com:80:${GW_IP}" \
http://httpbin.contoso.com/get
curl -sS -o /dev/null -w '%{http_code}\n' \
--resolve "httpbin.contoso.com:80:${INGRESS_NGINX_IP}" \
http://httpbin.contoso.com/get
Os dois têm que devolver 200 por vários minutos em loop. E não fique no happy path: teste todo host e todo path, HTTPS com o certificado de produção (sem --insecure), POST com body, autenticação, streaming, WebSocket e gRPC se você usa. Tudo que quebrar aqui ainda não é incidente.
7. Virar. Atualize o registro A para o IP do Gateway e, no mesmo momento, os upstreams que apontavam para o IP do NGINX. Não tente reaproveitar o IP antigo: o AKS apaga os IPs públicos que ele gerencia quando o Service dono é removido, mesmo marcados como Static. Acompanhe as métricas de requisição do NGINX até zerar.
8. Limpar. Com o tráfego estável no Gateway:
az aks approuting update --resource-group rg-aks --name aks-prod --nginx None
kubectl delete nginxingresscontrollers.approuting.kubernetes.azure.com --all
O primeiro comando só para o add-on de reconciliar o controller padrão; o Deployment e o Service do nginx continuam lá até você apagar os NginxIngressController. Depois, suba o TTL de volta.
E o rollback? Até o passo 8, é simétrico: os Ingress continuam no cluster, então voltar é apontar o DNS de novo para o IP do NGINX. Depois do kubectl delete nginxingresscontrollers, voltar exige reabilitar o controller e recriar o que você apagou. Por isso o passo 6 existe.
[IMAGEM: dois IPs lado a lado no mesmo cluster, NGINX e Gateway, com o registro DNS mudando de um para o outro e o TTL de 60 s em destaque]
Então, o NGINX do app routing acabou?
Acabou. Não no sentido de sumir do cluster em dezembro, mas no sentido que importa para produção: novembro de 2026 é o último mês com alguém da Microsoft corrigindo vulnerabilidade crítica nele. Daí em diante, cada CVE do NGINX é problema seu.
A boa notícia é que, para a maioria dos clusters, a migração é menor do que parece. Se o seu Ingress roteia HTTP e HTTPS por host e path, o approuting-istio faz o mesmo trabalho com HPA, PDB e upgrade gerenciados. A má notícia é que você só descobre se está nessa maioria fazendo o inventário.
Próximo passo: roda o kubectl get ingress -A do começo deste post e, para cada Ingress da classe do add-on, lista as anotações que ele usa. Tudo que for rate limit, limite de body ou snippet entra na coluna "precisa de decisão". O resto entra na coluna "migra esta semana".
E aí, gostou? Se o seu time precisa migrar o ingress do AKS antes que o suporte acabe, a gente na AzureBrasil.cloud pode te ajudar.
Referências
- AKS managed NGINX ingress with the application routing add-on (Microsoft Learn): aviso de aposentadoria, prazo de novembro de 2026, classe
webapprouting.kubernetes.azure.com, limitações e riscos de multi-tenant. - Application routing add-on with the Kubernetes Gateway API (Microsoft Learn):
approuting-istio, comandos de habilitação, limitações, HPA, PDB e upgrades. - Migrate from application routing ingress-nginx to Gateway API (Microsoft Learn): diferenças, passo a passo, validação, cutover e rollback.
- Configure Azure DNS and TLS with the application routing Gateway API (Microsoft Learn): opções de TLS no listener,
ClusterExternalDNSeExternalDNS. - Managed Gateway API installation (Microsoft Learn): CRDs gerenciados e versões do bundle por versão do Kubernetes.
- What is Application Gateway for Containers? (Microsoft Learn): arquitetura, features e regiões do AGC.
- App Routing Gateway API is GA (blog do AKS): GA na release 20260428.
- Ingress NGINX Retirement (blog do Kubernetes): anúncio do SIG Network.
- ingress2gateway: ferramenta de conversão de Ingress para Gateway API.