排解功能旗標問題

本指南提供診斷及解決 App Lifecycle Manager 功能旗標常見問題的步驟。

SDK 和執行階段評估

OpenFeature API 的設計可確保旗標評估呼叫不會擲回未處理的例外狀況，而是在發生評估錯誤時傳回預設值。

症狀：旗標傳回安全預設值

如果無法連上旗標服務、供應商無法使用，或旗標設定錯誤，SDK 會傳回程式碼中提供的必要預設值。

解決方法：

  1. 確認 OpenFeature 供應商與 saasconfig.googleapis.com 端點之間的連線。
  2. 檢查驗證錯誤。確認應用程式的執行階段服務帳戶具備 roles/saasconfig.viewer 角色。
  3. 確認 FLAGD_SOURCE_PROVIDER_ID 正確無誤。

問題：評估結果不如預期

如果旗標未傳回預期的變化版本：

解決方法：

  1. 請檢查 CEL 條件和評估情境。
  2. 如果條件檢查期間，內容缺少必要屬性，評估引擎會略過該特定規則。
  3. 如果依百分比分配時缺少屬性，評估作業會傳回 INVALID_CONTEXT。

排解以應用程式為中心的範本同步和控制台推出問題

如果您使用 Application Design Center 複合範本和 Google Cloud 控制台，開始使用功能旗標，請按照下列步驟解決範本同步和推出問題。

症狀：連結 App Design Center 複合式範本後，未建立單位種類

連結複合範本後，如果 SaaS 產品的「Unit kinds」(單元 kind) 分頁仍空白：

解決方法：

  1. 將複合範本匯入 SaaS 產品之前，請確認每個內嵌的標準應用程式範本和父項複合應用程式範本，都已新增至 Application Design Center 的目錄。
  2. 確認 App Lifecycle Manager 服務代理 (service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.) 在專案中具備 roles/saasservicemgmt.serviceAgent 角色。
  3. 請在 Google Cloud 控制台查看 SaaS 產品詳細資料頁面，或執行 gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global，檢查範本同步狀態。

更改下列內容：

  • PROJECT_NUMBER：您的 Google Cloud 專案編號。
  • SAAS_OFFERING_ID：SaaS 產品的 ID。

症狀：在控制台推出旗標後，系統未更新依標準範本建立的單位

如果 Google Cloud 控制台已完成旗標推出作業，但透過標準範本建立的單元未收到更新的旗標設定，請按照下列步驟操作：

解決方法：

  1. 確認單元屬於目標單元 kind、位於推出作業涵蓋的區域，且符合推出作業 kind 設定的任何 unitFilter。
  2. 確認應用程式中的 FLAGD_SOURCE_PROVIDER_ID 與單元的完整功能旗標設定資源路徑 (projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID) 相符。

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • LOCATION：單位所在區域。
  • UNIT_ID：廣告單元 ID。

監控推出作業

監控功能旗標推出作業時，必須驗證自動化調度管理狀態 (推出作業是否完成？) 和應用程式健康狀態 (二進位檔是否擷取旗標？)。

推出自動化調度管理狀態

系統會即時監控作業成功率。

自動暫停

為避免錯誤設定影響整個機群，如果某個位置的失敗率超過推出類型 (errorBudget.allowedCount 或 errorBudget.allowedPercentage，例如每個位置 10% 的門檻) 設定的錯誤預算，系統會自動暫停推出作業。

查看摘要統計資料

使用 describe 指令查看匯總失敗次數，並判斷推出作業是否為 PAUSED 或 FAILED。

gcloud beta app-lifecycle-manager rollouts describe ROLLOUT_ID --location=global

篩選失敗的單元更新

確認失敗後，您必須找出未更新的特定裝置。使用這個篩選器，只找出特定區域中失敗的旗標更新：

gcloud beta app-lifecycle-manager unit-operations list \
    --location=LOCATION \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

診斷根本原因

針對每項失敗作業，您可以在 conditions 欄位 (message 和 reason) 和 errorCategory 中，擷取啟動引擎提供的詳細錯誤訊息 (或檢查推出資源上的 stateMessage)。

