Istio 1.31.0：从 Gateway API 诊断到 Ambient Waypoint 灰度的关键变化

Istio 1.31.0 的变化集中在几个运维痛点：旧版 Gateway API CRD 不再悄悄影响流量处理，ambient 模式的 XDS 推送范围更精准，waypoint 支持按权重进行金丝雀发布，同时补齐了多集群、CNI、TLS、负载均衡和安全配置中的一批边界问题。升级时，不能只替换控制面镜像，还应同步检查 CRD、节点 nftables、远程集群凭据和已有实验性配置。

升级后先解决“看不见”的配置问题

Gateway API CRD 版本低于当前 Istio 所需最低版本时，istiod 现在会以 warn 级别记录明确告警，并说明相关资源在 CRD 升级前不会被处理。这个调整直接针对一种很难排查的故障：Istio 升级后 TLS passthrough 突然失效，但 Gateway、Route 看起来都存在。

istioctl analyze 也新增了 IST0176，可以在部署后尽早发现过期 CRD。升级流程中可以这样执行：

# 检查 Gateway API CRD、Gateway、Route 和 Istio 配置
istioctl analyze --all-namespaces

# 生成清单到文件，便于审计和自动化流水线使用
istioctl manifest generate \
  -f istio-1.31-values.yaml \
  -o istio-1.31-rendered.yaml

# 确认远程集群及其 revision 信息
istioctl remote-clusters

1.31.0 还修复了多个 Gateway API 相关问题，包括 BackendTLSPolicy 冲突解析、ListenerSet 状态清理、无效 parametersRef 或证书引用的状态报告，以及 HTTPS listener 的证书交付。使用 Gateway API 的集群应把资源状态条件纳入升级验收，而不只检查 Deployment 是否为 Available。

Ambient 模式的推送与 Waypoint 灰度

在 ambient 模式下，Service 或 workload 地址发生变化时，istiod 以前可能向所有 waypoint 和 proxy 推送 XDS。1.31.0 默认把推送范围限制到受影响的 waypoint，有助于降低大型 mesh 中的控制面 CPU 使用和推送延迟。需要兼容旧行为时，可以设置：

# istiod Helm values 的示例片段
pilot:
  env:
    AMBIENT_SCOPED_ADDRESS_PUSHES: "false"

这个开关适合临时回退或问题定位，不建议在没有明确原因时长期关闭。与之相关的另一个变化是 ztunnel 重连不再必然触发完整 WDS 推送：istiod 会为 WDS 资源分配基于内容的版本，客户端报告已有版本后，只重新发送断线期间发生变化的资源。

Waypoint 现在可以配置主实例和 canary 实例，并按权重把服务的 mesh 内连接导向 canary。下面是一个可改造的标签和注解示例，假设主 waypoint 名为 waypoint-primary，canary 位于 canary-system 命名空间：

apiVersion: v1
kind: Service
metadata:
  name: payments
  namespace: shop
  labels:
    istio.io/use-waypoint: waypoint-primary
    istio.io/use-waypoint-canary: waypoint-canary
    istio.io/use-waypoint-canary-namespace: canary-system
  annotations:
    istio.io/use-waypoint-canary-weight: "10"
spec:
  selector:
    app: payments
  ports:
    - name: http
      port: 8080
      targetPort: 8080

实际部署时应确认 canary waypoint 已就绪，并通过指标观察连接分布、错误率和延迟。权重灰度影响的是连接转发路径，不要求客户端修改配置；若还要让 ingress 请求使用 waypoint，需要结合 istio.io/ingress-use-waypoint 的配置进行验证。

流量策略更细，默认行为也更明确

1.31.0 增加了几项可以改变流量行为的 API：

• RetryBudget.budget_interval 可以定义计算 retry budget 时的请求时间窗口。默认 0ms 保持原行为，即只考虑当前 in-flight 请求。
• MeshConfig.defaultTrafficPolicy 可以为出站集群提供 mesh 级别的 connectionPool 和 outlierDetection 基线。DestinationRule 明确设置的块会覆盖基线，未设置的块则继承基线。
• zoneAwareLbSetting 支持 Envoy 的 zone-aware 负载均衡。它只支持 sidecar 模式，不支持 ambient；启用前还需要打开 proxy self-discovery。
• 默认会发送 unhealthy endpoints，除非配置了 OutlierDetection.minHealthPercent。也可以通过 PILOT_AUTO_SEND_UNHEALTHY_ENDPOINTS=false 恢复关闭行为。
• ALLOW_ANY_DYNAMIC_DNS 允许 sidecar 对未知目的地的明文 HTTP 使用 Envoy Dynamic Forward Proxy，在请求到达时根据 Host 解析域名；TLS 和原始 TCP 仍使用 PassthroughCluster。

