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)

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

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

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.

Para usar o Terraform para criar um cluster AKS com a implementação Gateway API de encaminhamento de aplicações ativada, precisa de:

• 1.9.0 versão ou posterior instalada.
• CLI do Azure instalada e autenticada. Corre az --version para encontrar a tua azure-cli versão e corre az upgrade para atualizar. Utiliza a CLI do Azure para te ligares ao cluster depois de o Terraform o criar.
• Kubectl instalado. Podes instalá-lo localmente usando o az aks install-cli comando. Utiliza-se kubectl para implementar a aplicação de exemplo e os recursos da API do Gateway.

Implementar um cluster AKS com a implementação da Gateway API para encaminhamento de aplicações com o Terraform

Esta secção mostra como usar o Terraform para implementar um cluster do AKS com a instalação gerida do Gateway API e a implementação do Gateway API para encaminhamento de aplicações ativados.

Este exemplo implementa:

• Um grupo de recursos.
• Um cluster AKS que utiliza o plugin de rede Azure CNI e um balanceador de carga padrão.
• A instalação da API Managed Gateway e a implementação da API Gateway para encaminhamento de aplicações, ambas ativadas no cluster através do provedor AzAPI. Ativar ambas as definições torna a approuting-istio GatewayClass gerida pelo AKS disponível no cluster.

1. Crie um diretório para testar e executar o código de exemplo do Terraform, e torne-o o diretório atual.

2. Crie um arquivo chamado main.tfe insira o seguinte código:

   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. Inicializar o Terraform executando o terraform init comando. Este comando descarrega os fornecedores do Azure necessários para gerir os recursos do Azure com o Terraform.

   terraform init
   

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

   terraform fmt
   terraform validate
   

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

   terraform plan
   

6. Aplica o plano de execução do Terraform executando o terraform apply comando. Este comando cria os recursos definidos no seu main.tf ficheiro na sua subscrição do Azure. Quando solicitado, introduza yes para confirmar.

   terraform apply
   

Liga-te ao cluster AKS usando o Terraform

1. Obtenha os nomes dos grupos de recursos e clusters dos resultados do Terraform.

   terraform output -raw resource_group_name
   terraform output -raw cluster_name
   

2. Configure kubectl para se ligar ao cluster utilizando o comando az aks get-credentials. Este comando baixa credenciais e configura a CLI do Kubernetes para usá-las. Substitua <resource-group-name> e <cluster-name> com os valores do passo anterior. Em alternativa, executa terraform output -raw get_credentials_command para obter o comando completo e pronto a correr.

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

3. Verifica se o cluster está a funcionar executando o kubectl get nodes comando.

   kubectl get nodes
   

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

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

   kubectl get pods -n aks-istio-system
   

2. Confirme que a approuting-istio GatewayClass existe e é aceite.

   kubectl get gatewayclass
   

   A approuting-istio GatewayClass deve aparecer True na ACCEPTED coluna.

Configure a entrada usando um Gateway Kubernetes com Terraform

Implemente a aplicação de exemplo usando o Terraform

Implemente a aplicação 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

Crie os recursos Gateway e HTTPRoute usando o Terraform

O exemplo de implementação da API Gateway para encaminhamento de aplicações inclui um manifesto Gateway que cria uma escuta HTTP na porta 80 e utiliza a GatewayClass approuting-istio gerida pelo AKS.

1. Crie um arquivo chamado gateway.yamle insira o seguinte código:

   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 inclui também um ficheiro de manifesto HTTPRoute que encaminha os pedidos de httpbin.example.com/get para o serviço httpbin na porta 8000.

3. Crie um arquivo chamado httproute.yamle insira o seguinte código:

   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 um 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

Envie um pedido para a aplicação de exemplo usando o Terraform

Espere que o Gateway reporte uma Programmed condição e depois obtenha o 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}')

Depois, envie uma solicitação para httpbin através do Gateway:

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

Você verá uma HTTP 200 resposta.

Para usar o portal do Azure para ativar o encaminhamento de aplicações com a implementação da API Gateway, precisa de:

• Um cluster Kubernetes padrão existente.

Ativar para um cluster existente

Para permitir o encaminhamento de aplicações com a API Gateway para um cluster existente, abra o portal Azure, selecione o seu cluster e vá ao menu Rede>Perfil de entrada. Selecione Gerir para ativar o encaminhamento de aplicações com a API do Gateway.

Configurar o Ingress usando um Kubernetes Gateway

Implementar aplicação de exemplo

Primeiro, vá ao menu de comandos Executar e use o seguinte comando para implementar a aplicação de exemplo httpbin no default namespace:

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

Vai a Serviços, gateways e ingresses>. Aplicar um YAML. O ficheiro YAML seguinte implementa uma configuração da Gateway API no namespace default com o gatewayClassName definido como approuting-istio.

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

Visualizar e gerir recursos Gateway e HTTPRoute

Pode visualizar os recursos criados de Gateway e HTTPRoute no menu de Serviços, gateways e ingresses e verificar facilmente o seu estado e endereço.

Também pode consultar mais informações sobre os seus Gateways e HTTPRoutes selecionando o nome deles. Por exemplo:

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

Limpar recursos usando o Terraform

Nesta secção, implementou uma aplicação de exemplo limitada a um namespace e recursos da Gateway API. Se já não precisar destes recursos Kubernetes, elimine-os antes de remover a infraestrutura do Azure subjacente.

Elimine HTTPRoute, Gateway e a aplicação de exemplo utilizando 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 do Azure criados pelo Terraform usando o terraform destroy comando. Quando solicitado, introduza yes para confirmar.

terraform destroy

Desative a implementação da API de encaminhamento de aplicações usando o portal Azure

Vá ao menu >Perfil de ingresso. Na secção de encaminhamento de aplicações, selecione Gerir, desmarque a caixa de seleção e selecione Guardar.

Limpar recursos usando o portal do Azure

Em Serviços, gateways e Ingresses, selecione a caixa de seleção ao lado do recurso Gateway ou HTTPRoute que quer eliminar e depois selecione Eliminar na barra de ferramentas.