Actions Runner Controller 项目中的 Helm 卸载与 CRD 残留问题解析

在 Kubernetes 集群中使用 Helm 管理 Actions Runner Controller (ARC) 时，用户可能会遇到一个典型问题：通过 Helm uninstall 命令卸载控制器后，相关的 CustomResourceDefinitions (CRDs) 资源仍然保留在集群中。这种现象并非 ARC 特有的缺陷，而是源于 Helm 本身对 CRD 的生命周期管理机制。

技术背景

CRD 作为 Kubernetes 中扩展 API 的核心机制，其设计初衷是确保集群中的自定义资源类型具有持久性。Helm 出于安全考虑，在 chart 卸载时默认不会删除 CRD，这是为了避免误操作导致关键资源丢失。这种保守策略在 ARC 场景中表现为：即使完整执行了控制器的 Helm 卸载流程，以下 CRD 仍会保留：

• autoscalinglisteners.actions.github.com
• autoscalingrunnersets.actions.github.com
• ephemeralrunners.actions.github.com
• ephemeralrunnersets.actions.github.com

解决方案实践

对于需要完整清理的场景，建议采用分步操作：

1. 首先卸载 runner-scale-set chart
2. 随后卸载 controller chart
3. 最后手动清理残留 CRD

具体命令示例：

kubectl delete crd autoscalingrunnersets.actions.github.com
kubectl delete crd ephemeralrunnersets.actions.github.com
# 其他相关CRD...

升级场景的特殊处理

当用户需要升级 ARC 版本时，官方文档明确要求必须先执行完整卸载。这是因为新旧版本间的 CRD 可能存在不兼容变更，特别是当 minor 版本号变化时可能包含 breaking changes。这种设计虽然增加了操作复杂度，但确保了版本间转换的可靠性。

进阶注意事项

在复杂部署环境中，用户可能还会遇到 namespace 卡在 Terminating 状态的情况。这通常是由于 finalizers 未清理导致的，此时需要手动移除相关资源的 finalizer 字段。例如通过 kubectl edit 命令清理 autoscalingrunnersets 或 rolebindings 等资源的 finalizers。

架构设计思考

从系统架构角度看，ARC 团队选择不维护多版本 CRD 兼容性是基于安全权衡的结果。虽然这种设计增加了升级复杂度，但避免了引入 mutating webhook 可能带来的安全隐患。对于需要自动化部署的场景，建议将 CRD 清理和安装步骤纳入 CI/CD 流程统一管理。

这种设计决策反映了 Kubernetes 生态中常见的可靠性优先原则，开发者在享受自定义资源强大功能的同时，也需要理解其背后的运维约束条件。