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)

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-gateway-api --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-gateway-api --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.

Para usar o Terraform para criar um cluster do AKS com a implementação da API de Gateway de roteamento de aplicativos habilitada, você precisa:

• Terraform versão 1.9.0 ou posterior instalado.
• CLI do Azure instalada e autenticada. Execute az --version para localizar sua azure-cli versão e execute az upgrade para atualizar. Use o CLI do Azure para se conectar ao cluster depois que o Terraform o criar.
• kubectl instalado. Você pode instalá-lo localmente usando o az aks install-cli comando. Você usa kubectl para implantar o aplicativo de exemplo e os recursos da API de Gateway.

Implantar um cluster AKS com a implementação da API Gateway para roteamento de aplicativos usando o Terraform

Esta seção mostra como usar o Terraform para implantar um cluster do AKS com a instalação gerenciada da API de Gateway e a implementação da API de Gateway para roteamento de aplicações habilitadas.

Este exemplo implanta:

• Um grupo de recursos.
• Um cluster do AKS que usa o plug-in de rede CNI Azure e um balanceador de carga padrão.
• A instalação da API do Gateway Gerenciado e a implementação da API do Gateway de roteamento de aplicativos, ambas habilitadas no cluster por meio do provedor AzAPI. Habilitar ambas as configurações disponibiliza o GatewayClass approuting-istio gerenciado pelo AKS no cluster.

1. Crie um diretório para testar e executar o código terraform de exemplo e torná-lo o diretório atual.

2. Crie um arquivo chamado main.tf, depois insira o código a seguir:

   terraform {
     required_version = ">= 1.9.0"
   
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~> 4.0"
       }
       azapi = {
         source  = "Azure/azapi"
         version = "~> 2.0"
       }
       random = {
         source  = "hashicorp/random"
         version = "~> 3.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
   }
   
   provider "azapi" {
     enable_preflight = true
   }
   
   resource "random_string" "suffix" {
     length  = 6
     upper   = false
     special = false
   }
   
   locals {
     location            = "eastus"
     resource_group_name = "rg-aks-gateway-api-${random_string.suffix.result}"
     cluster_name        = "aks-gwapi-${random_string.suffix.result}"
   }
   
   resource "azurerm_resource_group" "example" {
     name     = local.resource_group_name
     location = local.location
   }
   
   resource "azurerm_kubernetes_cluster" "example" {
     name                              = local.cluster_name
     location                          = azurerm_resource_group.example.location
     resource_group_name               = azurerm_resource_group.example.name
     dns_prefix                        = local.cluster_name
     role_based_access_control_enabled = true
   
     default_node_pool {
       name       = "system"
       node_count = 2
       vm_size    = "Standard_D4s_v4"
   
       upgrade_settings {
         drain_timeout_in_minutes      = 0
         max_surge                     = "10%"
         node_soak_duration_in_minutes = 0
       }
     }
   
     identity {
       type = "SystemAssigned"
     }
   
     network_profile {
       network_plugin    = "azure"
       load_balancer_sku = "standard"
     }
   }
   
   resource "azapi_update_resource" "gateway_api_app_routing" {
     type        = "Microsoft.ContainerService/managedClusters@2026-03-01"
     resource_id = azurerm_kubernetes_cluster.example.id
     body = {
       properties = {
         ingressProfile = {
           gatewayAPI = {
             installation = "Standard"
           }
           webAppRouting = {
             gatewayAPIImplementations = {
               appRoutingIstio = {
                 mode = "Enabled"
               }
             }
           }
         }
       }
     }
     response_export_values = [
       "properties.ingressProfile"
     ]
     depends_on = [
       azurerm_kubernetes_cluster.example
     ]
   }
   
   output "resource_group_name" {
     value = azurerm_resource_group.example.name
   }
   
   output "cluster_name" {
     value = azurerm_kubernetes_cluster.example.name
   }
   
   output "get_credentials_command" {
     value = "az aks get-credentials --resource-group ${azurerm_resource_group.example.name} --name ${azurerm_kubernetes_cluster.example.name} --overwrite-existing"
   }
   

3. Inicialize o Terraform executando o terraform init comando. Esse comando baixa os provedores de Azure necessários para gerenciar Azure recursos com o Terraform.

   terraform init
   

