瞭解 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 的叢集，找出 WARNING 或 ERROR 嚴重程度的條件。membershipStates.servicemesh如有不相容問題，輸出內容會與下列內容相似：

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 控制層，因為機群的資源規模超出現代化支援的限制。

在這個階段，我們支援以以下限制條件更新車隊：