Configurar a entrada com a API do Gateway do Kubernetes por meio de complemento de roteamento de aplicativos para o Serviço de Kubernetes do Azure (AKS)

O complemento de roteamento de aplicativos dá suporte à API de Gateway do Kubernetes para gerenciamento de tráfego de entrada. A API de Gateway do Kubernetes é um conjunto de recursos que fornece uma estrutura padronizada, orientada para funções e extensível para gerenciamento de tráfego, projetada para ser uma sucessora e evolução da API de Ingress. Assim, a implementação da API de Gateway de roteamento de aplicações tem o objetivo de substituir o complemento NGINX gerenciado, que se baseia na API Ingress legada e deixará de receber suporte do Azure após novembro de 2026. Se você estiver usando o NGINX gerenciado, deverá migrar para a implementação da API de Gateway de roteamento de aplicativos ou outra implementação com suporte até novembro de 2026.

Para cargas de trabalho de produção, esse modelo é o modelo de entrada padrão recomendado no AKS Automatic. A partir do AKS versão 1.36, os novos clusters automáticos do AKS usam a API do Gateway do Kubernetes por meio do complemento de roteamento de aplicativos por padrão. Para obter informações sobre os padrões de produção automática do AKS, consulte O que é AKS (Serviço de Kubernetes do Azure) Automático?

Comparação com o complemento Istio Service Mesh

A implementação da API do Kubernetes do Gateway, um complemento de roteamento de aplicativos, implanta um plano de controle Istio para gerenciar a infraestrutura dos recursos da API do Kubernetes do Gateway. No entanto, difere do complemento de malha de serviço do Istio para o AKS das seguintes maneiras:

Quando usar a API do Gateway de roteamento de aplicativos em produção

Use essa implementação como o caminho de entrada padrão quando desejar:

• Um padrão de entrada gerenciada e pronta para produção no AKS Automático.
• Entrada HTTP/HTTPS nativa da API do Gateway do Kubernetes.
• Infraestrutura de gateway gerenciado com proteções operacionais internas, como dimensionamento automático e orçamentos disruptivos nos proxies de gateway.

Considere alternativas quando você precisar de recursos fora do suporte atual neste artigo, como:

• Comportamento completo da malha de serviços do Istio com gerenciamento de tráfego baseado em sidecar e uso mais amplo do CRD do Istio.
• Recursos atualmente listados como sem suporte, como a passagem de SNI baseada em TLSRoute.

Limitações

• Você não pode habilitar a implementação do Gateway API de roteamento de aplicativos e o complemento de malha de serviço Istio ao mesmo tempo. Você deve desabilitar um primeiro e habilitar o outro em uma operação separada. Ao fazer a transição do complemento de malha de serviço Istio para a implementação da API de Gateway do roteamento de aplicativos, você deve excluir a GatewayClass do Istio e os CRDs do Istio após desabilitar o complemento Istio. O complemento do Istio instala CRDs (como virtualservices.networking.istio.io, destinationrules.networking.istio.io e outros nos grupos de API networking.istio.io, security.istio.io, telemetry.istio.io e extensions.istio.io) que não são removidos quando o complemento é desativado. Se esses CRDs permanecerem no cluster, o plano de controle Istio da API de Gateway do roteamento de aplicativos falha ao ser iniciado. Execute o seguinte comando para excluí-los:

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

  Observação

  Se você tiver recursos personalizados do Istio existentes (como VirtualServices ou DestinationRules), excluir os CRDs também excluirá esses recursos. Verifique se você não precisa mais deles antes de continuar.

• A implementação da API do Gateway de roteamento de aplicativos usa a mesma lista de autorização de personalização de recursos que o complemento do Istio destinado a validar personalizações do ConfigMap para os recursos Gateway. Webhooks gerenciados por add-ons bloqueiam personalizações que não estão na lista de permissões.

