Debug Cluster

HyperShift クラスターのデバッグガイド

このスキルでは、HyperShift のホステッドクラスターでよくある問題に対する、体系的なデバッグワークフローを紹介します。

このスキルを使用する場合

このスキルは、次の場合に自動的に適用されます。

• ホステッドクラスターの削除に関する問題を調査するとき
• リソースやファイナライザーが停止している問題をデバッグするとき
• コントロールプレーンの問題をトラブルシューティングするとき
• NodePool のライフサイクルに関する問題を分析するとき
• クラスターの問題についてオペレーターのログを確認するとき

プロバイダー固有のトラブルシューティング

プロバイダー固有の問題や詳細なトラブルシューティング手順については、次のサブスキルを参照してください。

• AWS：aws-troubleshooting.md - AWS 固有の CAPI の問題、インフラストラクチャのクリーンアップ、再インストール

以下のメインスキルでは、プロバイダーに依存しないデバッグワークフローを紹介します。プロバイダー固有の問題が発生した場合は、該当するサブスキルを参照して、詳細な解決手順を確認してください。

理解しておくべき主要コンポーネント

リソース階層

• HostedCluster（HC）：管理クラスター内のメインクラスターリソース
• HostedControlPlane（HCP）：HCP 名前空間内で HC を表すコントロールプレーン
• NodePool（NP）：ワーカーノードプールのリソース
• CAPI リソース：HCP 名前空間内の Cluster、Machine などの Cluster API リソース

オペレーター

• hypershift-operator（HO）：HC および NP リソースを管理します
• control-plane-operator（CPO）：HCP およびコントロールプレーンコンポーネントを管理します
• hosted-cluster-config-operator（HCCO）：ホステッドクラスターの設定およびクラスター内リソースを管理します

名前空間

• HC 名前空間：HostedCluster および NodePool リソースが存在する場所（例：default、clusters）
• HCP 名前空間：コントロールプレーンの Pod および CAPI リソースが実行される場所（例：clusters-<cluster-name>）

よくあるデバッグシナリオ

シナリオ：ホステッドクラスターの削除が停止している

ホステッドクラスターが削除中の状態で停止している場合は、次の手順で体系的にデバッグしてください。

1. NodePool の削除

NodePool の削除が進行していることを確認します。

# Check NodePool resources in HC namespace
kubectl get nodepool -n <hc-namespace>

# Check CAPI cluster resource status in HCP namespace
kubectl get cluster -n <hcp-namespace> -o yaml

# Check CAPI provider pod logs
kubectl logs -n <hcp-namespace> deployment/capi-provider

# Check CAPI machines status in HCP namespace
kubectl get machines -n <hcp-namespace>
kubectl describe machines -n <hcp-namespace>

# Review HyperShift operator logs for NodePool issues
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i nodepool
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i <cluster-name>

確認する項目：

• NodePool の削除を妨げているファイナライザー
• 終了処理が進んでいない CAPI マシン
• マシンの削除を妨げているプロバイダーエラー
• リコンシリエーションエラーを示す HO のログ

2. HostedControlPlane リソースの削除

HCP リソースおよび Pod のクリーンアップが進行していることを確認します。

# Check HCP resource status
kubectl get hostedcontrolplane -n <hcp-namespace> -o yaml

# Check pods in HCP namespace
kubectl get pods -n <hcp-namespace>

# Check for stuck pods
kubectl get pods -n <hcp-namespace> --field-selector=status.phase!=Running

# Review control-plane-operator logs
kubectl logs -n <hcp-namespace> deployment/control-plane-operator --tail=100

確認する項目：

• 削除を妨げている HCP のファイナライザー
• ファイナライザーがある Pod、または Terminating 状態の Pod
• リソースのクリーンアップでエラーが発生していることを示す CPO のログ
• 名前空間の削除を妨げている PVC などのリソース

3. HCP 名前空間の削除

HCP 名前空間が削除されない理由を調査します。

# Check namespace status
kubectl get namespace <hcp-namespace> -o yaml

# List all remaining resources in namespace
kubectl api-resources --verbs=list --namespaced -o name | \
  xargs -n 1 kubectl get --show-kind --ignore-not-found -n <hcp-namespace>

# Check for resources with finalizers
kubectl get all -n <hcp-namespace> -o json | \
  jq '.items[] | select(.metadata.finalizers != null) | {kind: .kind, name: .metadata.name, finalizers: .metadata.finalizers}'

