通过应用程序路由加载项配置 Kubernetes Gateway API 入口

注意

Kubernetes SIG Network和安全响应委员会宣布即将停用 Ingress NGINX项目，维护将于2026年3月结束。目前，使用 NGINX 的应用程序路由加载项的 AKS 群集无需立即执行任何操作。 Microsoft将为应用程序路由加载项的NGINX Ingress资源的重要安全补丁提供正式支持，支持截止至2026年11月。

AKS 正在迁移到网关 API，这将作为入口和 L7 流量管理的长期标准，以便与上游 Kubernetes 社区保持一致。建议根据当前设置开始规划迁移路径：

应用程序路由扩展用户：生产工作负荷在 2026 年 11 月之前仍受全面支持。迁移到应用程序路由网关 API 实现，以获得基于网关 API 的入口流量管理体验。
OSS NGINX 用户 有多个选项：
- 迁移到使用 NGINX 的应用程序路由加载项，在规划长期网关 API 迁移的同时，从官方支持（截至2026年11月）中受益。
- 迁移到应用程序路由网关 API 实现，以获得基于网关 API 的入口流量管理体验。
服务网格用户：如果计划采用服务网格，请考虑基于 Istio 的服务网格加载项。今天使用 Istio 入口，计划在正式发布为 GA 时迁移到 Istio 网关 API 支持。

应用程序路由加载项支持用于入口流量管理的 Kubernetes 网关 API。 Kubernetes 网关 API 是一组资源，为流量管理提供标准化、面向角色和可扩展的框架，旨在成为入口 API 的后续和演变。因此，应用程序路由网关 API 实现，旨在作为 managed NGINX 加载项的继任者，该加载项基于旧的 Ingress API，并将在 2026 年 11 月之后停止获得 Azure 支持。如果使用托管 NGINX，则必须在 2026 年 11 月前迁移到应用程序路由网关 API 实现或其他受支持的实现。

应用程序路由插件的 Kubernetes Gateway API 实现会部署 Istio 控制平面，以便管理 Kubernetes Gateway API 资源的基础设施。但是，与适用于 AKS 的 Istio 服务网格加载项相比，其不同之处在于：

功能	应用程序路由网关 API	Istio 服务网格加载项
网关类名称	`approuting-istio`	`istio`
Sidecar 注入和 Istio CRD 支持	不支持。仅管理 Kubernetes 网关 API 资源的基础设施	支持
修订和升级	未修订。针对次要更新和修补程序版本更新就地升级	已修订。通过金丝雀升级进行次要版本更新，而修补程序版本更新则是就地进行。

局限性

无法同时启用应用程序路由网关 API 实现和 Istio 服务网格加载项。必须先禁用一个，并在单独的操作中启用另一个。从 Istio 服务网格加载项过渡到应用程序路由网关 API 实现时，必须在禁用 Istio 加载项后删除 Istio GatewayClass 和 Istio CRD。 Istio 加载项会安装一些 CRD（例如 virtualservices.networking.istio.io、destinationrules.networking.istio.io，以及 networking.istio.io、security.istio.io、telemetry.istio.io 和 extensions.istio.io API 组中的 CRD），即使在禁用加载项时也不会被删除。如果这些 CRD 保留在群集上，则应用程序路由网关 API Istio 控制平面无法启动。运行以下命令将其删除：
```
kubectl delete crd $(kubectl get crd -o name | grep -E 'istio\.io')
kubectl delete gatewayclass istio
```

注释

如果有现有的 Istio 自定义资源（如 VirtualServices 或 DestinationRules），则删除 CRD 也会删除这些资源。在继续操作之前，请确保不再需要它们。

