Runner Cache with Docker Executer

GitLab CI/CD
, ,
1

Problem to solve

I can’t seem to wrap my head around how the cache works with the Docker executor.

I have looked up and down at the advanced-configuration documentation, but I cant figure out the relationship between the cache in the runners section and the runners.docker section.

My simple objective is to be able to utilise the runner cache efficiently, and control where it is stored and accessed.

Questions

  1. What does the runners.cache_dir setting control?
  2. What does the runners.docker.cache_dir setting control?
  3. How does the two settings above interact?
  4. How can I control which directory I want the docker container to use as cache directory?

Steps that led to confusion

runners:

cache_dir: Absolute path to a directory where build caches are stored in context of selected executor. For example, locally, Docker, or SSH. If the docker executor is used, this directory needs to be included in its volumes parameter.

runners.docker:

cache_dir: Directory where Docker caches should be stored. This path can be absolute or relative to current working directory. See disable_cache for more information.

Now, reading this I would assume that:

  • runners.cache_dir refers to the path on the HOST on which I want to persistently store caches.
  • runners.docker.cache_dir refers to the path inside the container on which I want to store caches.

I want the cache to be persistently stored at the HOST at /mnt/data/runner-cache, and I want the containers to be able to use /var/cache as its cache directory.
Therefore I mount: /mnt/data/runner-cache:/var/cache

However, when using the following configuration, I could not find any cache persistently stored at /mnt/data/runner-cache.

[[runners]]
  executor = "docker"
  cache_dir = "/mnt/data/runner-cache"

  [runners.docker]
    privileged = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/mnt/data/runner-cache:/var/cache"]

Specifying runners.docker.cache_dir to be /var/cache/ did also not result in any cache being written to /mnt/data/runner-cache/

[[runners]]
  executor = "docker"
  cache_dir = "/mnt/data/runner-cache"

  [runners.docker]
    privileged = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/mnt/data/runner-cache:/var/cache"]
    cache_dir = "/var/cache"

Only after configuring runners.docker.cache_dir to be /mnt/data/runner-cache were I able to find any cache in /mnt/data/runner-cache.

[[runners]]
  executor = "docker"
  cache_dir = "/mnt/data/runner-cache"

  [runners.docker]
    privileged = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/mnt/data/runner-cache:/var/cache"]
    cache_dir = "/mnt/data/runner-cache"

Full Configuration

Runner Config:

[[runners]]
  limit = 0
  executor = "docker"
  cache_dir = "/mnt/data/runner-cache"

  [runners.docker]
    privileged = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/mnt/data/runner-cache:/var/cache"]
    cache_dir = "/mnt/data/runner-cache"
    image = docker:25
    shm_size = 0

Compose:

version: '3.4'

services:
  builder-1:
    image: docker:25
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /mnt/data/runner-cache:/var/cache
    configs:
      - source: gitlab-runner-builder-cfg-1
        target: /etc/gitlab-runner/config.toml

configs:
  gitlab-runner-builder-cfg-1:
    external:
      name: ${GITLAB_BUILDER_CFG_1}

Versions

Please select whether options apply, and add the version information.

  • Self-managed
  • GitLab.com SaaS
  • Self-hosted Runners: gitlab/gitlab-runner:v17.3.1