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

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. With the Managed Gateway API installation, you can use Gateway API functionality in a fully supported mode on AKS.

Prerequisites

You must use an AKS add-on or extension that implements the Gateway API, such as the Istio add-on. If using 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 this add-on, see Deploy Istio-based service mesh add-on for Azure Kubernetes Service (AKS).
- 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.
The aks-preview extension installed and updated to version 19.0.0b4 or later.
The ManagedGatewayAPIPreview feature flag registered to your subscription.

Install or update the `aks-preview` extension

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:

Install the aks-preview extension or update to the latest version of the extension using the az extension add and az extension update commands. if you're using Azure CLI. You must use aks-preview version 19.0.0b4 and later.
```
# Install the aks-preview extension
az extension add --name aks-preview

# Update the aks-preview extension to the latest version
az extension update --name aks-preview
```

Register the Managed Gateway API preview feature flag

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

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.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 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 with a supported implementation enabled 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

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

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

Configure ingress for Istio service mesh add-on with the Kubernetes Gateway API

Feedback

Was this page helpful?

Last updated on 2026-02-13