Actions Runner Controller 在 GitHub Enterprise 3.14.1 版本下的 Runner 注册问题分析与解决方案

问题背景

在使用 Actions Runner Controller (ARC) 项目部署自托管 Runner 时，用户遇到了与 GitHub Enterprise 3.14.1 版本的兼容性问题。主要症状表现为 Runner 无法成功注册，控制器日志中显示"RunnerScaleSetNotFoundException"错误，提示找不到标识符为12的Runner规模集。

问题分析

根本原因

经过深入分析，这个问题并非真正的版本兼容性问题，而是由于ARC资源清理不彻底导致的。具体表现为：

1. 在重新安装ARC时，之前的安装残留了未完全清理的Custom Resources
2. 这些残留资源保留了finalizers（终结器），阻止了Kubernetes的正常清理流程
3. 新安装的ARC尝试使用相同的标识符注册Runner时，与残留资源产生冲突

技术细节

在Kubernetes中，finalizers是一种保护机制，确保资源在被删除前完成必要的清理工作。然而在某些情况下，特别是当控制器意外终止或删除操作被中断时，这些finalizers可能会被"卡住"，导致资源无法被完全删除。

在ARC的场景中，以下资源类型特别容易出现这个问题：

• AutoscalingListeners
• EphemeralRunners
• RunnerScaleSets

解决方案

临时解决方案

对于已经出现问题的环境，可以手动清理残留资源：

1. 首先检查所有相关的Custom Resources：

   kubectl get AutoscalingListeners,EphemeralRunners,RunnerScaleSets -n <namespace>
   

2. 移除这些资源的finalizers：

   kubectl get AutoscalingListeners -n <namespace> -o name | xargs -I {} kubectl patch {} -n <namespace> -p '{"metadata":{"finalizers":null}}' --type=merge
   

3. 对其他资源类型重复类似操作

最佳实践

为了避免此类问题，建议在升级或重新安装ARC时遵循以下步骤：

1. 完全卸载现有安装：

   helm uninstall <release-name>
   

2. 等待所有资源被完全清理（可能需要几分钟）

3. 确认命名空间中没有残留资源：

   kubectl get all,AutoscalingListeners,EphemeralRunners,RunnerScaleSets -n <namespace>
   

4. 确认可以删除命名空间（测试目的）：

   kubectl delete namespace <namespace>
   

5. 如果命名空间无法删除，说明仍有资源未清理，需要手动移除finalizers

6. 确认清理完成后，再进行新版本的安装

预防措施

1. 在升级ARC前，确保所有工作负载已完成
2. 考虑在维护窗口期执行升级操作
3. 监控卸载过程，确保所有资源被正确清理
4. 对于生产环境，建议先在测试环境验证升级过程

总结

虽然这个问题表现为版本兼容性问题，但实际上是由于Kubernetes资源清理机制引起。理解Kubernetes的finalizer机制对于管理类似ARC这样的复杂Operator至关重要。通过遵循正确的卸载和安装流程，可以避免大多数此类问题。

对于未来版本，ARC团队已经意识到需要改进升级体验，可能会引入更健壮的清理机制和更明确的进度反馈，以帮助用户更好地管理生命周期操作。