• No momento, não há suporte para a configuração do acesso de entrada HTTPS para serviços HTTPS (por exemplo,a passagem de SNI (Indicação de Nome do Servidor) por meio do recurso TLSRoute. O suporte para o recurso TLSRoute estará disponível quando o AKS adicionar suporte ao Istio 1.30, quando o painel de controle do Istio de roteamento de aplicativos é atualizado de forma automática para essa versão.

• Não há suporte para o gerenciamento de tráfego de saída por meio da implementação da API de Gateway de roteamento de aplicativos.

• Não há suporte oficial para a injeção de sidecars não gerenciados pela Microsoft (por exemplo, telemetria personalizada, coleta de logs ou agentes de segurança) nos pods de proxy de gateway do Istio gerenciados pelo complemento de roteamento de aplicativos. Se você optar por injetar seu próprio sidecar em um pod de proxy gerenciado, a Microsoft fornecerá apenas suporte em regime de melhor esforço para quaisquer problemas encontrados.

• O log de acesso do Envoy é habilitado por padrão nos pods de proxy do Gateway, mas o formato do log, o escopo e o provedor não podem ser personalizados pela API Telemetry do Istio. Para personalizar, use a entrada de API do Gateway no complemento de malha de serviço do Istio em vez disso.

Pré-requisitos

Atualizar a versão da CLI do Azure

Você deve usar azure-cli versão 2.86.0 ou superior. Execute az --version para localizar sua azure-cli versão e execute az upgrade para atualizar.

Habilitar CRDs da API do Gateway Gerenciado

Habilite a instalação da API do Gateway Gerenciado. O uso de CRDs da API do Gateway autogerenciados com o complemento de roteamento de aplicativos não é compatível.

Comportamento padrão automático do AKS (AKS 1.36 e posterior)

Em novos clusters automáticos do AKS que executam o AKS 1.36 ou posterior, a API do Gateway do Kubernetes por meio do complemento de roteamento de aplicativos é habilitada por padrão.

Normalmente, você não precisa executar o comando de habilitação de recursos, a menos que seja:

• Usando um cluster existente.
• Executando uma versão anterior do AKS.
• Reinserindo o recurso depois de desabilitá-lo.

Habilitar a implementação da API do Gateway de roteamento de aplicativos

Habilitar durante a criação do cluster

Execute o seguinte comando para habilitar a implementação da API do Gateway de roteamento de aplicativos durante a criação do cluster Padrão do AKS:

# Set environment variables
export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

# Enable the application routing Gateway API implementation during AKS Standard cluster creation
az aks create --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

Habilitar para um cluster existente

Execute o seguinte comando para habilitar a implementação da API de Gateway de roteamento de aplicativos para um cluster existente:

# Set environment variables
export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

# Enable the application routing Gateway API implementation for an existing cluster
az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

Você deve visualizar pods istiod no namespace aks-istio-system:

kubectl get pods -n aks-istio-system

NAME                      READY   STATUS    RESTARTS   AGE
istiod-12a3bc45de-fghi6   1/1     Running   0          3m15s
istiod-78j9kl01mn-opqrs   1/1     Running   0          3m

Você também deve ver o ValidatingWebhookConfiguration ser implantado:

kubectl get validatingwebhookconfiguration

NAME                                        WEBHOOKS   AGE
aks-node-validating-webhook                 1          117m
azure-service-mesh-ccp-validating-webhook   1          4m2s

Se você tiver a instalação da API do Gateway Gerenciado habilitada, também deverá ver o ConfigMap de personalização do gateway Istio ser criado automaticamente:

kubectl get cm -n aks-istio-system

NAME                                  DATA   AGE
...
istio-gateway-class-defaults          2      43s
...

Configurar a entrada usando um Gateway do Kubernetes

Implantar um aplicativo de exemplo

Primeiro, implante o aplicativo de exemplo httpbin no default namespace:

export ISTIO_RELEASE="release-1.27"
kubectl apply -f https://raw.githubusercontent.com/istio/istio/$ISTIO_RELEASE/samples/httpbin/httpbin.yaml

Criar o Gateway do Kubernetes e o HTTPRoute

Em seguida, implante uma configuração de API de Gateway na namespace default com o gatewayClassName definido para approuting-istio.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpbin-gateway
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
spec:
  parentRefs:
  - name: httpbin-gateway
  hostnames: ["httpbin.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
EOF

Verifique se Deployment, Service, HorizontalPodAutoscaler, e PodDisruptionBudget sejam criados para httpbin-gateway:

kubectl get deployment httpbin-gateway-approuting-istio

NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
httpbin-gateway-approuting-istio   2/2     2            2           6m41s

kubectl get service httpbin-gateway-approuting-istio

NAME                               TYPE           CLUSTER-IP   EXTERNAL-IP      PORT(S)                        AGE
httpbin-gateway-approuting-istio   LoadBalancer   10.0.54.96   <external-ip>    15021:30580/TCP,80:32693/TCP   7m13s

kubectl get hpa httpbin-gateway-approuting-istio

NAME                               REFERENCE                                     TARGETS       MINPODS   MAXPODS   REPLICAS   AGE
httpbin-gateway-approuting-istio   Deployment/httpbin-gateway-approuting-istio   cpu: 3%/80%   2         5         2          8m13s

kubectl get pdb httpbin-gateway-approuting-istio

NAME                               MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
httpbin-gateway-approuting-istio   1               N/A               1                     9m1s

Enviar solicitação para um aplicativo de exemplo

Por fim, tente enviar uma curl solicitação para o httpbin aplicativo. Primeiro, defina a variável de INGRESS_HOST ambiente:

kubectl wait --for=condition=programmed gateways.gateway.networking.k8s.io httpbin-gateway
export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io httpbin-gateway -ojsonpath='{.status.addresses[0].value}')

Em seguida, tente enviar uma solicitação HTTP para httpbin:

curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"

Você deve ver uma HTTP 200 resposta.

Registro de acesso

A implementação da API Gateway para roteamento de aplicativos habilita, por padrão, o registro de logs de acesso do Envoy em todos os pods de proxy Gateway gerenciados. Os logs de acesso são gravados na saída padrão do contêiner de proxy no formato de texto padrão do Envoy. Você pode exibir os logs usando kubectl logs:

kubectl logs deployment/<your-gateway-name>-approuting-istio

Cada solicitação que o gateway manipula produz uma linha de log contendo detalhes como o método HTTP, o caminho, o código de resposta, o serviço upstream e os tamanhos de solicitação e resposta. Esse detalhe facilita a observação do tráfego de entrada e solução de problemas de roteamento sem nenhuma configuração adicional.

Controle de versão e atualizações

A implementação da API do Gateway de roteamento de aplicativos implanta e atualiza o plano de controle do Istio com base na versão do Kubernetes do cluster do AKS, tanto para atualizações de versão secundária quanto para atualizações de versão de patch. Esse modelo in-loco está alinhado às configurações padrão de produção do AKS Automático, em que o gerenciamento de ciclo de vida da plataforma foi projetado para reduzir as intervenções manuais.

A versão do Istio é a versão secundária máxima do Istio compatível com a sua versão do AKS do cluster. Por exemplo, se você estiver na versão 1.34do AKS, a versão secundária máxima do Istio instalada e suportada (a partir de março de 2026) é 1.28. Tenha em mente que a versão máxima do Istio compatível com uma determinada versão do Kubernetes pode ser diferente entre os clusters de Suporte de Longo Prazo (LTS) e os clusters não LTS.

Para encontrar a versão secundária máxima do Istio compatível com a sua versão do Kubernetes no AKS, consulte o calendário de lançamentos do complemento de malha de serviço. Embora a implementação da API do Gateway de roteamento de aplicativos não seja versionada, a versão secundária do plano de controle do Istio corresponde à revisão do complemento de malha de serviço (exemplo: para o complemento de malha de serviço asm-1-28, a versão secundária do plano de controle do Istio para roteamento de aplicativos seria 1.28). Você também pode ver a versão menor do Istio verificando a versão de patch na imagem de implantação do istiod:

kubectl get deployment istiod -n aks-istio-system -o=jsonpath="{.spec.template.spec.containers[*].image}"

Atualizações

As atualizações de versão de patch e de versão secundária do plano de controle do Istio para a implementação da API do Gateway de roteamento de aplicativos ocorrem in-loco. As atualizações de patch são acionadas automaticamente como parte dos lançamentos do AKS. Atualizações de versões menores podem ser disparadas automaticamente ou manualmente, dependendo da versão do Kubernetes do AKS e do cronograma de lançamentos das versões menores do Istio. As atualizações de versão secundária ocorrem nos seguintes cenários:

• O cluster do AKS foi atualizado para uma nova versão que possui uma versão máxima do Istio suportada mais alta. O plano de controle do Istio é atualizado para a versão secundária posterior como parte da atualização do cluster do AKS.
• Uma nova versão do Istio é lançada para o AKS e se torna a versão máxima do Istio com suporte para a versão do cluster do AKS. Após a distribuição para sua região, o plano de controle do Istio em seu cluster é atualizado automaticamente para a nova versão secundária. Para acompanhar as novas versões do Istio e ver quando a nova versão é lançada para sua região, siga as notas de versão do AKS e o rastreador de versão do AKS.

Interrupções de tráfego podem ocorrer durante o processo de atualização. Para minimizar interrupções durante atualizações, o complemento de roteamento de aplicativos implanta um Dimensionador Automático de Pod Vertical (HPA) com no mínimo duas réplicas e um PodDisruptionBudget (PDB) com disponibilidade mínima de um para cada Gateway. Você pode personalizar esses recursos para modificar essas configurações.

Personalizações de recursos

Personalização do dimensionamento automático horizontal do pod (HPA) do plano de controle

A implementação da API do Gateway de roteamento de aplicativos oferece suporte à personalização do Dimensionador Automático de Pod Horizontal (HPA) do plano de controle do Istio. O istiod recurso HPA tem as seguintes configurações padrão:

• Réplicas mínimas: Duas
• Réplicas máximas: cinco
• Utilização da CPU: 80%

A configuração de HPA pode ser modificada por meio de patches e edições diretas. Exemplo:

kubectl patch hpa istiod -n aks-istio-system --type merge --patch '{"spec": {"minReplicas": 3, "maxReplicas": 6}}'

Personalização de recursos do gateway

A implementação da API do Gateway de roteamento de aplicativos oferece suporte à personalização dos recursos Gateway por meio de anotações e ConfigMaps. O roteamento de aplicativos usa a mesma lista de permissões de personalização de recursos que o complemento de malha de serviço do Istio para personalização de recursos da API do Gateway. Siga as etapas nos documentos da API do Gateway de complemento do Istio para configurar os recursos gerados para o Gateways e para ver quais campos se enquadram na lista de permissões.

 service: |
    spec:
       externalTrafficPolicy: Local
    metadata:
      annotations:
        service.beta.kubernetes.io/port_80_health-probe_port:
        service.beta.kubernetes.io/port_80_health-probe_protocol:
        service.beta.kubernetes.io/port_80_health-probe_request-path:

Desabilitar a implementação da API do Gateway de roteamento de aplicativos

Execute o seguinte comando para desabilitar a implementação da API do Gateway de roteamento de aplicativos:

az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --disable-app-routing-istio

Limpar os recursos

Execute os seguintes comandos para excluir os recursos Gateway e HTTPRoute:

kubectl delete gateways.gateway.networking.k8s.io httpbin-gateway
kubectl delete httproute httpbin

Se você criou um ConfigMap para personalizar seu Gateway, execute o seguinte comando para excluir o ConfigMap:

kubectl delete configmap gw-options

Se você criou um SecretProviderClass e um segredo para usar para terminação TLS, exclua os seguintes recursos:

kubectl delete secret httpbin-credential
kubectl delete pod secrets-store-sync-httpbin
kubectl delete secretproviderclass httpbin-credential-spc

Conteúdo relacionado

• O que é AKS (Serviço de Kubernetes do Azure) Automático?
• Criar um cluster automático do AKS
• Configurar o DNS do Azure e o TLS com a implementação da API do Gateway de Roteamento de Aplicativos
• Proteger o tráfego de entrada com a implementação da API do Gateway de roteamento de aplicativos (configuração manual)