Configurar o ingress através da API Gateway do Kubernetes via o add-on de encaminhamento de aplicações para o Azure Kubernetes Service (AKS)

Atenção

A Rede SIG Kubernetes e o Comité de Resposta à Segurança anunciaram a próxima retirada do projeto Ingress NGINX, com a manutenção a terminar em março de 2026. Hoje em dia, não é necessária uma ação imediata para clusters AKS que utilizam o complemento de encaminhamento de aplicações com NGINX. A Microsoft fornecerá suporte oficial para patches de segurança críticos para recursos adicionais NGINX Ingress de encaminhamento de aplicações até novembro de 2026.

O AKS está a alinhar-se com o Kubernetes upstream ao adotar a API Gateway como padrão de longo prazo para a gestão de tráfego de entrada e L7. Recomendamos que comece a planear o seu percurso de migração com base na sua configuração atual:

O complemento de encaminhamento de aplicações suporta a API Kubernetes Gateway para gestão de tráfego de entrada. A API Kubernetes Gateway é um conjunto de recursos que fornecem uma estrutura padronizada, orientada para papéis e extensível para a gestão de tráfego, concebida para ser sucessora e evolução da API Ingress. A implementação da API Gateway de encaminhamento de aplicações visa assim servir como sucessora do add-on gerido NGINX, que se baseia na API Ingress legada e deixará de receber suporte da Azure a partir de novembro de 2026. Se estiver a usar NGINX gerido, deve migrar para a implementação da API de Gateway de roteamento de aplicações, ou para outra implementação suportada, até novembro de 2026.

Para cargas de trabalho de produção, este é o modelo de ingress predefinido recomendado no AKS Automatic. A partir da versão 1.36 do AKS, os novos clusters do AKS Automatic utilizam, por predefinição, a API Gateway do Kubernetes através do suplemento de encaminhamento de aplicações. Para contexto sobre os padrões de produção do AKS Automatic, veja O que é o Azure Kubernetes Service (AKS) Automatic?

Comparação com a extensão de malha de serviços Istio

O complemento de encaminhamento de aplicações Kubernetes Gateway API implementa um plano de controlo Istio para gerir a infraestrutura dos recursos da API Kubernetes Gateway. No entanto, difere do complemento de malha de serviço Istio para AKS das seguintes formas:

Feature API de Gateway de Encaminhamento de Aplicações Complemento de malha-de-serviço Istio
Nome da Classe Gateway approuting-istio istio
Injeção de sidecar e suporte para Istio CRD Não suportado. Apenas gere a infraestrutura dos recursos da API do Kubernetes Gateway Suportado
Revisões e atualizações Não revisto. Atualizado no local para atualizações de versões menores e de patches Revisto. Atualizado via atualizações canário para atualizações menores de versão e diretamente para atualizações de patch

Quando usar a API de Gateway de roteamento de aplicações em produção

Use esta implementação como caminho de entrada predefinido quando quiser:

  • Um sistema de entrada gerido e pronto para produção no AKS Automatic.
  • entrada HTTP/HTTPS nativa da Gateway API do Kubernetes
  • Infraestrutura de gateways gerida com salvaguardas operacionais integradas, como dimensionamento automático e limites de indisponibilidade nos proxies de gateway.

Considere alternativas quando precisar de capacidades fora do suporte atual neste artigo, tais como:

  • Comportamento completo da malha de serviços Istio, com gestão de tráfego baseada em sidecar e utilização mais alargada dos CRD do Istio.
  • Funcionalidades atualmente listadas como não suportadas, como o SNI passthrough baseado em TLSRoute.

Limitações

  • Não é possível ativar a implementação do Gateway API para encaminhamento de aplicações e o suplemento de malha de serviços Istio em simultâneo. Deves desativar um primeiro e ativar o outro numa operação separada. Ao fazer a transição do complemento mesh de serviço Istio para a implementação da API de encaminhamento de aplicações Gateway, deve eliminar os CRDs Istio GatewayClass e Istio após desativar o add-on Istio. O add-on do Istio instala CRDs (como virtualservices.networking.istio.io, destinationrules.networking.istio.io e outros nos grupos da API networking.istio.io, security.istio.io, telemetry.istio.io e extensions.istio.io) que não são removidos quando o add-on é desativado. Se estes CRDs permanecerem no cluster, o plano de controlo Istio da API Gateway de encaminhamento da aplicação falha em iniciar. Execute o seguinte comando para os eliminar:

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

    Observação

    Se já tiveres recursos personalizados do Istio (como VirtualServices ou DestinationRules), eliminar os CRDs também elimina esses recursos. Certifique-se de que já não precisa deles antes de avançar.

  • A implementação da API Gateway de roteamento de aplicações utiliza a mesma lista de permissão de personalização de recursos como o add-on Istio para validar as personalizações do ConfigMap para Gateway recursos. Os webhooks geridos por extensões bloqueiam personalizações que não constam da lista de permissões.

  • Atualmente, não é suportado configurar o acesso de entrada HTTPS a serviços HTTPS (por exemplo, Server Name Indication (SNI) Passthrough) através do recurso TLSRoute. O suporte para o TLSRoute recurso estará disponível assim que o AKS adicionar suporte para o Istio 1.30, altura em que o plano de controlo do Istio de roteamento da sua aplicação será automaticamente atualizado para essa versão.

  • A gestão de tráfego de saída através da implementação da API de Gateway de roteamento de aplicações não é suportada.

  • Injetar sidecars não geridos pela Microsoft (por exemplo, telemetria personalizada, registo ou agentes de segurança) nos proxy pods do gateway Istio geridos pelo add-on de roteamento de aplicações não é oficialmente suportado. Se optar por injetar o seu próprio sidecar num proxy pod gerido, a Microsoft oferece apenas suporte de melhor esforço para quaisquer problemas que encontre.

  • O registo de acessos do Envoy está ativado por defeito nos pods do proxy de Gateway, mas o formato, o âmbito e o provedor do registo não podem ser personalizados através da API do Istio Telemetry. Para personalizar, utilize, em vez disso, o ingress da Gateway API na extensão de malha de serviço Istio.

