了解 Cloud Service Mesh 兼容性

ISTIOD 控制平面实现已弃用，您必须在支持结束期限之前评估兼容性、解决整个舰队中的阻塞情况并进行现代化改造。

本指南详细介绍了如何评估舰队是否适合进行控制平面现代化改造，方法是确认其配置、基础架构和规模是否与 TRAFFIC_DIRECTOR 控制平面实现兼容。

选择启用或停用兼容性检查

如需启动兼容性检查，请为舰队启用验证模式，这会触发对所有 Istio 配置、基础架构配置和规模参数的持续审核。启用这些检查不会对您的舰队或集群进行任何更改；只会启用兼容性报告。

启用检查

如需开始进行兼容性审核，请运行以下 gcloud 命令：

gcloud alpha container fleet mesh update --modernization-compatibility validation-enabled --project FLEET_PROJECT_ID

将 FLEET_PROJECT_ID 替换为您的舰队宿主项目的 ID。 通常，FLEET_PROJECT_ID 与项目的名称相同。

启用后，Cloud Service Mesh 会开始评估舰队和舰队中所有已配置 Cloud Service Mesh 的集群的现代化兼容性。

停用检查

如需停止报告兼容性结果，请运行以下命令：

gcloud alpha container fleet mesh update --modernization-compatibility validation-disabled --project FLEET_PROJECT_ID

此命令会从成员资格状态中移除现代化兼容性条件，并从各个 Istio CR 中移除 ModernizationCompatible 状态。

了解兼容性

现代化改造兼容性是通过舰队级和成员（集群）级条件报告的。系统会在不同时间执行各种检查，所有检查每天至少运行一次。启用检查或应用修复后，状态最多可能需要一天时间才能更新。

如需查看这些结果，请使用以下命令检索最新的网格状态：

gcloud container fleet mesh describe --project FLEET_PROJECT_ID

舰队级兼容性

在 state.servicemesh.conditions 下查看舰队的总体现代化改造状态。

  • 舰队兼容：如果您的舰队兼容，您会看到代码为 MODERNIZATION_COMPATIBLE 的条件：

    name: projects/project_id/locations/global/features/servicemesh
state:
  servicemesh:
    conditions:
    - code: MODERNIZATION_COMPATIBLE
      details: 'Fleet is eligible for modernization.'
      documentationLink: https://cloud.google.com/service-mesh/...
      severity: INFO

  • 舰队不兼容：如果您的舰队尚不兼容现代化改造，您会看到代码为 MODERNIZATION_INCOMPATIBLE 的条件：

    name: projects/project_id/locations/global/features/servicemesh
state:
  servicemesh:
    conditions:
    - code: MODERNIZATION_INCOMPATIBLE
      details: 'Fleet is not yet eligible for modernization.'
      documentationLink: https://cloud.google.com/service-mesh/...
      severity: INFO

    如果您的车队不兼容，请查看特定差距的条件。 检查是否存在其他 WARNING 或 ERROR 严重程度的舰队级条件以及 membershipStates.servicemesh 下的集群级条件，以解决任何阻碍因素。

集群级兼容性

在舰队中每个已配置 Cloud Service Mesh 的集群的 membershipStates.servicemesh 下，查找严重程度为 WARNING 或 ERROR 的状况。如果存在不兼容问题，则输出类似于以下内容：

membershipSpecs:
 projects/project_id/locations/global/memberships/cluster-a:
   mesh:
     management:MANAGEMENT_AUTOMATIC
membershipStates:
  projects/project_id/locations/global/memberships/cluster-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION
       details: 'Pod pod-a in namespace test-namespace: invalid annotations: ["status.sidecar.istio.io/port": failed to parse port - "invalid", port must be a number and should be in the range 1..65535]; unsupported annotations: ["ambient.istio.io/redirection"] .'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING
     - code: WORKLOAD_IDENTITY_REQUIRED
       details: 'Workload Identity is not enabled for the cluster or at least one of the node pools.'
       documentationLink: https://cloud.google.com/...
       severity: ERROR
...

按照每种情况中提供的 documentationLink 了解并解决具体的不兼容问题。

解决兼容性问题

解决不兼容的 pod 注释

MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION 代码表示集群无法升级到 TRAFFIC_DIRECTOR 控制平面，因为某些 Pod 具有不受支持或无效的 Istio 注释。

gcloud container fleet mesh describe 命令的示例输出，其中为会员资格设置了条件 MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION：

membershipStates:
  projects/project_id/locations/global/memberships/membership-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION
       details: 'Pod pod-a in namespace test-namespace: invalid annotations: ["status.sidecar.istio.io/port": failed to parse port - "invalid", port must be a number and should be in the range 1..65535]; unsupported annotations: ["ambient.istio.io/redirection"] .'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING

如需解决这些 pod 注释问题，请执行以下操作：

  1. 识别有问题的注解：检查状态条件的 details 字段，找到不受支持或无效的注解键。查找具有问题注解键的所有 Pod。

  2. 修正并验证：

    1. 修改 Deployment 或 Pod 的 YAML 规范，确保它们仅使用受支持的注释（所有其他注释均不受支持）。移除所有不受支持的注释，更正所有无效值，然后将更新后的 YAML 重新应用于集群。
    2. 更正所有 Pod 注释后，相应会员资格将不再显示 MODERNIZATION_INCOMPATIBLE_POD_ANNOTATION 条件。

解决不兼容的配置

MODERNIZATION_INCOMPATIBLE_CONFIG 代码表示由于配置不兼容，集群无法现代化为 TRAFFIC_DIRECTOR 控制平面。这些不兼容问题可能源于：

  • 使用不受支持的功能或字段或包含无效值的特定 Istio 自定义资源 (CR)。
  • Istio MeshConfig 设置无效或不受支持。
  • 超出可伸缩性限制。
  • 使用不受支持的服务或命名空间注释。

gcloud container fleet mesh describe 命令的示例输出，其中为会员资格设置了条件 MODERNIZATION_INCOMPATIBLE_CONFIG：

membershipSpecs:
 projects/project_id/locations/global/memberships/membership-a:
   mesh:
     management:MANAGEMENT_AUTOMATIC
membershipStates:
  projects/project_id/locations/global/memberships/membership-a:
    servicemesh:
      conditions:
     - code: MODERNIZATION_INCOMPATIBLE_CONFIG
       details: 'One or more configs have warnings. Due to the following reason(s): Istio sidecar scale exceeds limit, MeshConfig "accessLogFile" is unsupported. Invalid Config Types: [Gateway, ServiceEntry], where more details are shown on individual config resources.See documentation link for more detail.'
       documentationLink: https://cloud.google.com/service-mesh/...
       severity: WARNING

如需解决这些配置问题，请执行以下操作：

  1. 分析条件详情：检查状态条件的 details 字段。它会汇总各个错误，并找出存在配置问题的资源类型。对于所提供的详细信息示例，您需要解决规模和 MeshConfig 问题，并检查 Gateway 和 ServiceEntry 资源是否存在错误。

  2. 识别并调查不兼容的资源：使用以下示例脚本列出未通过兼容性检查的 Istio 自定义资源 (CR)。此脚本仅作为示例提供；在集群中运行之前，请先检查并分析该脚本，确保其符合您的环境和运营要求。该脚本需要安装 kubectl 和 jq。输出内容包括每项资源在 status.conditions 下找到的具体错误详情（类型：ModernizationCompatible，状态："False"）。

    for resource in authorizationpolicies destinationrules envoyfilters gateways peerauthentications proxyconfigs requestauthentications serviceentries sidecars telemetries virtualservices wasmplugins workloadentries workloadgroups; do
  echo "--- Checking $resource ---"
  kubectl get $resource --all-namespaces -o json | \
  jq -r '.items[] | select(.status.conditions != null and any(.status.conditions[]; .type == "ModernizationCompatible" and .status == "False")) | {"kind": .kind, "name": .metadata.name, "namespace": .metadata.namespace, "message": [.status.conditions[] | select(.type == "ModernizationCompatible").message]}'
done

    输出示例：

    --- Checking serviceentries ---
{
  "kind": "ServiceEntry",
  "name": "demo-service-entry",
  "namespace": "se",
  "message": [
    "WARNING: unsupported resolution type: DNS_ROUND_ROBIN"
  ]
}
..
--- Checking workloadentries ---
{
  "kind": "WorkloadEntry",
  "name": "demo-we",
  "namespace": "default",
  "message": [
    "WARNING: This API is not supported"
  ]
}

  3. 修复并应用配置：修改 YAML，移除不受支持的字段或将无效值替换为兼容的值。如需帮助，请参阅托管式 Cloud Service Mesh 支持的功能和不受支持的 Istio API 文档。（例如，在提供的示例中，将 ServiceEntry 分辨率从 DNS_ROUND_ROBIN 更新为 DNS）。

  4. 验证修复：应用修复后，请等待最多 24 小时，以便定期检查更新状态。

    • 固定资源上的 ModernizationCompatible 条件应更改为状态："True"。使用以下命令检查资源的状态：

      kubectl get resource name -n namespace -o yaml

      输出示例：

      status:
  conditions:
  - lastTransitionTime: "2026-06-05T06:12:52.219963391Z"
    message: Resource is compatible for modernization
    reason: Compatible
    status: "True"
    type: ModernizationCompatible

    • 重新运行 gcloud container fleet mesh describe 命令。所有相关问题解决后，相应会员方案将不再显示 MODERNIZATION_INCOMPATIBLE_CONFIG 状态。

解决不兼容的舰队规模

MODERNIZATION_INCOMPATIBLE_FLEET_SCALE 代码表示，由于整个舰队的资源规模超出了现代化改造支持的限制，因此无法将舰队现代化改造为 TRAFFIC_DIRECTOR 控制平面。

在此阶段，我们支持在以下限制范围内实现车队的现代化：

  • 整个舰队最多 1,500 个数据平面端点（代理）。
  • 整个舰队最多可有 200 个 Cloud Service Mesh 服务。