瞭解 Cloud Service Mesh 相容性

本指南將詳細說明如何評估機群是否適合進行控制層現代化，確認機群的設定、基礎架構和規模是否與 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

叢集層級相容性

在機群中，為每個已佈建的 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 註解問題，請按照下列步驟操作：

找出有問題的註解：檢查狀態條件的 details 欄位，找出不支援或無效的註解鍵。找出所有具有問題註解鍵的 Pod。
修正並驗證：
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

如要解決這些設定問題，請按照下列步驟操作：

分析條件詳細資料：檢查狀態條件的 details 欄位。這份報告會摘要說明個別錯誤，並找出設定有問題的資源類型。以提供的詳細資料範例來說，您必須解決規模和 MeshConfig 問題，並檢查 Gateway 和 ServiceEntry 資源是否有錯誤。

找出並調查不相容的資源：使用下列指令碼列出所有未通過相容性檢查的 Istio 自訂資源 (CR)。指令碼需要安裝 kubectl 和 jq。輸出內容會顯示每個資源的 status.conditions (類型：ModernizationCompatible，狀態："False") 下方顯示的特定錯誤詳細資料。

for resource in authorizationpolicies destinationrules gateways proxyconfigs peerauthentications 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"
  ]
}

修正並套用設定：修改 YAML，移除不支援的欄位，或以相容的值取代無效值。如需相關協助，請參閱「代管 Cloud Service Mesh 支援的功能」和「不支援的 Istio API」說明文件。(例如，在提供的範例中，將 ServiceEntry 解析度從 DNS_ROUND_ROBIN 更新為 DNS)。
確認修正：套用修正後，系統最多需要 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條件。