Início Rápido: Implantar o Gateway de Aplicativo para o Controlador ALB de Contêineres usando o complemento do AKS

O Controlador ALB é responsável por traduzir a API de Gateway e a configuração da API de Entrada no Kubernetes para regras de balanceamento de carga no Gateway de Aplicativo para Contêineres. O guia a seguir descreve as etapas necessárias para habilitar os complementos da API Gateway gerenciada do AKS e do controlador ALB do Gateway de Aplicativo para Contêineres em um cluster do AKS (Serviço de Kubernetes do Azure) novo ou existente.

Pré-requisitos

Você precisa concluir as seguintes tarefas antes de habilitar o complemento do Controlador ALB em seu cluster:

1. Prepare sua assinatura do Azure e seu cliente az-cli.

   • CLI do Azure
   • Azure PowerShell

   # Sign in to your Azure subscription.
   SUBSCRIPTION_ID='<your subscription id>'
   az login
   az account set --subscription $SUBSCRIPTION_ID
   
   # Register required resource providers on Azure.
   az provider register --namespace Microsoft.ContainerService
   az provider register --namespace Microsoft.Network
   az provider register --namespace Microsoft.NetworkFunction
   az provider register --namespace Microsoft.ServiceNetworking
   
   # Install Azure CLI extensions.
   az extension add --name alb
   az extension add --name aks-preview 
   

2. Registrar recurso de complemento

   Use a CLI do Azure para registrar o recurso adicional.

   # Register required preview features
   az feature register --namespace "Microsoft.ContainerService" --name "ManagedGatewayAPIPreview"
   az feature register --namespace "Microsoft.ContainerService" --name "ApplicationLoadBalancerPreview"
   

   Importante

   A extensão do AKS para o Application Gateway for Containers está atualmente em versão prévia.
   Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Configurar um cluster do AKS com o complemento do AKS

O complemento do AKS pode ser habilitado em clusters novos ou existentes.

Os seguintes requisitos de cluster do AKS são necessários para o provisionamento bem-sucedido do complemento:

• Deve estar em uma região em que o Gateway de Aplicativo para Contêineres esteja disponível.
• Deve usar CNI do Azure ou Sobreposição de CNI do Azure.
• Deve ter o recurso de identidade da carga de trabalho habilitado. Saiba como habilitar a identidade de carga de trabalho em um cluster de AKS existente.
• Deve estar usando uma versão do Kubernetes do AKS com suporte.

Novo cluster

Use os comandos a seguir para criar um novo cluster do AKS com a CNI do Azure, a identidade da carga de trabalho habilitada, o complemento da API do gateway e o complemento do Gateway de Aplicativo para Contêineres habilitado.

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'
LOCATION='northeurope'
VM_SIZE='<the size of the vm in AKS>' # The size needs to be available in your location

az group create --name $RESOURCE_GROUP --location $LOCATION
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $AKS_NAME \
    --location $LOCATION \
    --node-vm-size $VM_SIZE \
    --network-plugin azure \
    --enable-oidc-issuer \
    --enable-workload-identity \
    --enable-gateway-api \
    --enable-application-load-balancer \
    --generate-ssh-key

Cluster existente

Adicionar pré-requisitos a um cluster existente

Se estiver usando um cluster existente, habilite o suporte à Identidade de Carga de Trabalho no cluster do AKS. As identidades de carga de trabalho podem ser habilitadas por meio dos seguintes comandos:

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'
az aks update -g $RESOURCE_GROUP -n $AKS_NAME --enable-oidc-issuer --enable-workload-identity --no-wait

$AKS_NAME = '<your cluster name>'
$RESOURCE_GROUP = '<your resource group name>'

# Get the AKS cluster object
$cluster = Get-AzAksCluster -ResourceGroupName $RESOURCE_GROUP -Name $AKS_NAME

# Set security profile
$cluster.SecurityProfile.WorkloadIdentity = $True

# Update the cluster
Set-AzAksCluster -InputObject $cluster -EnableOidcIssuer

Instalar o complemento do Controlador ALB

Com um cluster existente, você pode habilitar os complementos da API do Gateway e do Gateway de Aplicativo para Contêineres com os seguintes comandos:

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'

# Update the AKS cluster
az aks update --name ${AKS_NAME} --resource-group ${RESOURCE_GROUP} --enable-gateway-api --enable-application-load-balancer

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'
AKS_ID=$(az aks show -g $RESOURCE_GROUP -n $AKS_NAME --query id -o tsv)
AKS_REGION=$(az aks show -g $RESOURCE_GROUP -n $AKS_NAME --query location -o tsv)

az rest \
  --method put \
  --uri "https://management.azure.com${AKS_ID}?api-version=2025-09-02-preview" \
  --body '{
    "location": "${AKS_REGION}",
    "properties": {
      "ingressProfile": {
        "applicationLoadBalancer": {
          "enabled": true
        },
        "gatewayAPI": {
          "installation": "Standard"
        }
      }
    }
  }' \
  --verbose

Verificar a instalação do Controlador ALB

Tanto os caminhos do novo cluster quanto os do cluster existente usam as mesmas verificações. Depois que o complemento for ativado, complete as seguintes verificações, independentemente do caminho que você usou.

