Azure Kubernetes Fleet Manager の ClusterStagedUpdateRun と StagedUpdateRun API オブジェクト関連のエラーのトラブルシューティング (プレビュー)

概要

この記事は、azure Kubernetes Fleet Manager の使用時に発生する API とClusterStagedUpdateRun API オブジェクト関連のエラーStagedUpdateRun解決するのに役立ちます。 ハブ クラスターでこれらのエラーをトラブルシューティングするには、次のオブジェクトに関する知識が必要です。

ClusterStagedUpdateRun

  • ClusterResourceSnapshot
  • ClusterSchedulingPolicySnapshot
  • ClusterResourceBinding

StagedUpdateRun

  • ResourceSnapshot
  • SchedulingPolicySnapshot
  • ResourceBinding

各オブジェクトの詳細については、 KubeFleet API リファレンスを参照してください。

デプロイメントの全体的な進捗

ClusterStagedUpdateRunカスタム リソースの進行状況と状態を理解することは、障害を診断して特定できるようにするために重要です。 次のコマンドを実行すると、 ClusterStagedUpdateRun デプロイの状態を表示できます。

kubectl describe clusterstagedupdaterun <name>

ClusterStagedUpdateRunの進行状況は次のとおりです。

  • 初期化済み: ロールアウトを開始するために、 ClusterStagedUpdateRun とそれに対応するリソース (ClusterResourcePlacement、 ClusterStagedUpdateStrategy) が正しく設定されているかどうかを示します。

詳細については、「 ClusterStagedUpdateRun 初期化エラーのトラブルシューティング方法」を参照してください。

  • 進行状況: デプロイが各ステージを順番に処理し、各ステージ内のクラスターを更新し ( maxConcurrencyを考慮して)、ステージ前タスクとステージ後タスクを適用していることを示します。

UpdateRunStuckが 'False' に設定されている場合は、「ClusterStagedUpdateRun スタックのトラブルシューティング方法」を参照してください。ClusterStagedUpdateRun 実行エラーのトラブルシューティング方法を参照してください。

ClusterStagedUpdateRun 使用時のトラブルシューティング

  • ClusterStagedUpdateRun が自動的に実行されない

原因

状態を示さずに ClusterStagedUpdateRun インスタンスを作成した場合、 ClusterStagedUpdateRun は実行を開始しません。 ClusterStagedUpdateRun 代わりに既定値を使用します。

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: ClusterStagedUpdateRun
metadata:
  ...
  generation: 1
  name: example-run
  ...
spec:
  placementName: example-placement
  resourceSnapshotIndex: "0"
  stagedRolloutStrategyName: example-strategy
  state: Initialize
status:
  appliedStrategy:
    comparisonOption: PartialComparison
    type: ClientSideApply
    whenToApply: Always
    whenToTakeOver: Always
  conditions:
  - lastTransitionTime: "2026-01-09T01:21:18Z"
    message: The UpdateRun initialized successfully
    observedGeneration: 1
    reason: UpdateRunInitializedSuccessfully
    status: "True"
    type: Initialized

この場合、 ClusterStagedUpdateRun は既定で Initialize に設定されます。

解決策

次のコマンドを実行して、 ClusterStagedUpdateRun を Run 状態に更新します。

kubectl patch clusterstagedupdaterun example-run --type='merge' -p '{"spec":{"state":"Run"}}'
  • ClusterStagedUpdateRun ユーザーが承認した後に進行しない ClusterApprovalRequest

ClusterStagedUpdateRun をご確認ください。

$ kubectl get clusterstagedupdaterun example-run -o yaml

...
status:
  appliedStrategy:
    comparisonOption: PartialComparison
    type: ClientSideApply
    whenToApply: Always
    whenToTakeOver: Always
  conditions:
  - lastTransitionTime: "2026-01-09T01:49:06Z"
    message: The UpdateRun initialized successfully
    observedGeneration: 1
    reason: UpdateRunInitializedSuccessfully
    status: "True"
    type: Initialized
  - lastTransitionTime: "2026-01-09T01:55:36Z"
    message: The updateRun is waiting for after-stage tasks in stage staging to complete
    observedGeneration: 1
    reason: UpdateRunWaiting
    status: "False"
    type: Progressing
...

原因

ClusterStagedUpdateRun は、ユーザーからの承認をまだ待機しています。 ClusterApprovalRequestを調べて、次のことを確認します。

$ kubectl get clusterapprovalrequest example-run-after-staging -o yaml

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: ClusterApprovalRequest
metadata:
  creationTimestamp: "2026-01-09T01:49:36Z"
  generation: 1
  labels:
    kubernetes-fleet.io/isLatestUpdateRunApproval: "true"
    kubernetes-fleet.io/targetUpdateRun: example-run
    kubernetes-fleet.io/targetUpdatingStage: staging
    kubernetes-fleet.io/taskType: afterStage
  name: example-run-after-staging
  resourceVersion: "20752"
  uid: 9eae4ea0-3c4c-4182-a1d6-b7f1761caa6a
spec:
  parentStageRollout: example-run
  targetStage: staging
status:
  conditions:
  - lastTransitionTime: "2026-01-09T01:53:53Z"
    message: approved
    observedGeneration: 0
    reason: approved
    status: "True"
    type: Approved

ユーザーが要求を承認したことを示します (status: "True"、 type: Approved)。 ただし、observedGenerationのApproved値は0に設定されていますが、observedGenerationは1に設定されているため、承認は受け入れられません。 この不一致は、ステージ前タスクとステージ後タスクの両方に適用されます。

