Actions Runner Controller 故障排查指南

Actions Runner Controller 故障排查指南

actions-runner-controller Kubernetes controller for GitHub Actions self-hosted runners 项目地址: https://gitcode.com/gh_mirrors/ac/actions-runner-controller

前言

本文是针对 Actions Runner Controller 项目的深度故障排查指南。作为 Kubernetes 原生的 GitHub Actions 运行器管理工具，该控制器在实际部署和运维过程中可能会遇到各种问题。本文将系统性地梳理常见问题场景，并提供专业的技术解决方案。

排查工具准备

在开始排查前，建议准备以下 Kubernetes 专用工具：

1. kubectl-fields：用于解析 Kubernetes 资源层次结构的命令行工具
2. stern：支持多 Pod 和多容器日志追踪的 Kubernetes 日志工具

安装阶段问题

Webhook 调用超时问题

问题现象： 在安装过程中出现类似错误：

Internal error occurred: failed calling webhook...
Post "https://actions-runner-controller-webhook...": context deadline exceeded

根本原因：

1. 旧版本残留的 webhook 配置未清理干净
2. Kubernetes 控制平面无法访问 admission webhook 服务的 ClusterIP
3. 在私有 GKE 集群上防火墙规则限制

解决方案：

1. 清理残留 webhook：

kubectl delete mutatingwebhookconfiguration actions-runner-controller-mutating-webhook-configuration
kubectl delete validatingwebhookconfiguration actions-runner-controller-validating-webhook-configuration

2. 网络连通性检查：

• 确认 API Server 可以访问服务 ClusterIP
• 检查 CNI 插件配置是否正确

3. GKE 特殊处理：

• 修改 webhook 端口为 443 或 10250（默认放通）
• 或添加防火墙规则允许控制平面访问工作节点

无效头部字段值错误

问题现象： 控制器日志显示：

net/http: invalid header field value "Bearer $TOKEN\n" for key Authorization

原因分析： Base64 编码的 PAT 令牌末尾包含换行符(\n)

解决方案： 使用 -n 参数避免换行符：

echo -n $TOKEN | base64

Helm 证书验证失败

问题现象： 安装时出现证书验证错误：

x509: certificate signed by unknown authority

排查步骤：

1. 检查 cert-manager 日志
2. 确认是否使用已弃用的 admissionregistration.k8s.io/v1beta1 API

解决方案： 升级 cert-manager 到支持当前 Kubernetes 版本的发行版

运行阶段问题

运行器卡在终止状态

问题现象： Runner 资源或底层 Pod 卡在 Terminating 状态

解决方案： 移除 finalizer 强制删除：

kubectl get runners --no-headers | awk {'print $1'} | xargs kubectl patch runner --type merge -p '{"metadata":{"finalizers":null}}'

任务分配延迟

问题现象： 任务分配到运行器出现明显延迟

根本原因： 运行器自我更新过程导致

解决方案： 禁用自动更新：

env:
  - name: DISABLE_RUNNER_UPDATE
    value: "true"

网络准备就绪问题

问题现象： 在服务网格环境下，运行器启动时网络未就绪

解决方案： 添加启动延迟：

env:
  - name: STARTUP_DELAY_IN_SECONDS
    value: "5"

网络请求挂起

问题现象： 部分网络请求无限期挂起

根本原因： MTU 不匹配导致数据包分片问题

解决方案： 调整 Docker MTU 设置：

spec:
  dockerMTU: 1400
  env:
    - name: ARC_DOCKER_MTU_PROPAGATION
      value: "true"

无法缩容到零

问题现象： HorizontalRunnerAutoscaler 无法将副本数缩减到零

排查步骤： 检查是否有残留的工作流任务：

kubectl get workflows

解决方案： 通过 API 清理残留任务

Docker 存储问题

问题表现：

1. dind 容器启动缓慢或失败
2. 出现 "no space left on device" 错误

解决方案：

1. 性能问题：

• 将存储介质升级为 SSD
• 优化 IO 调度策略

2. 空间不足： 调整 dockerVarRun 卷大小：

spec:
  dockerVarRunVolumeSizeLimit: 50M

结语

本文涵盖了 Actions Runner Controller 从安装到运维的全生命周期常见问题。在实际生产环境中，建议结合监控告警系统，对运行器状态、资源使用率和任务分配延迟等关键指标进行持续观测，以提前发现潜在问题。对于复杂场景，可考虑结合 Kubernetes 事件监控和详细的日志收集方案，构建完整的可观测性体系。

actions-runner-controller Kubernetes controller for GitHub Actions self-hosted runners 项目地址: https://gitcode.com/gh_mirrors/ac/actions-runner-controller