> ## Content Index
> Fetch the complete content index at: https://www.azurebrasil.cloud/llms.txt
> Use this file to discover other available public pages before exploring further.

# O NGINX do app routing do AKS acabou: como migrar para o Gateway API
- URL: https://www.azurebrasil.cloud/blog/nginx-controller-deprecated-aks/
- Published: 2026-11-16T21:45:36.000Z
- Updated: 2026-11-16T21:45:36.000Z
- Description: 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.
- Author: Bruno Brito
- Tags: kubernetes, AKS, DevOps, networking

Roda isso no seu cluster:

```bash
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:

```bash
kubectl delete crd $(kubectl get crd -o name | grep -E 'istio\.io')
kubectl delete gatewayclass istio

```

Com isso resolvido, num cluster existente é um comando:

```bash
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:

```bash
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:

```yaml
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:

```yaml
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:

```bash
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ê:

```yaml
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:

```bash
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](https://github.com/kubernetes-sigs/ingress2gateway?ref=azurebrasil.cloud), 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:

```bash
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:

```bash
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](https://learn.microsoft.com/azure/aks/app-routing?ref=azurebrasil.cloud) (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](https://learn.microsoft.com/azure/aks/app-routing-gateway-api?ref=azurebrasil.cloud) (Microsoft Learn): `approuting-istio`, comandos de habilitação, limitações, HPA, PDB e upgrades.
- [Migrate from application routing ingress-nginx to Gateway API](https://learn.microsoft.com/azure/aks/app-routing-nginx-to-gateway-api-migration?ref=azurebrasil.cloud) (Microsoft Learn): diferenças, passo a passo, validação, cutover e rollback.
- [Configure Azure DNS and TLS with the application routing Gateway API](https://learn.microsoft.com/azure/aks/app-routing-gateway-api-dns-tls?ref=azurebrasil.cloud) (Microsoft Learn): opções de TLS no listener, `ClusterExternalDNS` e `ExternalDNS`.
- [Managed Gateway API installation](https://learn.microsoft.com/azure/aks/managed-gateway-api?ref=azurebrasil.cloud) (Microsoft Learn): CRDs gerenciados e versões do bundle por versão do Kubernetes.
- [What is Application Gateway for Containers?](https://learn.microsoft.com/azure/application-gateway/for-containers/overview?ref=azurebrasil.cloud) (Microsoft Learn): arquitetura, features e regiões do AGC.
- [App Routing Gateway API is GA](https://blog.aks.azure.com/2026/06/10/app-routing-gateway-api-ga?ref=azurebrasil.cloud) (blog do AKS): GA na release 20260428.
- [Ingress NGINX Retirement](https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/?ref=azurebrasil.cloud) (blog do Kubernetes): anúncio do SIG Network.
- [ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway?ref=azurebrasil.cloud): ferramenta de conversão de Ingress para Gateway API.