解決策

observedGeneration を Approved に更新します。 正しい observedGeneration 値を使用して再証明することもできます。

kubectl patch clusterapprovalrequests example-run-before-canary --type='merge' \
  -p '{"status":{"conditions":[{"type":"Approved","status":"True","reason":"approved","message":"approved","lastTransitionTime":"'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'","observedGeneration":1}]}}' \
  --subresource=status

StagedUpdateRunデプロイの完全な進行

エラーを診断して特定するには、 StagedUpdateRun カスタム リソースの進行状況と状態を理解することが重要です。 StagedUpdateRunの状態を表示するには、次のコマンドを実行します。

kubectl describe stagedupdaterun <name>

StagedUpdateRunの進行状況は次のとおりです。

  1. 初期化済み: ロールアウトを開始するために、 StagedUpdateRun とそれに対応するリソース (ResourcePlacement、 StagedUpdateStrategy) が正しく設定されているかどうかを示します。

詳細については、「 StagedUpdateRun 初期化エラーのトラブルシューティング方法」を参照してください。

  1. 進行状況: デプロイが各ステージを順番に処理し、各ステージ内のクラスターを更新し ( maxConcurrencyを考慮して)、ステージ前タスクとステージ後タスクを適用していることを示します。

UpdateRunStuckがFalseに設定されている場合は、「StagedUpdateRun スタックのトラブルシューティング方法」を参照してください。 それ以外の場合は、「 StagedUpdateRun 実行エラーのトラブルシューティング方法」を参照してください。

使用時のトラブルシューティング StagedUpdateRun

  • StagedUpdateRun が自動的に実行されない

原因

状態を示さずに StagedUpdateRun を作成した場合、 StagedUpdateRun は実行を開始しません。 StagedUpdateRun 代わりに既定値を使用します。

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: StagedUpdateRun
metadata:
  ...
  generation: 1
  name: web-app-rollout
  namespace: my-app-namespace
  ...
spec:
  placementName: web-app-rollout-placement
  resourceSnapshotIndex: "0"
  stagedRolloutStrategyName: example-strategy
  state: Initialize
status:
  appliedStrategy:
    comparisonOption: PartialComparison
    type: ClientSideApply
    whenToApply: Always
    whenToTakeOver: Always
  conditions:
  - lastTransitionTime: "2026-01-09T01:21:18Z"
    message: The UpdateRun initialized successfully
    observedGeneration: 1
    reason: UpdateRunInitializedSuccessfully
    status: "True"
    type: Initialized

この場合、 StagedUpdateRun は既定で Initialize に設定されます。

解決策

次のコマンドを実行して、 StagedUpdateRun を Run 状態に更新します。

kubectl patch stagedupdaterun web-app-rollout -n my-app-namespace --type='merge' -p '{"spec":{"state":"Run"}}'
  • StagedUpdateRun ユーザーが承認した後に進行しない ApprovalRequest

StagedUpdateRun を調査します。

$ kubectl get stagedupdaterun web-app-rollout -n my-app-namespace -o yaml

...
status:
  appliedStrategy:
    comparisonOption: PartialComparison
    type: ClientSideApply
    whenToApply: Always
    whenToTakeOver: Always
  conditions:
  - lastTransitionTime: "2026-01-09T01:49:06Z"
    message: The UpdateRun initialized successfully
    observedGeneration: 1
    reason: UpdateRunInitializedSuccessfully
    status: "True"
    type: Initialized
  - lastTransitionTime: "2026-01-09T01:55:36Z"
    message: The updateRun is waiting for after-stage tasks in stage staging to complete
    observedGeneration: 1
    reason: UpdateRunWaiting
    status: "False"
    type: Progressing
...

原因

StagedUpdateRun は、ユーザーからの承認をまだ待機しています。 ApprovalRequestを調べて、次のことを確認します。

$ kubectl get approvalrequests web-app-rollout-before-dev -n my-app-namespace -o yaml

apiVersion: placement.kubernetes-fleet.io/v1beta1
kind: ApprovalRequest
metadata:
  creationTimestamp: "2026-01-09T02:31:57Z"
  generation: 1
  labels:
    kubernetes-fleet.io/isLatestUpdateRunApproval: "true"
    kubernetes-fleet.io/targetUpdateRun: web-app-rollout
    kubernetes-fleet.io/targetUpdatingStage: dev
    kubernetes-fleet.io/taskType: beforeStage
  name: web-app-rollout-before-dev
  namespace: my-app-namespace
  resourceVersion: "25386"
  uid: 6442e1ef-b694-4d59-8691-a3f5200c29ad
spec:
  parentStageRollout: web-app-rollout
  targetStage: dev
status:
  conditions:
  - lastTransitionTime: "2026-01-09T02:33:15Z"
    message: approved
    observedGeneration: 0
    reason: approved
    status: "True"
    type: Approved

ユーザーが要求を承認したことを示します (status: "True"、 type: Approved)。 ただし、observedGenerationのApprovedは0に設定されていますが、observedGenerationは1に設定されているため、承認は受け入れられません。 この不一致は、ステージ前タスクとステージ後タスクの両方に適用されます。

解決策

observedGeneration を Approved に更新します。 正しい observedGeneration 値を使用して再証明することもできます。

kubectl patch approvalrequests web-app-rollout-before-dev -n my-app-namespace --type='merge' \
  -p '{"status":{"conditions":[{"type":"Approved","status":"True","reason":"approved","message":"approved","lastTransitionTime":"'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'","observedGeneration":1}]}}' \
  --subresource=status
  • Last updated on