# Review HO logs for namespace cleanup
kubectl logs -n hypershift deployment/operator --tail=100 | grep -i namespace

確認する項目：

• 削除を妨げているファイナライザー付きのリソース
• HO がクリーンアップしているはずの API リソース
• Webhook またはアドミッションコントローラーのエラー
• Terminating 状態で停止している名前空間

4. HostedCluster リソースの削除

最後に、HostedCluster リソース自体を確認します。

# Check HostedCluster status
kubectl get hostedcluster -n <hc-namespace> <cluster-name> -o yaml

# Check HostedCluster finalizers
kubectl get hostedcluster -n <hc-namespace> <cluster-name> -o jsonpath='{.metadata.finalizers}'

# Review HO logs for HostedCluster deletion
kubectl logs -n hypershift deployment/operator --tail=200 | grep -i "hostedcluster.*<cluster-name>"

確認する項目：

• HostedCluster の削除を妨げているファイナライザー
• リコンシリエーションループ内で発生している HO のエラー
• クリーンアップされていない依存リソース
• 削除に失敗したクラウドリソース

デバッグのクイックチェックリスト

クラスターの削除に関する問題を調査する際は、次の項目を確認します。

• リソースのステータスと状態を確認する
• 関連するオペレーター（HO、CPO）のログを確認する
• 停止しているリソースのファイナライザーを調べる
• CAPI リソースのリコンシリエーションを確認する
• 失敗を示すイベントがないか確認する
• プロバイダーエラーがないか確認する
• 名前空間のクリーンアップの進行状況を確認する
• Webhook またはアドミッションエラーがないか確認する

よくある問題と解決方法

問題：NodePool を削除できない

• 原因：プロバイダーエラーにより CAPI マシンの処理が停止している
• 解決方法：プロバイダーの認証情報を確認し、HO のログでマシンの削除エラーを調査します

問題：「Deleting」フェーズで「WaitingForInfrastructureDeletion」のまま停止するマシン

• 原因：マシンリソースより先にクラスターリソースが削除され、CAPI コントローラーの調整が妨げられています
• 根本原因：CAPI マシンコントローラーは、削除を続行するためにクラスターリソースが「ready」であることを必要とします
• 症状：
  • マシンに InfrastructureReady: 1 of 2 completed と表示される
  • CAPI のログに、クラスターリソースが ready ではないことが表示される
  • インスタンスは引き続き実行中ですが、コントローラーが終了できません
• 解決方法：プロバイダー固有のクリーンアップが必要です。プロバイダー固有のトラブルシューティングを参照してください：
  • AWS：詳しい解決手順については、aws-troubleshooting.md を参照してください

問題：HCP 名前空間が Terminating のまま停止する

• 原因：ファイナライザーが設定されたリソース、または失敗している Webhook
• 解決方法：名前空間内のすべてのリソースを一覧表示し、孤立したリソースからファイナライザーを削除して、Webhook が利用可能か確認してください

問題：HostedCluster がファイナライザーのために停止する

• 原因：依存リソース（NodePools、HCP、クラウドリソース）が完全にクリーンアップされていません
• 解決方法：依存するすべてのリソースが削除されていることを確認し、調整エラーがないか HO のログを確認してください

問題：コントロールプレーンの Pod が終了しない

• 原因：PVC または保護用ファイナライザーが設定されたその他のリソース
• 解決方法：PVC のステータスを確認し、ストレージクラスのファイナライザーを確認して、CPO のログを調査してください

シナリオ：HyperShift CRD の欠落または破損

HyperShift CRD が誤って削除または破損した場合（例：hypershift destroy infra の実行後）は、HyperShift を再インストールする必要があります。

⚠️ 警告：HyperShift の再インストールは最後の手段としてください。 CRD が実際に欠落または破損しており、ほかの方法では復旧できない場合に限り、続行してください。再インストールするとダウンタイムが発生し、既存のホステッドクラスターに影響する可能性があります。

症状：

• kubectl get hostedclusters などのコマンドが、error: the server doesn't have a resource type "hostedclusters" というエラーで失敗する
• HyperShift オペレーターのログに、CRD の欠落に関するエラーが表示される
• HostedCluster、NodePool、または CAPI リソースの CRD が欠落している

欠落している CRD の確認：

# Check if critical HyperShift CRDs exist
kubectl get crd hostedclusters.hypershift.openshift.io
kubectl get crd nodepools.hypershift.openshift.io

