Compartilhar via

Configure a entrada com a API do Gateway do Kubernetes através do complemento de roteamento de aplicativos (versão preliminar)

Importante

As funcionalidades em versão preliminar do AKS estão disponíveis de forma optativa e por autoatendimento. As versões prévias são fornecidas “no estado em que se encontram” e “conforme disponíveis” e são excluídas dos contratos de nível de serviço e da garantia limitada. As versões prévias do AKS são parcialmente cobertas pelo suporte ao cliente em uma base de melhor esforço. Dessa forma, esses recursos não são destinados ao uso em produção. Para obter mais informações, consulte os seguintes artigos:

Cuidado

A Rede SIG do Kubernetes e o Comitê de Resposta à Segurança anunciaram a próxima desativação do projeto NGINX de entrada, com a manutenção terminando em março de 2026. Não é necessária nenhuma ação imediata hoje para clusters AKS que utilizam o complemento de roteamento de aplicativos com NGINX.. A Microsoft fornecerá suporte oficial para patches de segurança críticos para recursos de entrada NGINX de complemento de roteamento de aplicativos até Novembro de 2026.

O AKS está se alinhando ao Kubernetes upstream ao mover-se para a Gateway API como o padrão de longo prazo para o gerenciamento de entrada e tráfego L7. Recomendamos que você comece a planejar seu caminho de migração com base na configuração atual:

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.

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:

Característica API de Roteamento de Aplicações do Gateway Complemento da malha de serviço do Istio
Nome da classe de gateway approuting-istio istio
Injeção de sidecar e suporte ao Istio CRD Sem suporte. Gerencia apenas a infraestrutura para recursos da API de Gateway do Kubernetes Supported
Revisão e atualizações Não revisado. Atualizado no local para atualizações de versão secundárias e de correção Revisado. Atualizado por meio de atualizações canárias para atualizações de versão secundária e no local para atualizações de versão patch

Limitações

  • A implementação da API de roteamento de aplicativos do Gateway e o complemento de malha de serviço do Istio não podem ser ativados simultaneamente. Você deve desabilitar um primeiro e habilitar o outro em uma operação separada.
  • 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. As personalizações que não estão na lista de permitidos são bloqueadas por meio de webhooks gerenciados por complemento.
  • Atualmente, não há suporte para o gerenciamento de certificados DNS e TLS do Azure por meio do complemento de roteamento de aplicativos para a API de Gateway do Kubernetes. Você pode seguir os passos no Guia de implementação da API do Gateway de roteamento de aplicativos para entrada segura para configurar um Gateway para realizar a terminação TLS.
  • A configuração do acesso de entrada HTTPS aos serviços HTTPS – ou seja, Passagem de Indicação de Nome de Servidor (SNI) – por meio do recurso TLSRoute não tem suporte no momento.
  • O gerenciamento de tráfego de saída por meio da implementação da API Gateway de roteamento de aplicações não tem suporte.

Pré-requisitos

  • Instale a aks-preview extensão ou atualize para a versão mais recente da extensão usando os comandos [az extension add][az-extension-add] e [az extension update][az-extension-update]. se você estiver usando a CLI do Azure. Você deve usar aks-preview versão 19.0.0b24 ou posterior.

    # Install the aks-preview extension
az extension add --name aks-preview

# Update the aks-preview extension to the latest version
az extension update --name aks-preview

  • 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.

  • Registre o indicador da versão prévia do recurso da API do Gateway de Roteamento de Aplicativos

  • Registre o sinalizador de recurso AppRoutingIstioGatewayAPIPreview usando o comando az feature register.

    az feature register --namespace "Microsoft.ContainerService" --name "AppRoutingIstioGatewayAPIPreview"

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

Definir variáveis de ambiente

export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

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:

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:

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-54b4ff45cf-htph8   1/1     Running   0          3m15s
istiod-54b4ff45cf-wlvgd   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

Observação

O exemplo acima cria um serviço de balanceador de carga de entrada externo acessível de fora do cluster. Você pode adicionar anotações para criar um balanceador de carga interno e personalizar outras configurações do balanceador de carga.

Observação

Por padrão, o plano de controle do Istio acrescentará o GatewayClass nome approuting-istio ao nome dos recursos que ele provisiona para o Gateway. Você pode anotar o seu recurso Gateway com gateway.istio.io/name-override para sobrescrever o nome dos recursos provisionados. Os nomes de recurso devem ser menores que 63 caracteres e devem ser um nome DNS válido.

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.

Observação

Para proteger o tráfego de entrada com a implementação da API de roteamento de aplicativos do Gateway, consulte o guia a seguir para sincronizar segredos do Azure Key Vault (AKV) para proteger o tráfego de entrada da API do Gateway com a terminação TLS.

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 AKS, tanto para atualizações de versão secundária quanto para atualizações de versão de correção.

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. Lembre-se de que a versão máxima do Istio suportada para uma determinada versão do Kubernetes pode variar entre clusters com suporte de longo prazo (LTS) e clusters sem LTS.

Para encontrar a versão secundária máxima do Istio compatível com a sua versão do Kubernetes no AKS, você pode consultar 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 do patch na imagem de implantação 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 no mesmo local. As atualizações de versão de patch do Istio são acionadas automaticamente como parte das versões 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 dois cenários a seguir:

  • O cluster 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 será atualizado para a versão secundária superior como parte da atualização do cluster do AKS.
  • Uma nova versão do Istio é lançada para o AKS e agora é a versão máxima do Istio com suporte para a versão do cluster do AKS. O plano de controle Istio em seu cluster será atualizado automaticamente para a nova versão secundária após a implementação da atualização em sua região. Siga as notas de versão do AKS e o rastreador de versão do AKS para acompanhar as novas versões do Istio e ver quando a nova versão foi distribuída para sua região.

É possível que as interrupções de tráfego possam ocorrer durante o processo de atualização. Para minimizar interrupções durante atualizações, o complemento de roteamento de aplicativos implanta um Horizontal Pod Autoscaler (HPA) com no mínimo 2 réplicas e um PodDisruptionBudget (PDB) com disponibilidade mínima de 1 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: 2
  • Réplicas máximas: 5
  • Utilização da CPU: 80%

Observação

Para evitar conflitos com a PodDisruptionBudget, a implementação da API Gateway de roteamento de aplicativo não permite estabelecer o minReplicas abaixo do padrão inicial de 2.

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.

Observação

O ConfigMap istio-gateway-class-defaults é provisionado e reconciliado pelo AKS quando os CRDs da API do Gateway Gerenciado e a implementação da API do Gateway de Roteamento de Aplicativos estão habilitados em conjunto. Se você criou anteriormente o ConfigMap istio-gateway-class-defaults no namespace aks-istio-system por conta própria, deverá excluir a instância autogerenciada do ConfigMap antes de habilitar os CRDs da Managed Gateway API, para evitar conflitos com a reconciliação do ConfigMap gerenciado pelo AKS.

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

Recursos de limpeza

Execute os seguintes comandos para excluir o 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 também:

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

Próximas Etapas 

Proteja o tráfego de ingresso com a implementação da API Gateway de Roteamento de Aplicações

  • Last updated on