4. Formate e valide a configuração executando os comandos terraform validate e terraform fmt.

   terraform fmt
   terraform validate
   

5. Crie um plano de execução do Terraform executando o terraform plan comando. Este comando mostra os recursos que o Terraform cria ou modifica em sua assinatura Azure.

   terraform plan
   

6. Aplique o plano de execução do Terraform executando o terraform apply comando. Esse comando cria os recursos definidos em seu main.tf arquivo em sua assinatura Azure. Quando solicitado, insira yes para confirmar.

   terraform apply
   

Conectar-se ao cluster do AKS usando o Terraform

1. Obtenha os nomes do grupo de recursos e do cluster a partir das saídas do Terraform.

   terraform output -raw resource_group_name
   terraform output -raw cluster_name
   

2. Configure kubectl para se conectar ao seu cluster usando o comando az aks get-credentials. Este comando baixa as credenciais e configura a CLI do Kubernetes para usá-las. Substitua <resource-group-name> e <cluster-name> pelos valores das etapas anteriores. Como alternativa, execute terraform output -raw get_credentials_command para obter o comando completo pronto para execução.

   az aks get-credentials --resource-group <resource-group-name> --name <cluster-name>
   

3. Verifique se o cluster está em execução executando o kubectl get nodes comando.

   kubectl get nodes
   

Verificar a configuração da API do Gateway usando o Terraform

1. Confirme se os istiod pods estão em execução no aks-istio-system namespace.

   kubectl get pods -n aks-istio-system
   

2. Confirme se o approuting-istio GatewayClass existe e é aceito.

   kubectl get gatewayclass
   

   O approuting-istio GatewayClass deve retornar True na ACCEPTED coluna.

Configurar a entrada usando um Gateway do Kubernetes com o Terraform

Implantar o aplicativo de exemplo usando o Terraform

Implante o aplicativo de exemplo httpbin no default namespace:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.27/samples/httpbin/httpbin.yaml

Verifique se o httpbin pod e o serviço estão disponíveis:

kubectl get pods -l app=httpbin
kubectl get svc httpbin

Criar os recursos de Gateway e HTTPRoute usando o Terraform

O exemplo de implementação da Gateway API para roteamento de aplicativos inclui um manifesto Gateway que cria um listener HTTP na porta 80 e usa a GatewayClass approuting-istio gerenciada pelo AKS.

1. Crie um arquivo chamado gateway.yaml, depois insira o código a seguir:

   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
   

2. Aplique a Gateway configuração:

   kubectl apply -f gateway.yaml
   

   O exemplo também inclui um manifesto HTTPRoute que roteia solicitações para httpbin.example.com/get para o serviço httpbin na porta 8000.

3. Crie um arquivo chamado httproute.yaml, depois insira o código a seguir:

   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
   

4. Aplique a HTTPRoute configuração:

   kubectl apply -f httproute.yaml
   

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

kubectl get deployment httpbin-gateway-approuting-istio
kubectl get service httpbin-gateway-approuting-istio
kubectl get hpa httpbin-gateway-approuting-istio
kubectl get pdb httpbin-gateway-approuting-istio

Enviar uma solicitação para o aplicativo de exemplo usando o Terraform

Aguarde até que o Gateway relate uma Programmed condição e, em seguida, obtenha seu endereço externo:

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, envie uma solicitação para httpbin por meio do Gateway:

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

Você deve ver uma HTTP 200 resposta.

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

Limpar recursos usando o Terraform

Nesta seção, você implantou um aplicativo de exemplo com escopo de namespace e recursos de API de Gateway. Se você não precisar mais desses recursos do Kubernetes, exclua-os antes de remover a infraestrutura de Azure subjacente.

Exclua o HTTPRoute, o Gateway e o aplicativo de exemplo usando o comando kubectl delete:

kubectl delete -f httproute.yaml
kubectl delete -f gateway.yaml
kubectl delete -f https://raw.githubusercontent.com/istio/istio/release-1.27/samples/httpbin/httpbin.yaml

Remova os recursos de Azure criados pelo Terraform usando o terraform destroy comando. Quando solicitado, insira yes para confirmar.

terraform destroy