Verificar os pods do controlador ALB

Verifique se os pods do Controlador ALB estão em execução no namespace kube-system:

kubectl get pods -n kube-system | grep alb-controller

Você deve ver dois pods alb-controller no estado Running:

Verificar GatewayClass

Verifique se o GatewayClass azure-alb-external está instalado no cluster:

kubectl get gatewayclass azure-alb-external -o yaml

Você deve ver que o GatewayClass tem uma condição que lê GatewayClass Válido. Essa condição indica que um GatewayClass padrão está configurado e que todos os recursos de gateway que fazem referência a esse GatewayClass são gerenciados pelo Controlador ALB.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  creationTimestamp: "2023-07-31T13:07:00Z"
  generation: 1
  name: azure-alb-external
  resourceVersion: "64270"
  uid: 6c1443af-63e6-4b79-952f-6c3af1f1c41e
spec:
  controllerName: alb.networking.azure.io/alb-controller
status:
  conditions:
    - lastTransitionTime: "2023-07-31T13:07:23Z"
    message: Valid GatewayClass
    observedGeneration: 1
    reason: Accepted
    status: "True"
    type: Accepted

Validar recursos de complemento no portal do Azure

Navegue até o grupo de recursos MC_ (nó) do seu cluster de AKS. Você deverá ver os seguintes recursos criados pelo complemento:

Identidade Gerenciada

Uma identidade nomeada applicationloadbalancer-<cluster-name> é criada com as seguintes atribuições de função:

A applicationloadbalancer-<cluster-name> identidade tem uma credencial de identidade federada configurada com as seguintes propriedades:

• Nome: aksfic
• Namespace: kube-system
• Conta de Serviço: alb-controller-sa

Sub-rede

Quando o complemento é habilitado em um cluster do AKS usando a opção de rede virtual gerenciada pelo AKS, uma sub-rede chamada aks-appgateway é criada automaticamente com a delegação habilitada para Microsoft.ServiceNetworking/TrafficController.

Próximas etapas

Agora que você instalou com sucesso um controlador ALB no seu cluster, é possível provisionar o Application Gateway para recursos de contêineres no Azure.

O próximo passo é vincular seu controlador ALB ao Application Gateway para Containers. A forma como você cria esse link depende de sua estratégia de implantação.

Há duas estratégias de implantação para o gerenciamento do Gateway de Aplicativos para contêineres:

• Traga sua própria implantação (BYO): nessa estratégia de implantação, a implantação e o ciclo de vida do recurso Gateway de Aplicativos para contêineres, do recurso Association e do recurso Frontend são assumidos por meio do portal do Azure, CLI, PowerShell, Terraform etc. e referenciados na configuração dentro do Kubernetes.
  • Para usar uma implantação BYO, consulte Criar Gateway de Aplicativos para contêineres – traga sua própria implantação.
• Gerenciado pelo Controlador ALB: nesta estratégia de implantação, o Controlador ALB implantado no Kubernetes é responsável pelo ciclo de vida do recurso Gateway de Aplicativos para contêineres e seus sub-recursos. O Controlador ALB cria o recurso Gateway de Aplicativo para Contêineres quando um recurso personalizado ApplicationLoadBalancer é definido no cluster. O ciclo de vida do serviço é baseado no ciclo de vida do recurso personalizado.
  • Para usar uma implantação gerenciada do ALB, consulte Criar Gateway de Aplicativo para Contêineres gerenciados pelo Controlador ALB.

Cenários de exemplo para experimentar

• MTLS de back-end
• Descarregamento de SSL/TLS
• Divisão de tráfego/Round Robin ponderado

Desinstalar o Gateway de Aplicativo para Contêineres e o Controlador ALB

Se você quiser desinstalar o complemento do Controlador ALB, conclua as etapas a seguir.

Desativar o complemento do controlador ALB

Desative o complemento do controlador ALB no seu cluster:

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'

# Update the AKS cluster
az aks update --name ${AKS_NAME} --resource-group ${RESOURCE_GROUP} --disable-gateway-api --disable-application-load-balancer

AKS_NAME='<your cluster name>'
RESOURCE_GROUP='<your resource group name>'
AKS_ID=$(az aks show -g $RESOURCE_GROUP -n $AKS_NAME --query id -o tsv)
AKS_REGION=$(az aks show -g $RESOURCE_GROUP -n $AKS_NAME --query location -o tsv)

az rest \
  --method put \
  --uri "https://management.azure.com${AKS_ID}?api-version=2025-09-02-preview" \
  --body '{
    "location": "${AKS_REGION}",
    "properties": {
      "ingressProfile": {
        "applicationLoadBalancer": {
          "enabled": false
        },
        "gatewayAPI": {
          "installation": "Disabled"
        }
      }
    }
  }' \
  --verbose

Excluir o Grupo de Recursos

Para limpar totalmente todos os recursos, incluindo o Gateway de Aplicativo para Contêineres, exclua o grupo de recursos:

az group delete --resource-group $RESOURCE_GROUP

Remove-AzResourceGroup -Name $RESOURCE_GROUP -Force