应用程序路由网关 API 实现使用与 Istio 插件相同的资源自定义允许列表来对资源的 ConfigMap 自定义进行验证。不在允许列表上的自定义项通过插件管理的 Webhook 阻止。
目前不支持通过 TLSRoute 资源配置对 HTTPS 服务的 HTTPS Ingress 访问（即服务器名称指示 (SNI) 透传）。一旦 AKS 添加对 Istio 1.30 的支持，就将支持该 TLSRoute 资源；届时，应用程序路由的 Istio 控制平面将自动升级到该版本。
不支持通过应用程序路由网关 API 实现进行出口流量管理。
将非由 Azure 托管的边车容器（例如自定义遥测、日志记录或安全代理）注入到由应用程序路由加载项管理的 Istio 网关代理 Pod 中，未获官方支持。如果你选择将自定义 sidecar 容器注入受管代理 Pod，Microsoft 对于你遇到的任何问题仅提供尽力而为的支持。
默认情况下，Gateway 代理 Pod 已启用 Envoy 访问日志，但无法通过 Istio Telemetry API 自定义日志格式、记录范围和提供程序。若要进行自定义，请改用 Istio 服务网格附加组件上的 Gateway API Ingress。

先决条件

更新 Azure CLI 版本

必须使用 azure-cli 版本 2.86.0 或更高版本。运行 az --version 以查找版本 azure-cli ，然后运行 az upgrade 以升级。

启用托管式网关 API CRD

启用受控网关 API 安装。不支持将自托管网关 API CRD 用于应用程序路由加载项。

启用应用程序路由网关 API 实现

设置环境变量。

export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

在创建群集期间启用

运行以下命令，在创建群集期间启用应用程序路由网关 API 实现：

az aks create --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

为现有群集启用

运行以下命令，为现有群集启用应用程序路由网关 API 实现：

az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

应在istiod命名空间中看到aks-istio-systemPod：

kubectl get pods -n aks-istio-system

NAME                      READY   STATUS    RESTARTS   AGE
istiod-54b4ff45cf-htph8   1/1     Running   0          3m15s
istiod-54b4ff45cf-wlvgd   1/1     Running   0          3m

还应看到 ValidatingWebhookConfiguration 已部署：

kubectl get validatingwebhookconfiguration

NAME                                        WEBHOOKS   AGE
aks-node-validating-webhook                 1          117m
azure-service-mesh-ccp-validating-webhook   1          4m2s

如果已启用托管网关 API 安装，还应看到 Istio 网关自定义 ConfigMap 已创建：

kubectl get cm -n aks-istio-system

NAME                                  DATA   AGE
...
istio-gateway-class-defaults          2      43s
...

使用 Kubernetes 网关配置入口

部署示例应用程序

首先，在httpbin命名空间中部署default示例应用。

export ISTIO_RELEASE="release-1.27"
kubectl apply -f https://raw.githubusercontent.com/istio/istio/$ISTIO_RELEASE/samples/httpbin/httpbin.yaml

创建 Kubernetes 网关和 HTTPRoute

