Compartilhar via

安装托管网关 API 自定义资源定义 （CRD） - 预览版

重要

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

Kubernetes Gateway API 是 Kubernetes 群集流量管理的规范。 它被设计为对Ingress API的继任者和改进，因为Ingress API缺乏一种统一且提供商无关的高级流量路由方法。

适用于 Azure Kubernetes 服务的托管网关 API 安装（AKS）将 Kubernetes 网关 API 的自定义资源定义（CRD）安装到群集上。 通过托管网关 API 安装，可以在 AKS 上完全受支持的模式下使用网关 API 功能。 但是，还必须使用实现网关 API 的 AKS 加载项或扩展，例如 Istio 加载项。

要求和限制

  • 必须至少安装一个加载项，例如实现网关 API 的 Istio 加载项。 在启用托管网关安装之前或期间，必须先启用加载项。
  • 如果你的群集上现在已安装网关 API CRD，那么你只需要安装 standard 通道 CRD，并且网关 API 捆绑包版本必须与群集的 Kubernetes 版本兼容。 请参阅表，以了解与每个 Kubernetes 版本关联的捆绑版本。

网关 API 捆绑版本和 AKS Kubernetes 版本映射

下表针对 standard 通道的每个网关 API 捆绑包版本，你的 AKS 群集所支持的 Kubernetes 版本。 Experimental 通道 CRD 不被允许，必须在启用托管网关 API 的安装之前将其卸载。

网关 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 实现

确保群集上至少安装了以下网关 API 实现之一：

注册托管网关 API 预览功能

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

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

安装托管网关 API CRD

Azure 资源管理器 （ARM） 模板

可以通过部署 Azure 资源管理器 （ARM） 模板在群集上启用托管网关 API CRD。 使用 properties API 版本或更高版本将以下内容添加到规范下的 2025-06-02-preview AR 托管群集资源 JSON：

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

按照文档中的说明 部署模板。

验证安装

现在应该能看到您群集上已安装的自定义资源定义（CRD）：

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

验证 CRD 是否具有预期的批注，并且捆绑版本是否与群集 的预期 Kubernetes 版本 匹配。

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

卸载托管网关 API CRD

ARM 模板

使用以下规范部署 ARM 模板 以禁用托管网关 API CRD：

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

后续步骤