zone-aware 负载均衡可以这样配置。示例中的 self-discovery 是必需前提，且这段配置不适用于 ambient：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  name: istio-control-plane
spec:
  meshConfig:
    defaultConfig:
      proxyMetadata:
        ISTIO_META_ENABLE_SELF_DISCOVERY: "true"
    defaultTrafficPolicy:
      connectionPool:
        http:
          http2MaxRequests: 1000
    outboundTrafficPolicy:
      mode: ALLOW_ANY_DYNAMIC_DNS
    # 仅在确认 Istio 版本支持并完成验证后启用
    # zoneAwareLbSetting:
    #   enabled: true

如果使用 zoneAwareLbSetting.enabled: false，1.31.0 会显式生成 routing_enabled: 0%，避免 Envoy 在存在 self-discovery local cluster 时自行启用 zone-aware 路由。对于渐进式迁移，这个语义差异尤其重要。

安全、CNI 与可观测性变化

安全方面，1.31.0 支持在 AuthorizationPolicy 的 Source 中按 peer 证书的 trust domain 匹配或排除请求；新增 fips-140-3 合规策略，并要求 Go 组件使用 Go 1.24 及以上的原生 FIPS 140-3 模块。不能把旧的 GOEXPERIMENT=boringcrypto 配置直接沿用到这个模式，因为它针对 FIPS 140-2。

XDS API generator 现在要求经过验证的控制面身份。此前只要能访问 istiod 的 XDS 端口，就可能读取跨命名空间的 Istio 配置。兼容旧客户端时可以设置 ENABLE_XDS_API_GENERATOR_AUTH=false，但这应被视为过渡措施，并配合网络访问控制使用。

CNI 方面，启动时会检查节点上的 nft 是否支持 JSON 输出；不支持时自动回退到 iptables，避免 pod 删除阶段持续报错和无限重试。Istio distroless 镜像也升级了内置 nftables 版本，节点操作系统仍应安装发行版提供的最新修复版本。1.31.0 同时修复了 ambient CNI 的并发 map 写入、网络命名空间误配、hostNetwork pod 错误纳入，以及 probe ipset 在节点重启后丢失等问题。

可观测性方面，可以为一个 pod 声明多个应用指标端点：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
  namespace: shop
spec:
  selector:
    matchLabels:
      app: checkout
  template:
    metadata:
      labels:
        app: checkout
      annotations:
        prometheus.istio.io/scrape-targets: "9090:/metrics,9100:/custom-metrics"
    spec:
      containers:
        - name: checkout
          image: example/checkout:1.0
          ports:
            - containerPort: 8080
            - containerPort: 9090
            - containerPort: 9100

多目标响应会按声明顺序合并，每个目标有 10 MiB 的响应上限；单个目标失败不会阻塞其他目标，但会增加 istio_agent_scrape_failures_total{type="application"}。如果不希望 pilot-agent 把 Envoy 指标合并到自身端点，可设置 PILOT_AGENT_MERGE_ENVOY_STATS=false。需要加密抓取时，则可以评估 ENVOY_SECURE_METRICS_PORT 和 ENVOY_SECURE_MERGED_METRICS_PORT。

一份实际的升级检查清单

• 升级 Gateway API CRD，并运行 istioctl analyze --all-namespaces，重点查看 IST0176。
• 检查 BackendTLSPolicy、XBackendTrafficPolicy、ListenerSet 的 status conditions 和证书引用。
• 在 ambient 集群中观察 istiod CPU、XDS 推送数量、ztunnel 重连后的 WDS 行为。
• 若启用 waypoint canary，先用低权重验证连接分布，再逐步增加权重。
• 评估 defaultTrafficPolicy、unhealthy endpoint 默认行为和 retry budget 变化对现有流量的影响。
• 使用 zone-aware 负载均衡前确认 sidecar、节点可用区标签和 ISTIO_META_ENABLE_SELF_DISCOVERY 均已准备好。
• 检查节点 nftables JSON 支持、远程集群凭据轮换、CNI agent 重启恢复和跨网络流量。
• 重新审计 FIPS、XDS generator 鉴权、Gateway 合并策略以及外部 SDS 配置。

Istio 1.31.0 的价值不只在新增字段，更在于把许多原本依赖隐式行为的场景变得可诊断、可配置、可渐进发布。生产升级应把控制面日志、资源 status、代理指标和跨网络流量测试放在同一套验收流程中。