Debug Cluster

HyperShift 集群调试指南

此技能为常见的 HyperShift 托管集群问题提供结构化调试工作流。

何时使用此技能

在以下情况下会自动应用此技能：

• 调查托管集群删除问题
• 调试卡住的资源或终结器
• 排查控制平面问题
• 分析 NodePool 生命周期问题
• 查看与集群问题相关的 Operator 日志

提供商特定的故障排查

有关提供商特定问题和详细的故障排查步骤，请参阅以下子技能：

• AWS：aws-troubleshooting.md - AWS 特定的 CAPI 问题、基础设施清理和重新安装

下面的主技能提供与提供商无关的调试工作流。遇到提供商特定问题时，请查阅相关子技能，了解详细的解决步骤。

需要了解的关键组件

资源层级

• HostedCluster（HC）：管理集群中的主要集群资源
• HostedControlPlane（HCP）：HCP 命名空间中 HC 的控制平面表示
• NodePool（NP）：工作节点池资源
• CAPI 资源：HCP 命名空间中的 Cluster API 资源（Cluster、Machine 等）

Operator

• 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 Machine
• 阻止 Machine 删除的提供商错误
• 显示协调错误的 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 终结器
• 带有终结器或处于 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 在协调循环中发生的错误
• 尚未清理的依赖项
• 删除失败的云资源

快速调试清单

调查集群删除问题时：

• 检查资源状态和状况
• 查看相关 Operator 日志（HO、CPO）
• 检查卡住资源上的终结器
• 确认 CAPI 资源正在协调
• 检查是否存在指示故障的事件
• 查找提供商错误
• 确认命名空间清理进度
• 检查是否存在 Webhook 或准入错误

常见问题与解决方法

问题：NodePool 无法删除

• 原因：CAPI Machine 因提供商错误而卡住
• 解决方法：检查提供商凭据，并调查 HO 日志中的 Machine 删除错误

问题：机器卡在 “Deleting” 阶段，并显示 “WaitingForInfrastructureDeletion”

• 原因：在机器资源删除前删除了集群资源，导致 CAPI 控制器协调受阻
• 根本原因：CAPI 机器控制器需要集群资源处于“就绪”状态才能继续执行删除
• 症状：
  • 机器显示 InfrastructureReady: 1 of 2 completed
  • CAPI 日志显示集群资源未就绪
  • 实例仍在运行，但控制器无法终止它们
• 解决方法：需要进行特定于提供商的清理。请参阅提供商专属故障排除指南：
  • 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 确实缺失或损坏，且无法通过其他方式恢复时才继续操作。重新安装会导致停机，并可能影响现有的 hosted-clusters。

症状：

• kubectl get hostedclusters 等命令失败，并显示：error: the server doesn't have a resource type "hostedclusters"
• HyperShift operator 日志显示 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 operator 部署
• 删除所有 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"

重新安装后的预期结果：

• Operator 部署：2/2 READY
• HostedCluster CRD：存在
• NodePool CRD：存在
• CAPI CRD：已安装约 50 个
• HyperShift CRD：共约 9 个
• 控制器：HostedCluster、NodePool 和其他控制器均已启动工作线程
• Webhook：变更 Webhook 已配置
• API：kubectl get hostedclusters -A 成功返回（即使不存在集群）

重要说明：

• 如果 hosted-clusters 的资源仍然存在，重新安装不会影响它们
• 如果 CRD 已被删除，任何现有的 HostedCluster/NodePool 资源都会丢失
• 如果 hosted-clusters 的定义丢失，可能需要重新创建
• 请确保使用与原始安装相同的配置标志

常规调试提示

检查终结器

# 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/