Edit

Install Managed Gateway API CRDs on Azure Kubernetes Service (AKS)

The Kubernetes Gateway API is a specification for traffic management on Kubernetes clusters. The specification enhances Ingress API, which lacks a unified and provider-agnostic approach for advanced traffic routing.

The Managed Gateway API Installation for Azure Kubernetes Service (AKS) installs the Custom Resource Definitions (CRDs) for the Kubernetes Gateway API. You can install these CRDs independently of any specific Gateway API implementation.

Note

The Managed Gateway API installation only installs and manages the Gateway API CRDs. You can use these CRDs with your own Gateway API implementation, but AKS support only applies when you use the Managed Gateway API installation with a supported AKS add-on or extension that implements the Gateway API. BYO proxies or other self-managed Gateway API implementations aren't supported by AKS.

Prerequisites

  • If you already have an existing installation of the Gateway API CRDs on your cluster, you must meet the following requirements:

    • Only standard channel CRDs can be installed on your cluster. Experimental channel CRDs are disallowed, and you must uninstall them before enabling the Managed Gateway API.
    • The Gateway API bundle version must be compatible with your cluster's Kubernetes version. For more information, see the Supported Kubernetes versions for Gateway API bundle versions section.

  • Optionally, you could deploy an AKS add-on or extension that implements the Gateway API, such as the Istio add-on. If you use the Istio add-on, you must be on minor revision asm-1-26 or later to ensure compatibility with the Managed Gateway API installation. To deploy the Istio add-on, see Deploy Istio-based service mesh add-on for Azure Kubernetes Service (AKS).

Update Azure CLI version

You must use azure-cli version 2.86.0 or higher. Run az --version to find your azure-cli version, and run az upgrade to upgrade.

Supported Kubernetes versions for Gateway API bundle versions

The following table outlines the supported Kubernetes versions for your AKS cluster for each Gateway API bundle version for the standard channel:

Gateway API bundle version Supported Kubernetes versions
v1.2.1 v1.26.0 - v1.33.x
v1.3.0 v1.34.x
v1.4.1 v1.35.0+

Note

If you upgrade your AKS cluster to a new minor version after installing the Managed Gateway API CRDs, the CRDs automatically upgrade to the new supported Gateway API bundle version for that Kubernetes version. For instance, if you upgrade from AKS v1.33.0 to v1.34.0 and previously had the Managed Gateway API installed for bundle version v1.2.1, the CRDs automatically upgrade to bundle version v1.3.0.

Create a new AKS cluster with Managed Gateway API CRDs installed

  • Create a new AKS cluster with Managed Gateway API CRDs installed using the az aks create command with the --enable-gateway-api flag. You can also optionally enable a supported add-on, such as the Istio service mesh add-on, in the same command. The following example command creates a new AKS cluster with the Managed Gateway API installation and the Istio service mesh add-on enabled:

    az aks create --resource-group myResourceGroup --name myAKSCluster --enable-gateway-api --enable-azure-service-mesh

Install Managed Gateway API CRDs on an existing AKS cluster

  • Install Managed Gateway API CRDs on an existing cluster using the az aks update command with the --enable-gateway-api flag.

    az aks update --resource-group myResourceGroup --name myAKSCluster --enable-gateway-api

Verify Managed Gateway API CRD installation

  1. View the CRDs installed on your cluster using the following kubectl get crds command:

    kubectl get crds | grep "gateway.networking.k8s.io"

    The output should show the installed CRDs, which are part of the Kubernetes Gateway API specification. For example:

    gatewayclasses.gateway.networking.k8s.io                           2025-08-29T17:52:36Z
gateways.gateway.networking.k8s.io                                 2025-08-29T17:52:36Z
grpcroutes.gateway.networking.k8s.io                               2025-08-29T17:52:36Z
httproutes.gateway.networking.k8s.io                               2025-08-29T17:52:37Z
referencegrants.gateway.networking.k8s.io                          2025-08-29T17:52:37Z

  2. Verify the CRDs have the expected annotations and the bundle version matches the expected Kubernetes version for your cluster using the following kubectl get crds command:

    kubectl get crd gateways.gateway.networking.k8s.io -ojsonpath={.metadata.annotations} | jq

    The output should show the expected annotations, including the gateway.networking.k8s.io/bundle-version annotation with the expected bundle version for your cluster's Kubernetes version. For example, if your cluster is running Kubernetes v1.33.0, the expected bundle version is v1.2.1, and the output should be similar to the following:

    {
"api-approved.kubernetes.io": "https://github.com/kubernetes-sigs/gateway-api/pull/3328",
"app.kubernetes.io/managed-by": "aks",
"app.kubernetes.io/part-of": <hash>,
"gateway.networking.k8s.io/bundle-version": "v1.2.1",
"gateway.networking.k8s.io/channel": "standard"
}

Uninstall Managed Gateway API CRDs on an AKS cluster

  • Uninstall Managed Gateway API CRDs on an existing cluster using the az aks update command with the --disable-gateway-api flag.

    az aks update --resource-group myResourceGroup --name myAKSCluster --disable-gateway-api

Related content

  • Last updated on