Install Managed Gateway API Custom Resource Definitions (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 onto your cluster. 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.

Requirements and limitations

  • You must have at least one add-on installed, such as the Istio add-on, that implements the Gateway API. The add-on must be enabled before, or during enablement of the Managed Gateway Installation.
  • 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.

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 will automatically be upgraded to bundle version v1.3.0.

Prerequisites

Install supported Gateway API implementation

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

Register the Managed Gateway API preview feature

Register the ManagedGatewayAPIPreview feature flag by using the az feature register command:

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

Install the Managed Gateway API CRDs

Azure Resource Manager (ARM) Template

You can enable the Managed Gateway API CRDs on your cluster by deploying an Azure Resource Manager (ARM) Template. Add the following to an AR the Managed Cluster resource JSON under the properties spec, using the 2025-06-02-preview API version or higher:

"resources": [
  {
    "type": "Microsoft.ContainerService/managedClusters",
    "apiVersion": "2025-06-02-preview",
    "name": "[parameters('clusterName')]",
    "location": "[parameters('location')]",
    "properties": {
      "ingressProfile": {
        "gatewayAPI": {
          "installation": "Standard"
        }
      }
    }
  }
],

Follow the instructions in the documentation to deploy the template.

Verify Installation

You should now see the CRDs installed on your cluster:

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

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

Uninstall the Managed Gateway API CRDs

ARM Template

Deploy an ARM template with the following spec to disable the Managed Gateway API CRDs:

"resources": [
  {
    "type": "Microsoft.ContainerService/managedClusters",
    "apiVersion": "2025-06-02-preview",
    "name": "[parameters('clusterName')]",
    "location": "[parameters('location')]",
    "properties": {
      "ingressProfile": {
        "gatewayAPI": {
          "installation": "Disabled"
        }
      }
    }
  }
],

Next Steps