Pré-requisitos

Atualizar a versão do CLI do Azure

Você deve usar a versão azure-cli2.86.0 ou superior. Corre az --version para encontrar a tua azure-cli versão e corre az upgrade para atualizar.

Ativar CRDs da API de Gateway Geridosa

Ative a instalação da API do Gateway Gerido. A utilização de CRDs de API de Gateway autogeridos com o complemento de roteamento de aplicações não é suportada.

Comportamento automático predefinido do AKS (AKS 1.36 e posteriores)

Nos novos clusters automáticos AKS com AKS 1.36 ou posterior, a API Kubernetes Gateway através do complemento de encaminhamento de aplicações está ativada por defeito.

Normalmente não precisas de executar o comando de ativação de funcionalidades a menos que estejas:

  • Utilizar um cluster existente.
  • A executar uma versão anterior do AKS.
  • Reativar a funcionalidade depois de a desativar.

Ativar a implementação da API Gateway para roteamento de aplicações

Observação

Se criar um novo cluster AKS Automatic no AKS 1.36 ou posterior, esta funcionalidade está ativada por predefinição. Use os comandos desta secção para clusters AKS Standard, versões anteriores ou clusters existentes que ainda não tenham a funcionalidade ativada.

Ativar durante a criação do cluster

Execute o seguinte comando para ativar a implementação da Gateway API de encaminhamento de aplicações durante a criação do cluster AKS Standard:

# 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

Ativar para um cluster existente

Execute o seguinte comando para ativar a implementação da API do Gateway de roteamento de aplicações 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

Deves ver istiod os pods no aks-istio-system namespace:

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

Também deves ver o ValidatingWebhookConfiguration ser implementado:

kubectl get validatingwebhookconfiguration

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

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

kubectl get cm -n aks-istio-system

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

Configurar ingresso usando um Gateway Kubernetes

Implementar aplicação 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 Gateway Kubernetes e HTTPRoute

Em seguida, implante uma configuração de API Gateway no namespace default, com o gatewayClassName definido como 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

Observação

O exemplo acima cria um serviço de balanceador de carga de entrada externo que pode ser acessado de fora do cluster. Podes adicionar anotações para criar um balanceador de carga interno e personalizar outras definições do balanceador.

Observação

Por defeito, o plano de controlo do Istio irá adicionar o GatewayClass nome approuting-istio ao nome dos recursos que provisiona para o Gateway. Pode anotar o seu Gateway recurso com o gateway.istio.io/name-override para substituir o nome dos recursos provisionados. Os nomes dos recursos devem ser menores que 63 caracteres e devem ser um nome DNS válido.

Verifique se um 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 pedido para aplicação 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ê verá uma HTTP 200 resposta.

Observação

Para proteger o tráfego de entrada com a implementação da API de encaminhamento de aplicações e integrar com o DNS do Azure para gestão de nomes de host, consulte Configurar DNS do Azure e TLS com a implementação da API de encaminhamento de aplicações para o fluxo de trabalho automatizado alimentado pelo operador de encaminhamento de aplicações. Para um fluxo de trabalho manual de terminação de TLS que não dependa da integração do operador, consulte Proteja o tráfego de entrada com a implementação da API Gateway de encaminhamento de aplicações.

Registo de acessos

A implementação da Gateway API para encaminhamento de aplicações ativa, por predefinição, o registo de acessos do Envoy em todos os pods proxy Gateway geridos. Os registos de acesso são gravados na saída padrão do contentor de proxy, no formato de texto predefinido do Envoy. Pode visualizar os registos usando kubectl logs:

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

Cada pedido que o gateway gere produz uma linha de registo contendo detalhes como o método HTTP, caminho, código de resposta, serviço a montante e tamanhos de pedido e resposta. Este detalhe facilita a observação do tráfego de entrada e a resolução de problemas de encaminhamento sem qualquer configuração adicional.

Versionamento e Melhorias

A implementação da API Gateway de encaminhamento de aplicações implementa e atualiza o plano de controlo do Istio com base na versão Kubernetes do cluster AKS para atualizações tanto menores como de patch. Este modelo in-situ está alinhado com os padrões de produção automática do AKS, onde a gestão do ciclo de vida da plataforma é concebida para reduzir operações manuais.

