如何在Kubernetes环境下为GitLab Runner配置本地缓存

问题根源 #

在K8s中运行的GitLab Runner，默认不会自动提供持久化的缓存存储：

• 日志里的「成功提取缓存」只是Runner的流程性提示，若未配置持久化卷，缓存会随Pod销毁直接丢失
• /cache是Runner默认的缓存存储挂载点，但如果没配置对应Volume，这个目录根本不会存在
• 你流水线中指定的local-cached-folder，Runner会将其压缩后存到/cache下的对应key目录，而非直接将/cache挂载到工作目录

正确解决方案：用PVC挂载持久化缓存 #

你提到的[[runners.kubernetes.volumes.pvc]]是正确的方向，具体步骤如下：

1. 创建缓存用的PVC（及可选PV） #

根据你的集群环境选择存储方式，以下是两种常见场景：

单节点测试场景（用hostPath）

先创建PV：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: gitlab-runner-cache-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /mnt/gitlab-runner-cache # 节点上提前创建该目录并授权
    type: DirectoryOrCreate

再创建PVC：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gitlab-runner-cache-pvc
  namespace: gitlab-runner # 替换为你的Runner所在命名空间
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: "" # 禁用存储类，直接绑定上面的PV

多节点生产场景（用本地存储类）

如果集群有本地存储类（比如local-storage），直接创建PVC即可：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gitlab-runner-cache-pvc
  namespace: gitlab-runner
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: "local-storage" # 替换为你的集群本地存储类名称

2. 修改GitLab Runner配置文件（config.toml） #

在[[runners]]块的[runners.kubernetes]下添加PVC挂载配置：

[[runners]]
  name = "k8s-runner"
  url = "https://你的GitLab地址/"
  token = "你的Runner令牌"
  executor = "kubernetes"
  [runners.kubernetes]
    namespace = "gitlab-runner"
    # 保留其他已有K8s配置...
    # 添加缓存PVC挂载
    [[runners.kubernetes.volumes.pvc]]
      name = "gitlab-runner-cache-pvc"
      mount_path = "/cache" # 必须与Runner默认的cache_dir一致，默认就是/cache

修改后重启GitLab Runner Pod使配置生效。

3. 优化流水线缓存配置 #

调整cache policy让缓存逻辑更清晰：

default:
  cache: &cache
    key: "$CI_COMMIT_REF_SLUG"
    paths:
      - local-cached-folder

prepare: 
  stage: prepare
  cache:
    <<: *cache
    policy: push # 仅上传缓存，无需提前拉取
  script:
    - mkdir local-cached-folder
    - echo "preparing…" > ./local-cached-folder/cached_file
    - ls -lFa . # 确认文件创建成功

build:
  stage: build
  cache:
    <<: *cache
    policy: pull # 仅拉取缓存，无需上传
  script:
    - ls -lFa local-cached-folder # 此处应能看到cached_file

关键注意事项 #

• 不要直接查看/cache目录：该目录存储的是Runner压缩后的缓存包，你的缓存内容会被自动解压到流水线指定的paths路径下
• 若流水线首次运行，build阶段拉取缓存会显示「成功提取」但实际为空，这是正常现象，后续运行即可读取到prepare阶段的缓存
• 多节点Runner需确保PVC的访问模式适配，若用ReadWriteOnce，同一缓存只能被一个节点上的Pod使用，多节点共享需用分布式存储

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