actions-runner-controller 自托管 Runner 入口脚本功能配置指南环境变量、Docker daemon 定制与优雅停机【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controller本文聚焦 ARCactions-runner-controllerlegacy 模式actions.summerwind.net资源下 Runner 镜像入口脚本entrypoint提供的全部可配置特性。你将掌握通过RunnerDeployment的env字段控制日志级别、启动延迟、Docker 等待超时、自动更新开关以及针对 dind 镜像的 dockerd 网络池与 daemon.json 定制方案并了解这些开关在runner/目录下脚本中的真实生效逻辑从而让自托管 Runner 在各类网络与调度环境下稳定运行。背景legacy 模式与入口脚本在 ARC 的 legacy 模式中Runner、RunnerDeployment等资源定义在actions.summerwind.netAPI 组下对应仓库 apis/actions.summerwind.net/v1alpha1。当 Pod 启动时镜像内的入口脚本负责完成 Runner 的注册、配置与运行其核心实现位于 runner/startup.sh 与 runner/entrypoint.sh。入口脚本通过读取容器环境变量来启用或禁用各类特性这些环境变量全部要求以字符串形式赋值true、2等。需要特别注意的是本文描述的是 legacy 资源的使用方式若使用新版 autoscaling runner scale setsactions.github.com组请参考仓库 docs/gha-runner-scale-set-controller/README.md 对应的使用文档。通过 RunnerDeployment 配置入口特性所有入口特性都可以直接写在RunnerDeployment的 Pod 模板env中。以下是一个覆盖全部通用开关的完整示例apiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: example-runnerdeployment spec: template: spec: env: # 关闭各类入口日志级别的输出 - name: LOG_DEBUG_DISABLED value: true - name: LOG_NOTICE_DISABLED value: true - name: LOG_WARNING_DISABLED value: true - name: LOG_ERROR_DISABLED value: true - name: LOG_SUCCESS_DISABLED value: true # 在入口脚本最开始执行 sleep用于错峰启动 - name: STARTUP_DELAY_IN_SECONDS value: 2 # 指定等待 Docker daemon 可用的时长秒 # 默认 120 秒在部分场景下不足以等待 daemon 就绪 # 参见 issue #1804 - name: WAIT_FOR_DOCKER_SECONDS value: 120 # 完全跳过对 Docker daemon 可用性的等待检查 - name: DISABLE_WAIT_FOR_DOCKER value: true # 关闭 Runner 自动更新 # 警告actions/runner 新版本发布 30 天后 # GitHub 将停止向旧版本 Runner 分配任务 - name: DISABLE_RUNNER_UPDATE value: true日志级别开关LOG_*_DISABLEDLOG_DEBUG_DISABLED、LOG_NOTICE_DISABLED、LOG_WARNING_DISABLED、LOG_ERROR_DISABLED、LOG_SUCCESS_DISABLED分别对应入口脚本的五种日志级别。实现位于 runner/logger.sh只要对应变量被设置无论取值是什么该级别日志就会被静默其注释明确写道the value of the variables MUST not matter, the mere fact that they are set is all that matters日志统一输出到 stderr格式为YYYY-MM-DD hh:mm:ss.SSS $level --- $message例如2022-03-19 10:01:23.172 NOTICE --- example message便于用标准文本工具解析五个级别分别对应不同终端颜色debug 白色、notice 蓝色、warning 黄色、error 红色、success 绿色当设置了NO_COLOR环境变量时输出将去掉 ANSI 颜色码方便采集到日志平台该日志实现可被替换只要在镜像的/usr/local/bin放置同名logger.sh并实现上述五个log.*函数即可参考 runner/actions-runner.ubuntu-22.04.dockerfile 中脚本被复制到/usr/bin、/usr/local/bin优先级更高的设计。启动延迟STARTUP_DELAY_IN_SECONDS在 runner/startup.sh 中脚本最开始便检查该变量if [ -n ${STARTUP_DELAY_IN_SECONDS} ]; then log.notice Delaying startup by ${STARTUP_DELAY_IN_SECONDS} seconds sleep ${STARTUP_DELAY_IN_SECONDS} fi典型用途是当大批 Runner 同时被调度时通过随机或错峰的延迟避免它们在同一时刻涌入 GitHub API 执行注册缓解惊群效应。注意该变量在后续会被unset见下文不会泄漏到 Runner 的工作环境。Docker 等待逻辑WAIT_FOR_DOCKER_SECONDS 与 DISABLE_WAIT_FOR_DOCKER在配置完成、启动 Runner agent 之前runner/startup.sh 会执行 Docker 可用性检查WAIT_FOR_DOCKER_SECONDS${WAIT_FOR_DOCKER_SECONDS:-120} if [[ ${DISABLE_WAIT_FOR_DOCKER} ! true ]] [[ ${DOCKER_ENABLED} true ]]; then log.debug Docker enabled runner detected and Docker daemon wait is enabled if ! timeout ${WAIT_FOR_DOCKER_SECONDS}s bash -c until docker ps ;do sleep 1; done; then log.notice Docker has not become available within ${WAIT_FOR_DOCKER_SECONDS} seconds. Exiting with status 1. exit 1 fi fiWAIT_FOR_DOCKER_SECONDS默认值为120 秒文档明确指出该默认值在部分场景如磁盘冷启动、镜像拉取缓慢下偏短可根据实际情况调大检查方式为每 1 秒执行一次docker ps直到成功或超时超时后入口脚本以状态码 1 退出容器会被 Kubernetes 回收DISABLE_WAIT_FOR_DOCKERtrue可完全跳过该检查例如使用非 dind 镜像、或由外部 sidecar 保证 daemon 就绪时检查依赖DOCKER_ENABLEDtruedind 系列镜像会设置该变量普通 Runner 镜像不会触发等待。关闭自动更新DISABLE_RUNNER_UPDATE设置DISABLE_RUNNER_UPDATEtrue后runner/startup.sh 会向 GitHub Runner 的config.sh追加--disableupdate参数if [ ${DISABLE_RUNNER_UPDATE:-} true ]; then config_args(--disableupdate) log.debug Passing --disableupdate to config.sh to disable automatic runner updates. fi文档中的警告务必重视当 actions/runner 软件发布新版本后GitHub 会在 30 天后停止向运行旧版本软件的 Runner 分配任务。因此关闭自动更新后必须自行建立 Runner 镜像的更新机制例如结合RunnerDeployment的滚动更新否则会导致任务分配中断。仓库在 test/startup/should_work_use_disable_update_switch/test.sh 中对该行为有完整单元测试它会验证配置步骤只执行一次、config.sh收到--disableupdate参数、以及run.sh正常启动。dind Runner 专属高级环境变量以下变量仅在 dindDocker-in-Docker镜像上生效例如summerwind/actions-runner-dind与summerwind/actions-runner-dind-rootless。它们由 dind 入口脚本读取并通过jq写入 Docker daemon 配置apiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: example-runnerdeployment spec: template: spec: dockerdWithinRunnerContainer: true image: summerwind/actions-runner-dind env: # 设置 dockerd daemon.json 中的 default-address-pools 字段 - name: DOCKER_DEFAULT_ADDRESS_POOL_BASE value: 172.17.0.0/12 - name: DOCKER_DEFAULT_ADDRESS_POOL_SIZE value: 24DOCKER_DEFAULT_ADDRESS_POOL_BASE / DOCKER_DEFAULT_ADDRESS_POOL_SIZE在 runner/entrypoint-dind.shrootful与 runner/entrypoint-dind-rootless.shrootless中if [ -n ${DOCKER_DEFAULT_ADDRESS_POOL_BASE} ] [ -n ${DOCKER_DEFAULT_ADDRESS_POOL_SIZE} ]; then jq .\default-address-pools\ [{\base\: \${DOCKER_DEFAULT_ADDRESS_POOL_BASE}\, \size\: ${DOCKER_DEFAULT_ADDRESS_POOL_SIZE}}] /etc/docker/daemon.json /tmp/.daemon.json mv /tmp/.daemon.json /etc/docker/daemon.json fi这两个变量必须成对设置用于控制 dind 内创建的网络子网池BASE指定起始 CIDRSIZE指定每个网络划分出的子网掩码位数。默认情况下 dockerd 会从172.17.0.0/16这一单一网段分配网络当并发创建大量容器网络时容易耗尽地址空间导致failed to allocate network之类的错误配置更大的地址池如示例中的172.17.0.0/12/24可以显著提升可创建的默认 bridge 网络数量。此外dind 入口脚本还支持未在本文档正文中列出的两个同族变量从源码可以确认其行为DOCKER_REGISTRY_MIRROR写入daemon.json的registry-mirrors[0]用于配置镜像加速器DOCKER_INSECURE_REGISTRY写入daemon.json的insecure-registries[0]用于对接 HTTP 私有镜像仓库rootless 变体未实现该变量见源码差异MTU写入daemon.json的mtu字段rootless 变体还会把DOCKERD_ROOTLESS_ROOTLESSKIT_MTU追加到/etc/environment用于适配底层网络 MTUdocker-shim.sh配合ARC_DOCKER_MTU_PROPAGATIONtrue还可以在docker network create时自动传播 bridge 网络的 MTU。通过 ConfigMap 覆盖 daemon.json更灵活的做法是直接将自定义daemon.json以 ConfigMap 挂载到 dind 容器中。挂载路径因运行模式而异rootless/home/runner/.config/docker/daemon.jsonrootful/etc/docker/daemon.jsonapiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: example-runnerdeployment spec: template: spec: dockerdWithinRunnerContainer: true image: summerwind/actions-runner-dind(-rootless) volumeMounts: - mountPath: /home/runner/.config/docker/daemon.json name: daemon-config-volume subPath: daemon.json volumes: - name: daemon-config-volume configMap: name: daemon-cm items: - key: daemon.json path: daemon.json securityContext: fsGroup: 1001 # runner 用户 IDapiVersion: v1 kind: ConfigMap metadata: name: daemon-cm data: daemon.json: | { log-level: warn, dns: [x.x.x.x] }要点说明使用subPath: daemon.json挂载单个文件避免 ConfigMap 以目录形式覆盖原有内容fsGroup: 1001与镜像内runner用户 UIDRUNNER_USER_UID1001见 runner/actions-runner.ubuntu-22.04.dockerfile保持一致确保 rootless dockerd 有权限读取该文件入口脚本在启动 dockerd 前会打印 daemon.json 的最终内容Using /etc/docker/daemon.json with the following content:便于排查配置是否生效该方式与上文的环境变量方式可以共存入口脚本先确保daemon.json存在不存在则写入{}再用jq将环境变量合并进去因此挂载的 ConfigMap 会被环境变量增量叠加而非被覆盖。入口脚本整体流程与测试佐证完整的入口流程可以概括为结合 runner/entrypoint.sh 与 runner/startup.shentrypoint.sh通过dumb-init拉起子进程执行startup.sh并注册TERM信号处理器graceful_stopstartup.sh按需执行启动延迟STARTUP_DELAY_IN_SECONDS、校验GITHUB_URL/RUNNER_NAME/RUNNER_TOKEN等必填变量将/runnertmp下的 Runner 资产拷贝到/runneremptyDir挂载点并确保目录属主为runner:docker根据RUNNER_EPHEMERAL、DISABLE_RUNNER_UPDATE组装config.sh参数以--unattended --replace方式注册失败时最多重试 10 次见 test/startup/should_retry_configuring/test.sh该测试验证配置失败后重试 10 次并以状态码 2 退出、且不执行run.sh按需等待 Docker daemonWAIT_FOR_DOCKER_SECONDS/DISABLE_WAIT_FOR_DOCKERunset RUNNER_NAME RUNNER_REPO RUNNER_TOKEN STARTUP_DELAY_IN_SECONDS DISABLE_WAIT_FOR_DOCKER避免入口专用变量泄漏到 Job 环境中注意LOG_*_DISABLED与 Docker 相关变量不在此列如需隔离可自行在 Job 中处理读取/etc/environment模拟 PAM 行为解决 Docker 不加载系统环境变量的历史问题见 issue #1135最后exec ./run.sh。配套的优雅停机逻辑位于 runner/graceful-stop.sh收到SIGTERM后会先通过config.sh remove将 Runner 从 GitHub Actions 服务中原子移除若失败则等待至多RUNNER_GRACEFUL_STOP_TIMEOUT默认 15 秒让运行中的 Job 自然取消随后向Runner.Listener发送SIGTERM并等待退出确保 Pod 被删除时进行中的工作流任务显示operation was canceled而不是无提示挂起。排查与使用建议日志级别生产环境建议保留NOTICE/ERROR仅关闭DEBUG若将NO_COLOR与LOG_*_DISABLED配合使用可获得干净、无 ANSI 码的结构化日志Docker 超时若 Runner 频繁在注册后立即以状态码 1 退出优先检查WAIT_FOR_DOCKER_SECONDS是否够长再检查dockerd日志入口脚本会打印最终 daemon.json 内容自动更新除非有完善的镜像自动重建流水线否则不建议长期开启DISABLE_RUNNER_UPDATE以免 30 天后被 GitHub 停止分配任务地址池凡是 dind 模式下 Job 内大量创建容器网络的场景都建议显式设置DOCKER_DEFAULT_ADDRESS_POOL_BASE与DOCKER_DEFAULT_ADDRESS_POOL_SIZE版本适用前提以上所有环境变量的行为均以当前仓库 runner 目录下的脚本实现为准自定义镜像或改动过入口脚本的镜像可能存在差异。仓库中还提供了 dind 与普通 Runner 的多版本镜像构建文件runner/actions-runner-dind.ubuntu-22.04.dockerfile、runner/actions-runner.ubuntu-22.04.dockerfile 等若需在入口脚本层面做更深度的定制例如替换 logger、新增钩子可直接在这些镜像之上进行扩展。【免费下载链接】actions-runner-controllerKubernetes controller for GitHub Actions self-hosted runners项目地址: https://gitcode.com/GitHub_Trending/ac/actions-runner-controller创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考