Actions Runner Controller 中使用私有容器镜像的配置指南

问题背景

在使用 Actions Runner Controller (ARC) 的 gha-runner-scale-set 组件时，许多用户在尝试使用私有容器镜像作为 runner 模板时会遇到 ErrImagePull 错误。这种问题通常发生在将默认的公共镜像 ghcr.io/actions/actions-runner:latest 替换为私有镜像 ghcr.io/<组织名>/gha-runners:latest 时。

核心问题分析

当 Kubernetes 尝试从私有容器注册表拉取镜像时，需要提供适当的认证凭据。这个问题本质上是因为 runner pod 没有配置正确的 imagePullSecrets，导致无法从私有仓库拉取镜像。

解决方案

基础配置

正确的配置方法是在 runner 模板的 spec 部分添加 imagePullSecrets 字段：

template:
  spec:
    imagePullSecrets:
      - name: github-pat  # 这里使用你创建的 Secret 名称
    containers:
      - name: runner
        image: ghcr.io/<my-org>/gha-runners:latest
        command: ["/home/runner/run.sh"]

完整实施步骤

1. 创建 Kubernetes Secret： 首先需要创建一个包含 GitHub 个人访问令牌(PAT)的 Secret：

   kubectl create secret docker-registry github-pat \
     --docker-server=ghcr.io \
     --docker-username=<GitHub用户名> \
     --docker-password=<个人访问令牌> \
     --docker-email=<你的邮箱>
   

2. 验证 Secret： 确保 Secret 已正确创建并包含所需字段：

   kubectl get secret github-pat -o yaml
   

3. 配置 Helm Values： 在 Helm chart 的 values 文件中添加 imagePullSecrets 配置：

   imagePullSecrets:
     - name: github-pat
   

4. 部署验证： 部署后，检查 runner pod 是否能够正常启动并拉取镜像。

进阶问题：工作流中的容器镜像

值得注意的是，即使 runner pod 本身能够正常启动，当在工作流中使用 container.image 指定容器时，这些工作流 pod 不会自动继承 runner pod 的 imagePullSecrets 配置。这是因为：

• 工作流容器是通过容器钩子(container hooks)创建的
• 这些钩子会创建独立的 pod 规范
• 需要单独为这些工作流容器提供拉取凭据

最佳实践建议

1. 统一凭证管理：考虑使用 Kubernetes 的 ServiceAccount 来集中管理镜像拉取凭据
2. 最小权限原则：确保使用的 PAT 仅具有必要的权限（通常只需要 packages:read）
3. 多环境支持：在不同环境（开发、测试、生产）中使用不同的凭证和镜像仓库
4. 监控配置：定期检查 Secret 的有效性，特别是当使用 PAT 时，注意令牌的有效期

通过以上配置，用户可以在 Actions Runner Controller 中顺利使用私有容器镜像作为 runner，同时也能够处理工作流中使用的私有容器镜像的认证问题。