接下来，在 default 命名空间中部署网关 API 配置，并将其 gatewayClassName 设置为 approuting-istio.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpbin-gateway
spec:
  gatewayClassName: approuting-istio
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
spec:
  parentRefs:
  - name: httpbin-gateway
  hostnames: ["httpbin.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
EOF

注释

上面的示例创建可从群集外部访问的外部入口负载均衡器服务。可以添加批注以创建内部负载均衡器并自定义其他负载均衡器设置。

注释

默认情况下，Istio 控制平面会将GatewayClass的名称追加到它为approuting-istio预配的资源名称中。可以使用 Gateway 批注你的资源 gateway.istio.io/name-override，以覆盖预配资源的名称。资源名称必须小于 63 字符，并且必须是有效的 DNS 名称。

验证是否为 Deployment 创建了 Service、HorizontalPodAutoscaler、PodDisruptionBudget 和 httpbin-gateway。

kubectl get deployment httpbin-gateway-approuting-istio

NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
httpbin-gateway-approuting-istio   2/2     2            2           6m41s

kubectl get service httpbin-gateway-approuting-istio

NAME                               TYPE           CLUSTER-IP   EXTERNAL-IP      PORT(S)                        AGE
httpbin-gateway-approuting-istio   LoadBalancer   10.0.54.96   <external-ip>    15021:30580/TCP,80:32693/TCP   7m13s

kubectl get hpa httpbin-gateway-approuting-istio

NAME                               REFERENCE                                     TARGETS       MINPODS   MAXPODS   REPLICAS   AGE
httpbin-gateway-approuting-istio   Deployment/httpbin-gateway-approuting-istio   cpu: 3%/80%   2         5         2          8m13s

kubectl get pdb httpbin-gateway-approuting-istio

NAME                               MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
httpbin-gateway-approuting-istio   1               N/A               1                     9m1s

将请求发送到示例应用程序

最后，尝试向 curl 应用程序发送 httpbin 请求。首先，设置 INGRESS_HOST 环境变量：

kubectl wait --for=condition=programmed gateways.gateway.networking.k8s.io httpbin-gateway
export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io httpbin-gateway -ojsonpath='{.status.addresses[0].value}')

然后，尝试将 HTTP 请求发送到 httpbin：

curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"

应会看到响应 HTTP 200 。

注释

若要使用应用程序路由 Gateway API 实现来保护入口流量，并集成 Azure DNS 以管理主机名，请参阅使用应用程序路由 Gateway API 实现配置 Azure DNS 和 TLS，了解由应用程序路由操作器提供支持的自动化工作流。有关不依赖于操作员集成的手动 TLS 终止工作流，请参阅使用应用程序路由网关 API 实现保护入口流量。

访问日志

应用程序路由的 Gateway API 实现默认在所有受管的 Gateway 代理 Pod 上启用 Envoy 访问日志。访问日志以默认 Envoy 文本格式写入代理容器的标准输出。可以使用以下命令查看日志 kubectl logs：

kubectl logs deployment/<your-gateway-name>-approuting-istio

网关处理的每个请求都会生成一个日志行，其中包含 HTTP 方法、路径、响应代码、上游服务和请求和响应大小等详细信息。通过此详细信息，可以更轻松地观察入口流量并排查路由问题，而无需任何其他配置。

版本控制与升级

应用路由网关 API 的实现会根据 AKS 集群的 Kubernetes 版本来部署和升级 Istio 控制平面，涵盖次要版本和修补版本的升级。

Istio 版本是与群集的 AKS 版本兼容的受支持的最大 Istio 次要版本。例如，如果你使用的是 AKS 版本 1.34，则安装的最大受支持的 Istio 次要版本（截至 2026 年 3 月）为 1.28。请记住，给定 Kubernetes 版本支持的最大 Istio 版本在 Long-Term 支持（LTS）群集和非 LTS 群集之间可能有所不同。

若要查找 AKS Kubernetes 版本支持的最大 Istio 次要版本，可以检查服务网格加载项发布日历。虽然应用程序路由网关 API 实现未修订，但 Istio 控制平面次要版本对应于给定的服务网格加载项修订版（例如：对于服务网格加载项 asm-1-28，应用程序路由 Istio 控制平面次要版本将是 1.28）。还可以通过检查部署映像中的istiod补丁版本来查看 Istio 次要版本：kubectl get deployment istiod -n aks-istio-system -o=jsonpath="{.spec.template.spec.containers[*].image}"

升级

Istio 控制平面针对应用程序路由网关 API 实现的补丁版本和次要版本升级是在就地进行的。作为 AKS 版本的一部分，Istio 控制平面的修补程序版本升级会自动触发。次要版本升级可以自动或手动触发，具体取决于 Istio 次要版本版本的 AKS Kubernetes 版本和时间。次要版本升级发生在以下两种方案中：