gcloud beta app-lifecycle-manager unit-operations describe OPERATION_ID --location=LOCATION

更改下列內容：

  • ROLLOUT_ID：推出作業的 ID。
  • LOCATION：單元作業的區域。
  • OPERATION_ID：單位作業的 ID。

缺少單元設定

本節說明如何避免裝置因固定而無法接收功能旗標設定，以及如何復原裝置。

瞭解單位固定

固定功能會將單元凍結在目前的版本，防止任何自動或手動推出作業更新該單元。在固定期間到期或手動取消固定之前，固定單元會明確排除在推出作業之外。

固定廣告單元缺少設定

在功能旗標推出期間，如果固定單元，就會發生重大問題。固定會封鎖所有更新，也就是說，裝置會略過接收設定所需的 FlagUpdate 作業。

症狀：取消固定單元並升級至需要功能旗標的二進位檔後，應用程式無法初始化或進入無限重試迴圈，導致 readiness 探測失敗，容器持續重新啟動。

根本原因：在單元固定期間，推出作業更新了父項單元種類資源的 defaultFlagRevisions 欄位，但固定單元略過了 FlagUpdate 作業，因此未收到生效中的設定。

診斷指令

使用下列指令，檢查失敗的旗標更新作業和單元狀態。

1. 列出失敗的標記作業

如要找出未更新的單位，請篩選 UNIT_OPERATION_STATE_FAILED 狀態和 flag_update 類型的單位作業。

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

2. 篩選失敗的旗標推出作業

如要找出整個機群或特定裝置中失敗的旗標更新，請為 UNIT_OPERATION_STATE_FAILED 狀態新增條件。

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="unit:UNIT_ID AND state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

3. 檢查失敗原因

使用 describe 指令檢查 conditions 欄位 (message 和 reason) 和 errorCategory。

gcloud beta app-lifecycle-manager unit-operations describe "OPERATION_ID" --location="LOCATION"

4. 檢查裝置狀況

您也可以直接查看單元的目前狀態。如果旗標推出作業失敗，或上次作業發生錯誤，單元的 conditions 清單會包含 type: TYPE_OPERATION_ERROR 項目。

gcloud beta app-lifecycle-manager units describe "UNIT_ID" --location="LOCATION"

更改下列內容：

  • LOCATION：單位或單位作業的區域。
  • UNIT_ID：單元 ID。
  • OPERATION_ID：單位作業的 ID。

手動緩解

如要復原未更新旗標的固定單元，請套用上層單元 kind 的預設旗標修訂版本。

套用單元 kind 預設旗標修訂版本

如果某個單位因在一或多項推出作業中固定而缺少設定，您可以手動將該單位重設為其單位種類中定義的目前基準，藉此復原該單位。

  1. 取消固定單元 (如果已固定)：

    gcloud beta app-lifecycle-manager units update "UNIT_ID" \
    --location="LOCATION" \
    --maintenance-pinned-until-time=""

  2. 從父項單元 kind 擷取預設修訂版本：

    gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
    --location="LOCATION" \
    --format="value(defaultFlagRevisions.join(','))"

  3. 建立包含這些修訂版本的新 FlagRelease：

    gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
    --location="LOCATION" \
    --unit-kind="UNIT_KIND_ID" \
    --revisions="REVISIONS"

  4. 手動啟動 FlagUpdate 單位作業，套用復原版本：

    gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
    --unit="UNIT_ID" \
    --flag-update="projects/PROJECT_ID/locations/LOCATION/flagReleases/recovery-release-1" \
    --location="LOCATION"

更改下列內容：

  • UNIT_ID：要復原的單位 ID。
  • LOCATION：單位所在的區域。
  • UNIT_KIND_ID：父項單位類型的 ID。
  • REVISIONS：以半形逗號分隔的清單，列出步驟 2 傳回的預設旗標修訂版本資源名稱。
  • PROJECT_ID：您的 Google Cloud 專案 ID。