# Count HyperShift CRDs (should be ~9)
kubectl get crd | grep hypershift | wc -l

# Count CAPI CRDs (should be ~50)
kubectl get crd | grep cluster.x-k8s.io | wc -l

解決方法：HyperShift の再インストール

🤖 AI アシスタント向けの注意： このシナリオが発生した場合、Claude は再インストール手順をユーザーに案内し、提案してください。ただし、再インストールコマンドを実行してはいけません。ユーザー自身が明示的にこれらのコマンドを実行する必要があります。明確な手順と説明を提示してください。ただし、Bash ツールを使って実際に再インストールを実行しないでください。

ステップ 1：必要なパラメーターを収集する

# You'll need these for reinstallation:
# - OIDC storage provider configuration (provider-specific, see below)
# - Provider credentials (if applicable)
# - Any custom configuration flags used in original installation

プロバイダー固有のパラメーター：

• AWS：AWS 固有の OIDC S3 パラメーターについては、aws-troubleshooting.md を参照してください

ステップ 2：HyperShift を完全にアンインストールする

hypershift install render | kubectl delete -f -

これにより、以下が実行されます：

• HyperShift オペレーターのデプロイメントを削除する
• HyperShift のすべての CRD（HostedCluster、NodePool など）を削除する
• RBAC リソース、Webhook、その他のコンポーネントをクリーンアップする

ステップ 3：HyperShift を再インストールする

hypershift install \
  [provider-specific-flags] \
  --enable-defaulting-webhook true

元のインストール時に使用したその他のフラグも追加してください。

プロバイダー固有のインストール：

• AWS：AWS 固有のインストール例については、aws-troubleshooting.md を参照してください

ステップ 4：インストールを確認する

# Check operator is running
kubectl get deploy -n hypershift
kubectl get pods -n hypershift

# Verify CRDs are installed
kubectl get crd | grep hostedcluster
kubectl get crd | grep nodepool
kubectl get crd | grep cluster.x-k8s.io | wc -l

# Test API accessibility
kubectl get hostedclusters -A

# Check operator logs for errors
kubectl logs -n hypershift deployment/operator --tail=50

# Verify controllers are running
kubectl logs -n hypershift deployment/operator --tail=100 | grep "Starting workers"

再インストール後に期待される結果：

• オペレーターのデプロイメント：2/2 READY
• HostedCluster CRD：存在する
• NodePool CRD：存在する
• CAPI CRD：約 50 個がインストール済み
• HyperShift CRD：約 9 個が合計で存在する
• コントローラー：HostedCluster、NodePool、その他のコントローラーでワーカーが起動している
• Webhook：Mutating Webhook が設定されている
• API：クラスターが存在しなくても、kubectl get hostedclusters -A が正常に実行される

重要な注意事項：

• リソースが引き続き存在していれば、再インストールによって既存のホステッドクラスターに影響することはありません
• CRD が削除されている場合、既存の HostedCluster／NodePool リソースは失われています
• 定義が失われている場合は、ホステッドクラスターを再作成する必要があります
• 元のインストール時と同じ設定フラグを使用してください

一般的なデバッグのヒント

ファイナライザーの確認

# List all finalizers on a resource
kubectl get <resource-type> <name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

# Remove a specific finalizer (use with caution!)
kubectl patch <resource-type> <name> -n <namespace> -p '{"metadata":{"finalizers":null}}' --type=merge

オペレーターログ

# HyperShift operator logs with context
kubectl logs -n hypershift deployment/operator --tail=500 --timestamps

# Control plane operator logs
kubectl logs -n <hcp-namespace> deployment/control-plane-operator --tail=500 --timestamps

# Follow logs in real-time
kubectl logs -n hypershift deployment/operator -f

リソースイベント

# Get events for a specific resource
kubectl describe <resource-type> <name> -n <namespace>

# Get all events in a namespace, sorted by time
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

条件とステータス

# Check resource conditions
kubectl get <resource-type> <name> -n <namespace> -o jsonpath='{.status.conditions}' | jq .

# Check specific condition
kubectl get hostedcluster <name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Available")]}'

追加リソース

• HyperShift オペレーターのコード：hypershift-operator/controllers/hostedcluster/
• コントロールプレーンオペレーターのコード：control-plane-operator/controllers/
• API 定義：api/hypershift/v1beta1/
• E2E テストの例：test/e2e/