このガイドでは、App Lifecycle Manager のフィーチャー トグルに関する一般的な問題の診断と解決の手順について説明します。
SDK とランタイムの評価
OpenFeature API は、フラグ評価呼び出しが未処理の例外をスローせず、評価エラーが発生した場合はデフォルト値を返すように設計されています。
症状: フラグが安全なデフォルト値を返す
フラグサービスにアクセスできない場合、プロバイダが利用できない場合、またはフラグが誤って構成されている場合、SDK はコードで指定された必要なデフォルト値を返します。
解決策:
- OpenFeature プロバイダと
saasconfig.googleapis.comエンドポイント間の接続を確認します。 - 認証エラーを確認します。アプリケーションのランタイム サービス アカウントに
roles/saasconfig.viewerロールがあることを確認します。 FLAGD_SOURCE_PROVIDER_IDが正しいことを確認します。
症状: 予期しない評価結果
フラグが想定されるバリアントを返さない場合:
解決策:
- CEL 条件と評価コンテキストを確認します。
- 条件チェック中にコンテキストに必須属性がない場合、評価エンジンはその特定のルールをスキップします。
- 割合ベースの割り当て中に属性が欠落している場合、評価は
INVALID_CONTEXTを返します。
アプリ中心のテンプレートの同期とコンソールのロールアウトに関するトラブルシューティング
Application Design Center の複合テンプレートと Google Cloud コンソールを使用してフィーチャー トグルをオンボーディングする場合は、次の手順でテンプレートの同期とロールアウトの問題を解決します。
症状: App Design Center の複合テンプレートを接続しても、ユニットの種類が作成されない
複合テンプレートを接続した後も、SaaS サービスの [ユニットの種類] タブが空のままになっている場合:
解決策:
- 複合テンプレートを SaaS サービスにインポートする前に、埋め込まれた各標準アプリケーション テンプレートと親複合アプリケーション テンプレートが Application Design Center のカタログに追加されていることを確認します。
- App Lifecycle Manager サービス エージェント（
service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.）にプロジェクトのroles/saasservicemgmt.serviceAgentロールが付与されていることを確認します。 - 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 コンソールでフラグのロールアウトが完了しても、標準テンプレートから作成されたユニットが更新されたフラグ構成を受信しない場合:
解決策:
- ユニットがターゲット ユニットの種類に属し、ロールアウトに含まれるリージョンにあり、ロールアウトの種類で構成された
unitFilterと一致することを確認します。 - アプリケーションの
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。
手動による緩和
フラグの更新を逃した固定ユニットを復元するには、親ユニットの種類からデフォルトのフラグ リビジョンを適用します。
ユニットの種類のデフォルトのフラグ リビジョンを適用する
1 つ以上のロールアウト中にユニットが固定されたために構成が欠落している場合は、ユニットの種類で定義されている現在のベースラインにユニットを手動でリセットすることで、構成を復元できます。
ユニットの固定を解除する（固定されている場合）:
gcloud beta app-lifecycle-manager units update "UNIT_ID" \ --location="LOCATION" \ --maintenance-pinned-until-time=""親ユニットの種類からデフォルトのリビジョンを取得します。
gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \ --location="LOCATION" \ --format="value(defaultFlagRevisions.join(','))"これらのリビジョンを含む新しい
FlagReleaseを作成します。gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \ --location="LOCATION" \ --unit-kind="UNIT_KIND_ID" \ --revisions="REVISIONS"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。