O NGINX do app routing do AKS acabou: como migrar para o Gateway API

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.

16 de novembro de 2026

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 --version para conferir, az upgrade para 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 canal experimental precisam 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 Telemetry do 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 EnvoyFilter ficam 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

Confira mais:

Fique por dentro das novidades

Assine nossa newsletter e receba as últimas atualizações e artigos diretamente em seu email.

Assinar gratuitamente