AKS 群集已升级至新版本，该版本将 Istio 的最大支持版本固定为更高版本。作为 AKS 群集升级的一部分，Istio 控制平面将升级到更高次要版本。
AKS 发布了新的 Istio 版本，现在是 AKS 群集版本支持的最大 Istio 版本。在发布到你的区域后，群集上的 Istio 控制平面将自动升级到新的次要版本。按照 AKS 发行说明和 AKS 发布跟踪器跟踪新的 Istio 版本版本，并查看新版本何时推出到你的区域。

升级过程中可能会发生流量中断。为了最大程度地减少升级期间的中断，应用程序路由加载项将部署一个水平 Pod 自动缩放程序（HPA），其中包含 2 个最小副本和一个 PodDisruptionBudget （PDB），每个 Gateway副本的最小可用性为 1。可以自定义这些资源以修改这些设置。

资源自定义

控制台 Pod 水平自动缩放（HPA）自定义设置

应用程序路由网关 API 实现支持自定义 Istio 控制平面水平 Pod 自动缩放程序 (HPA)。 istiod HPA 资源具有以下默认配置：

最小副本数：2
副本数上限：5
CPU 使用率：80%

注释

为防止与 PodDisruptionBudget 冲突，应用程序路由网关 API 的实现不允许将 minReplicas 设置为低于初始默认值 2。

HPA 配置可以通过修补程序和直接编辑进行修改。例：

kubectl patch hpa istiod -n aks-istio-system --type merge --patch '{"spec": {"minReplicas": 3, "maxReplicas": 6}}'

网关资源自定义

应用程序路由网关 API 实现支持通过注释和 ConfigMap 自定义 Gateway 资源。应用程序路由使用与用于网关 API 资源自定义的 Istio 服务网格加载项相同的资源自定义允许列表。按照 Istio 加载项网关 API 文档中的步骤配置为 Gateways 生成的资源，并查看哪些字段位于允许列表中。

注释

当托管网关 API CRD 和应用程序路由网关 API 实现被同时启用时，AKS 会预配和协调istio-gateway-class-defaults ConfigMap。如果您以前在istio-gateway-class-defaults命名空间中自行创建了aks-istio-system ConfigMap，则必须在启用托管网关 API CRD 之前删除该自管理的 ConfigMap 实例，以避免与 AKS 托管的 ConfigMap 在对帐时产生冲突。

注释

应用程序路由 Gateway API 实现会将Azure 负载均衡器注解添加到Gateway Service，以便为默认值为“Cluster”的externalTrafficPolicy设置配置运行状况探测。如果将spec.externalTrafficPolicy设置为“Local”，则必须在 GatewayClass 级别的 ConfigMap 或每个 Gateway 的 ConfigMap 中取消设置以下注解：

 service: |
    spec:
       externalTrafficPolicy: Local
    metadata:
      annotations:
        service.beta.kubernetes.io/port_80_health-probe_port:
        service.beta.kubernetes.io/port_80_health-probe_protocol:
        service.beta.kubernetes.io/port_80_health-probe_request-path:

禁用应用程序路由网关 API 实现

运行以下命令以禁用应用程序路由网关 API 实现：

az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --disable-app-routing-istio

清理资源

运行以下命令以删除 Gateway 和 HttpRoute：

kubectl delete gateways.gateway.networking.k8s.io httpbin-gateway
kubectl delete httproute httpbin

如果您创建了用于定制Gateway的ConfigMap，请运行以下命令删除该ConfigMap：

kubectl delete configmap gw-options

如果创建了用于 TLS 终止的 SecretProviderClass 和机密，请删除以下资源：

kubectl delete secret httpbin-credential
kubectl delete pod secrets-store-sync-httpbin
kubectl delete secretproviderclass httpbin-credential-spc

后续步骤

使用应用程序路由 Gateway API 实现配置 Azure DNS 和 TLS

使用应用程序路由网关 API 实现保护入口流量（手动配置）

Last updated on 2026-07-02