Install Managed Gateway API CRDs (Preview)

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

The Kubernetes Gateway API is a specification for traffic management on Kubernetes clusters. It was designed as a successor and enhancement of the Ingress API, which lacked 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. With the Managed Gateway API installation, you can use Gateway API functionality in a fully supported mode on AKS. However, you must also use an AKS add-on or extension that implements the Gateway API, such as the Istio add-on.

Gateway API bundle version and AKS Kubernetes version mapping

The following table outlines the supported Kubernetes versions for your AKS cluster for each Gateway API bundle version for the standard channel. Experimental channel CRDs are disallowed and must be uninstalled before enabling the Managed Gateway API installation.

Gateway API Bundle Version Supported Kubernetes Versions
v1.2.1 v1.26.0 - v1.33.x
v1.3.0 v1.34.0+

Note

If you upgrade your AKS cluster to a new minor version after installing the Managed Gateway API CRDs, the CRDs will automatically be upgraded 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 are automatically upgraded to bundle version v1.3.0.

Prerequisites

Ensure that you have at least one of the following implementations of the Gateway API installed and enabled on your cluster:

  • Istio add-on minor revision asm-1-26 and later.

    • If you already have an existing installation of the Gateway API CRDs on your cluster, then you must only have standard channel CRDs installed, and the Gateway API bundle version must be compatible with your cluster's Kubernetes version. See the table for the bundle version associated with each Kubernetes version.

  • Install the aks-preview extension using the az extension add command if you're using Azure CLI. You must use aks-preview version 19.0.0b4 and later.

    az extension add --name aks-preview

    Update to the latest version of the extension using the az extension update command:

    az extension update --name aks-preview

Manage the Managed Gateway API preview feature

You can register the ManagedGatewayAPIPreview feature flag by using the az feature register command:

az feature register --namespace "Microsoft.ContainerService" --name "ManagedGatewayAPIPreview"

Then you can install or uninstall the Managed Gateway API CRDs.

  1. You can run the az aks create command to install the Managed Gateway API CRDs on a newly created cluster. You must also enable an implementation of the Gateway API to enable the managed CRD installation.

    # Example: enable the managed Gateway API installation with the Istio service mesh add-on
az aks create -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-gateway-api --enable-azure-service-mesh

  2. To install the Managed Gateway API CRDs on an existing cluster with a supported implementation enabled, run the following command:

    az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-gateway-api

  3. To view the CRDs installed on your cluster, run the following command:

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

    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

  4. Verify that the CRDs have the expected annotations and that the bundle version matches the expected Kubernetes version for your cluster.

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

    {
  "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"
}

Next Steps

  • Last updated on