A versão Istio é a versão menor Istio mais suportada que é compatível com a versão AKS do teu cluster. Por exemplo, se estiveres a utilizar a versão 1.34 do AKS, a versão secundária máxima do Istio suportada que pode ser instalada (em março de 2026) é 1.28. Tenha em mente que a versão máxima do Istio suportada para uma determinada versão do Kubernetes pode diferir entre clusters de Long-Term Support (LTS) e clusters sem LTS.

Para encontrar a versão menor Istio mais suportada para a sua versão AKS Kubernetes, consulte o calendário de lançamentos de add-ons do service mesh. Embora a implementação da API Gateway para encaminhamento de aplicações não tenha revisões, a versão secundária do plano de controlo do Istio corresponde à revisão do suplemento da malha de serviço indicada (por exemplo: para o suplemento da malha de serviço asm-1-28, a versão secundária do plano de controlo do Istio para encaminhamento de aplicações é 1.28). Também pode ver a versão menor do Istio verificando a versão do patch na imagem de implementação do Istiod:

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

Atualizações

As atualizações de patch e de versões secundárias do plano de controlo do Istio para a implementação da Gateway API de encaminhamento de aplicações são efetuadas no local. As atualizações de versões do patch são ativadas automaticamente como parte dos lançamentos do AKS. Atualizações de versões menores podem ser acionadas automaticamente ou manualmente, dependendo da versão AKS Kubernetes e do calendário dos lançamentos das versões menores do Istio. Atualizações menores de versão ocorrem nos seguintes cenários:

  • O cluster AKS é atualizado para uma nova versão, à qual está associada uma versão máxima suportada do Istio mais elevada. O plano de controlo do Istio é atualizado para a versão secundária mais recente no âmbito da atualização do cluster AKS.
  • Uma nova versão Istio é lançada para AKS e torna-se a versão Istio mais suportada para a versão do cluster AKS. Após a implementação na sua região, o plano de controlo Istio no seu cluster atualiza automaticamente para a nova versão menor. Para acompanhar os lançamentos das novas versões do Istio e ver quando a nova versão será lançada na sua região, siga as notas de lançamento do AKS e o rastreador de lançamentos do AKS.

Podem ocorrer interrupções no trânsito durante o processo de atualização. Para minimizar perturbações durante as atualizações, o complemento de encaminhamento de aplicações implementa um Horizontal Pod Autoscaler (HPA) com duas réplicas mínimas e um PodDisruptionBudget (PDB) com uma disponibilidade mínima de uma para cada Gateway. Pode personalizar estes recursos para modificar essas definições.

Personalizações de recursos

Personalização do plano de controlo Horizontal Pod Autoscaling (HPA)

A implementação da Gateway API de roteamento de aplicação suporta a personalização do plano de controlo do Istio para o Horizontal Pod Autoscaler (HPA). 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%

Observação

Para evitar conflitos com o PodDisruptionBudget, a implementação da API do Gateway de roteamento de aplicações não permite definir o minReplicas para menor do que o padrão inicial de 2.

A configuração do HPA pode ser modificada através 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 de Gateway

A implementação da API do Gateway de encaminhamento de aplicações suporta a personalização de Gateway recursos através de anotações e ConfigMaps. O roteamento de aplicações utiliza a mesma lista de autorização para personalização de recursos que o complemento de malha de serviços Istio para personalização de recursos da API Gateway. Siga os passos na documentação do add-on Gateway API do Istio para configurar os recursos gerados para o Gateways e para ver quais os campos que se enquadram na lista de permissões.

Observação

O istio-gateway-class-defaults ConfigMap é provisionado e reconciliado pelo AKS quando os CRDs da API de Gateway Gerido e a implementação da API de Gateway para encaminhamento de aplicações são habilitados em conjunto. Se anteriormente criou o istio-gateway-class-defaults ConfigMap no aks-istio-system namespace por si próprio, deve eliminar a instância autogerida do ConfigMap antes de ativar os CRDs da API do Gateway Gerido para evitar conflitos com a reconciliação do ConfigMap gerido pelo AKS.

Observação

A implementação da API de encaminhamento de aplicações do Gateway adiciona anotações do Balanceador de Carga do Azure ao Gateway Serviço para configurar sondas de saúde para a definição padrão externalTrafficPolicy de "Cluster." Se definir spec.externalTrafficPolicy para "Local", deve desdefinir as seguintes anotações tanto no ConfigMap ao nível do GatewayClass quer no ConfigMap per-Gateway:

 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:

Desativar a implementação da API Gateway de roteamento de aplicações

Execute o seguinte comando para desativar a implementação da API do Gateway de roteamento de aplicações:

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

Limpeza de recursos

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

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

Se criaste um ConfigMap para personalizar o teu Gateway, executa o seguinte comando para eliminar o ConfigMap:

kubectl delete configmap gw-options

Se criou um SecretProviderClass e um segredo para usar na terminação TLS, elimine os seguintes recursos:

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

Conteúdo relacionado

  • Last updated on