Quickstart: Deploy Application Gateway for Containers ALB Controller

The ALB Controller is responsible for translating Gateway API and Ingress API configuration within Kubernetes to load balancing rules within Application Gateway for Containers. The following guide walks through the steps needed to provision an ALB Controller into a new or existing AKS cluster.


You need to complete the following tasks prior to deploying Application Gateway for Containers on Azure and installing ALB Controller on your cluster:

  1. Prepare your Azure subscription and your az-cli client.

    # 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
  2. Set an AKS cluster for your workload.


    The AKS cluster needs to be in a region where Application Gateway for Containers is available AKS cluster should use Azure CNI. AKS cluster should have the workload identity feature enabled. Learn how to enable workload identity on an existing AKS cluster.

    If using an existing cluster, ensure you enable Workload Identity support on your AKS cluster. Workload identities can be enabled via the following:

     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

    If you don't have an existing cluster, use the following commands to create a new AKS cluster with Azure CNI and workload identity enabled.

    AKS_NAME='<your cluster name>'
    RESOURCE_GROUP='<your resource group name>'
    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 \
  3. Install Helm

    Helm is an open-source packaging tool that is used to install ALB controller.


    Helm is already available in Azure Cloud Shell. If you are using Azure Cloud Shell, no additional Helm installation is necessary.

    You can also use the following steps to install Helm on a local device running Windows or Linux. Ensure that you have the latest version of helm installed.

    See the instructions for installation for various options of installation. Similarly, if your version of Windows has Windows Package Manager winget installed, you may execute the following command:

    winget install helm.helm

Install the ALB Controller

  1. Create a user managed identity for ALB controller and federate the identity as Workload Identity to use in the AKS cluster.

    RESOURCE_GROUP='<your resource group name>'
    AKS_NAME='<your aks cluster name>'
    mcResourceGroup=$(az aks show --resource-group $RESOURCE_GROUP --name $AKS_NAME --query "nodeResourceGroup" -o tsv)
    mcResourceGroupId=$(az group show --name $mcResourceGroup --query id -otsv)
    echo "Creating identity $IDENTITY_RESOURCE_NAME in resource group $RESOURCE_GROUP"
    az identity create --resource-group $RESOURCE_GROUP --name $IDENTITY_RESOURCE_NAME
    principalId="$(az identity show -g $RESOURCE_GROUP -n $IDENTITY_RESOURCE_NAME --query principalId -otsv)"
    echo "Waiting 60 seconds to allow for replication of the identity..."
    sleep 60
    echo "Apply Reader role to the AKS managed cluster resource group for the newly provisioned identity"
    az role assignment create --assignee-object-id $principalId --assignee-principal-type ServicePrincipal --scope $mcResourceGroupId --role "acdd72a7-3385-48ef-bd42-f606fba81ae7" # Reader role
    echo "Set up federation with AKS OIDC issuer"
    AKS_OIDC_ISSUER="$(az aks show -n "$AKS_NAME" -g "$RESOURCE_GROUP" --query "oidcIssuerProfile.issuerUrl" -o tsv)"
    az identity federated-credential create --name "azure-alb-identity" \
        --identity-name "$IDENTITY_RESOURCE_NAME" \
        --resource-group $RESOURCE_GROUP \
        --issuer "$AKS_OIDC_ISSUER" \
        --subject "system:serviceaccount:azure-alb-system:alb-controller-sa"

    ALB Controller requires a federated credential with the name of azure-alb-identity. Any other federated credential name is unsupported.


    Assignment of the managed identity immediately after creation may result in an error that the principalId does not exist. Allow about a minute of time to elapse for the identity to replicate in Microsoft Entra ID prior to delegating the identity.

  2. Install ALB Controller using Helm

    For new deployments

    To install ALB Controller, use the helm install command.

    When the helm install command is run, it will deploy the helm chart to the default namespace. When alb-controller is deployed, it will deploy to the azure-alb-system namespace. Both of these namespaces may be overridden independently as desired. To override the namespace the helm chart is deployed to, you may specify the --namespace (or -n) parameter. To override the azure-alb-system namespace used by alb-controller, you may set the albController.namespace property during installation (--set albController.namespace). If neither the --namespace or --set albController.namespace parameters are defined, the default namespace will be used for the helm chart and the azure-alb-system namespace will be used for the ALB controller components. Lastly, if the namespace for the helm chart resource is not yet defined, ensure the --create-namespace parameter is also specified along with the --namespace or -n parameters.

    ALB Controller can be installed by running the following commands:

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME
    helm install alb-controller oci://mcr.microsoft.com/application-lb/charts/alb-controller \
         --namespace <helm-resource-namespace> \
         --version 1.0.0 \
         --set albController.namespace=<alb-controller-namespace> \
         --set albController.podIdentity.clientID=$(az identity show -g $RESOURCE_GROUP -n azure-alb-identity --query clientId -o tsv)

    For existing deployments

    ALB can be upgraded by running the following commands:


    During upgrade, please ensure you specify the --namespace or --set albController.namespace parameters if the namespaces were overridden in the previously installed installation. To determine the previous namespaces used, you may run the helm list command for the helm namespace and kubectl get pod -A -l app=alb-controller for the ALB controller.

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME
    helm upgrade alb-controller oci://mcr.microsoft.com/application-lb/charts/alb-controller \
        --namespace <helm-resource-namespace> \
        --version 1.0.0 \
        --set albController.namespace=<alb-controller-namespace> \
        --set albController.podIdentity.clientID=$(az identity show -g $RESOURCE_GROUP -n azure-alb-identity --query clientId -o tsv)

