在 Azure Kubernetes 服务（AKS）上安装托管网关 API CRD（预览版）

Kubernetes Gateway API 是 Kubernetes 群集流量管理的规范。该规范增强了入口 API，该 API 缺少一种不依赖于特定提供商的统一方法来进行高级流量路由。

Azure Kubernetes 服务 (AKS) 的网关 API 托管安装会为 Kubernetes 网关 API 安装自定义资源定义（CRDs）。通过托管网关 API 安装，可以在 AKS 上完全受支持的模式下使用网关 API 功能。

先决条件

必须使用实现网关 API 的 AKS 加载项或扩展，例如 Istio 加载项。如果使用 Istio 加载项，则必须采用次要修订 asm-1-26 或更高版本，以确保与托管网关 API 安装兼容。若要部署此加载项，请参阅为 Azure Kubernetes 服务（AKS）部署基于 Istio 的服务网格加载项。
- 如果群集上已有网关 API CRD 安装，则必须满足以下要求：
  - 只能在 standard 群集上安装通道 CRD。 Experimental 不允许使用频道 CRD，必须在启用 Managed Gateway API 之前将其卸载。
  - 网关 API 捆绑包版本必须与群集的 Kubernetes 版本兼容。有关详细信息，请参阅网关 API 捆绑包版本的 Kubernetes 受支持版本部分。
aks-preview 扩展已安装并更新至版本 19.0.0b4 或更高版本。
ManagedGatewayAPIPreview注册到订阅的功能标志。

安装或更新 `aks-preview` 扩展

重要

AKS 预览功能可在自助服务和自愿选择的基础上启用。预览版按“现状”和“视供应情况”提供，它们不包括在服务级别协议和有限保证范围内。 AKS 预览功能是由客户支持尽最大努力部分覆盖。因此，这些功能并不适合用于生产。有关详细信息，请参阅以下支持文章：

使用aks-preview和az extension add命令安装az extension update扩展或更新到最新版本的扩展。如果使用 Azure CLI。必须使用 aks-preview 及更高版本 19.0.0b4。
```
# 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
```

注册托管网关 API 预览功能标志

使用 ManagedGatewayAPIPreview 命令注册 az feature register 功能标志。

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

网关 API 捆绑包版本支持的 Kubernetes 版本

下表概述了 standard 通道中每个网关 API 捆绑包版本的 AKS 群集所支持的 Kubernetes 版本：

网关 API 捆绑版本	支持的 Kubernetes 版本
v1.2.1	v1.26.0 - v1.33.x
v1.3.0	v1.34.0+

注释

如果在安装托管网关 API CRD 后将 AKS 群集升级到新的次要版本，则 CRD 会自动升级到该 Kubernetes 版本支持的新网关 API 捆绑包版本。例如，如果您从 AKS v1.33.0 升级到 v1.34.0，并且之前已为捆绑包版本 v1.2.1 安装了托管网关 API，那么 CRD 会自动升级到捆绑包版本 v1.3.0。

使用已安装的托管网关 API CRD 创建新的 AKS 群集

使用带有 az aks create 标志的 --enable-gateway-api 命令新建一个安装了托管网关 API CRD 的 AKS 群集。还可以在同一命令中启用受支持的加载项，例如 Istio 服务网格加载项。以下示例命令创建一个新的 AKS 群集，并安装托管网关 API 和启用 Istio 服务网格加载项：
```
az aks create --resource-group myResourceGroup --name myAKSCluster --enable-gateway-api --enable-azure-service-mesh
```

在现有 AKS 群集上安装托管网关 API CRD

在支持的实现已启用的现有集群上，通过 az aks update 命令和标志安装托管网关 API CRDs。
```
az aks update --resource-group myResourceGroup --name myAKSCluster --enable-gateway-api
```

验证托管网关 API CRD 安装

使用以下 kubectl get crds 命令查看群集上安装的 CRD：

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

输出应显示已安装的 CRD，这些 CRD 是 Kubernetes 网关 API 规范的一部分。例如：

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

使用以下命令验证 CRD 是否具有预期的注解，并且捆绑版本与您的集群的预期 kubectl get crds相匹配：
```
kubectl get crd gateways.gateway.networking.k8s.io -ojsonpath={.metadata.annotations} | jq
```
输出应显示预期的注释，包括 gateway.networking.k8s.io/bundle-version 注释，该注释应带有与你的群集 Kubernetes 版本相匹配的预期捆绑包版本。例如，如果群集正在运行 Kubernetes v1.33.0，则预期捆绑版本为 v1.2.1，输出应类似于以下内容：
```
{
"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"
}
```

卸载 AKS 群集上的托管网关 API CRD

使用带有 az aks update 标志的 --disable-gateway-api 命令在现有群集上卸载托管网关 API CRD。
```
az aks update --resource-group myResourceGroup --name myAKSCluster --disable-gateway-api
```

使用 Kubernetes Gateway API 为 Istio 服务网格插件配置 Ingress

Last updated on 2026-02-28

通过