Actions Runner Controller版本升级问题分析与解决方案

问题背景

在使用Actions Runner Controller管理自托管运行器时，用户遇到了一个关于版本升级的典型问题。当用户将gha-runner-scale-set组件从0.8.0升级到0.8.1版本后，控制器日志显示版本不匹配，并自动删除了autoscalinglistener、autoscalingrunnerset、ephemeral-runner-controller和ephemeralrunnerset等关键资源。

问题现象

用户最初的操作步骤是先升级运行器组件(gha-runner-scale-set)到0.8.1，然后升级控制器到0.8.1。这种操作顺序导致了以下现象：

1. 控制器检测到版本不匹配后，自动删除了相关资源
2. 升级控制器后，相关资源未能自动重建
3. 回滚到0.8.0版本后，问题依然存在

根本原因分析

经过深入调查，发现问题的根本原因在于：

1. 版本严格匹配要求：Actions Runner Controller要求控制器和运行器组件的版本必须完全一致，即使是小版本升级(如0.8.0到0.8.1)也需要严格匹配。

2. 遗留资源影响：系统中存在旧版本(0.7.0)的helm release残留，虽然对应的Pod并未运行，但仍对系统产生了干扰。

3. 自动清理机制：当控制器检测到版本不匹配时，会主动清理相关资源，而不是保留资源并标记为不可用状态。

解决方案

正确的升级流程应该是：

1. 首先卸载所有autoscaling runner sets(gha-runner-scale-set实例)
2. 升级控制器版本
3. 重新安装运行器组件

这种顺序确保了版本一致性，避免了资源被意外删除的情况。

最佳实践建议

1. 升级顺序：始终遵循"先卸载运行器组件→升级控制器→重新安装运行器组件"的升级流程。

2. 版本检查：在升级前，使用helm list命令检查系统中是否存在旧版本的残留release。

3. 监控机制：设置对scale set删除事件的监控告警，及时发现版本不匹配问题。

4. 权限管理：在多团队环境中，确保运行器组件所有者能够查看相关资源状态，即使他们无法直接访问控制器日志。

技术实现考量

从技术实现角度看，当前设计选择自动删除不匹配资源而非标记为不可用状态，主要基于以下考虑：

1. 资源效率：避免无用的运行器实例持续消耗集群资源
2. 安全考量：避免引入复杂的webhook机制
3. 明确性：删除操作比状态标记更能引起用户注意

然而，这种设计在多团队环境中确实会带来一定的可观测性挑战。未来版本可能会考虑在资源删除前添加更明显的警告信息，或提供配置选项来控制这一行为。

总结

Actions Runner Controller的版本管理机制要求严格，这是为了确保CRD变更的有效性和系统的稳定性。用户在进行版本升级时，必须严格按照官方文档推荐的顺序操作，并注意检查系统中可能存在的旧版本残留。理解这一机制后，可以避免类似问题的发生，确保自托管运行器的平稳运行。