Verify the ALB Controller installation

  1. Verify the ALB Controller pods are ready:

    kubectl get pods -n azure-alb-system

    You should see the following:

    alb-controller-bootstrap-6648c5d5c-hrmpc 1/1 Running 0 4d6h
    alb-controller-6648c5d5c-sdd9t 1/1 Running 0 4d6h
    alb-controller-6648c5d5c-au234 1/1 Running 0 4d6h
  2. Verify GatewayClass azure-application-lb is installed on your cluster:

    kubectl get gatewayclass azure-alb-external -o yaml

    You should see that the GatewayClass has a condition that reads Valid GatewayClass . This indicates that a default GatewayClass has been set up and that any gateway resources that reference this GatewayClass is managed by ALB Controller automatically.

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

Next Steps

Now that you have successfully installed an ALB Controller on your cluster, you can provision the Application Gateway For Containers resources in Azure.

The next step is to link your ALB controller to Application Gateway for Containers. How you create this link depends on your deployment strategy.

There are two deployment strategies for management of Application Gateway for Containers:

  • Bring your own (BYO) deployment: In this deployment strategy, deployment and lifecycle of the Application Gateway for Containers resource, Association and Frontend resource is assumed via Azure portal, CLI, PowerShell, Terraform, etc. and referenced in configuration within Kubernetes.
  • Managed by ALB controller: In this deployment strategy, ALB Controller deployed in Kubernetes is responsible for the lifecycle of the Application Gateway for Containers resource and its sub resources. ALB Controller creates an Application Gateway for Containers resource when an ApplicationLoadBalancer custom resource is defined on the cluster. The service lifecycle is based on the lifecycle of the custom resource.

Uninstall Application Gateway for Containers and ALB Controller

If you wish to uninstall the ALB Controller, complete the following steps.

  1. Delete the Application Gateway for Containers, you can delete the Resource Group containing the Application Gateway for Containers resources:
az group delete --resource-group $RESOURCE_GROUP
  1. Uninstall ALB Controller and its resources from your cluster run the following commands:
helm uninstall alb-controller
kubectl delete ns azure-alb-system
kubectl delete gatewayclass azure-alb-external


If a different namespace was used for alb-controller installation, ensure you specify the -n parameter on the helm uninstall command to define the proper namespace to be used. For example: helm uninstall alb-controller -n unique-namespace