如何为Kubernetes集群内的GitLab Runner自动补丁config.toml文件？

问题重现 #

通过Helm安装的GitLab Kubernetes Runner，执行镜像构建步骤时触发报错：

ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

手动进入Runner Pod修改/home/gitlab-runner/.gitlab-runner/config.toml，添加/var/run/docker.sock的hostPath挂载可临时解决，但Pod重建后配置丢失。需要实现自动持久化该配置，且不能覆盖token、Runner ID等关键参数。

方案一：通过Helm Values配置自动挂载（推荐） #

这是最规范的方式，直接通过Helm values注入挂载规则，无需手动修改config.toml：

1. 编辑你的GitLab Runner Helm values文件，添加以下配置：

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        [[runners.kubernetes.volumes.host_path]]
          name = "docker-sock"
          mount_path = "/var/run/docker.sock"
          host_path = "/var/run/docker.sock"

2. 执行Helm升级命令使配置生效：

helm upgrade --install gitlab-runner gitlab/gitlab-runner -f your-custom-values.yaml

Helm会自动合并默认配置与你添加的挂载规则，新启动的Runner Pod将自动挂载宿主机的docker.sock，且不会覆盖原有token、ID等关键参数。

方案二：用InitContainer自动补丁config.toml #

如果无法直接修改Helm values，可通过InitContainer在Pod启动时自动修改config.toml：

1. 创建存放补丁脚本的ConfigMap：

apiVersion: v1
kind: ConfigMap
metadata:
  name: gitlab-runner-config-patch
data:
  patch-config.sh: |
    #!/bin/sh
    CONFIG_FILE="/home/gitlab-runner/.gitlab-runner/config.toml"
    # 避免重复添加挂载配置
    if ! grep -q 'mount_path = "/var/run/docker.sock"' "$CONFIG_FILE"; then
      # 在[runners.kubernetes]块后插入hostPath挂载配置
      sed -i '/\[runners.kubernetes\]/a \        [[runners.kubernetes.volumes.host_path]]\
          name = "docker-sock"\
          mount_path = "/var/run/docker.sock"\
          host_path = "/var/run/docker.sock"' "$CONFIG_FILE"
    fi

2. 修改GitLab Runner的Deployment（或通过Helm values添加InitContainer）：

initContainers:
- name: patch-runner-config
  image: alpine:latest
  command: ["sh", "/scripts/patch-config.sh"]
  volumeMounts:
  - name: runner-config
    mountPath: /home/gitlab-runner/.gitlab-runner
  - name: patch-scripts
    mountPath: /scripts
volumes:
- name: patch-scripts
  configMap:
    name: gitlab-runner-config-patch
    defaultMode: 0755

InitContainer会在Runner主容器启动前检查并修改config.toml，确保挂载规则存在，同时保留原有关键参数。

方案三：配置Runner注册模板（针对新注册的Runner） #

如果需要让后续新注册的Runner自动应用该配置，可在Helm values中设置注册模板：

runners:
  registrationToken: "你的注册令牌"
  config: |
    [[runners]]
      executor = "kubernetes"
      [runners.kubernetes]
        [[runners.kubernetes.volumes.host_path]]
          name = "docker-sock"
          mount_path = "/var/run/docker.sock"
          host_path = "/var/run/docker.sock"

新Runner注册时会基于该模板生成config.toml，自动包含docker.sock挂载配置。

注意事项 #

• 确认Kubernetes节点上的Docker daemon处于运行状态，且/var/run/docker.sock路径存在
• 若集群使用containerd而非Docker，需挂载/run/containerd/containerd.sock，并调整流水线中DOCKER_HOST环境变量为unix:///run/containerd/containerd.sock
• 升级Helm release时，建议使用独立的自定义values文件管理配置，避免默认配置覆盖自定义规则

内容的提问来源于stack exchange，提问作者rbaleksandar