Allow multiple/alternative filter flags in clear-docker-cache script (closes #39234)

Ashmit Sharmarequested to merge
4shm1td06/gitlab-runner:fix/issue-39234-multiple-filter-flags-clear-docker-cache into main

What does this MR do?

Adds per-type filter flags to the clear-docker-cache script, giving users granular control over which containers, images, and volumes are pruned.

Previously, the script used a single FILTER_FLAG with docker system prune -af. Because docker system prune --filter only applies to containers, images and volumes were always pruned unconditionally — users could not keep specific images or volumes.

Now the script uses targeted prune commands (container prune, image prune, volume prune) and introduces three independent environment variables:

  • CONTAINER_FILTER_FLAGS — controls which containers are pruned (default: label=com.gitlab.gitlab-runner.managed=true)
  • IMAGE_FILTER_FLAGS — controls which images are pruned (default: empty → all unused images)
  • VOLUME_FILTER_FLAGS — controls which volumes are pruned (default: empty → all unused volumes)

Each variable accepts comma-separated values which are converted to multiple --filter flags. For example:

IMAGE_FILTER_FLAGS="label=keep,label!=provider=Acme" clear-docker-cache

This translates to docker image prune -af --filter=label=keep --filter=label!=provider=Acme.

FILTER_FLAG is preserved for backward compatibility. When set, it is used as the default for CONTAINER_FILTER_FLAGS if that variable is not explicitly set.

Why was this MR needed?

Users running multi-architecture CI jobs or custom Docker setups on GitLab Runner hosts needed the ability to preserve specific Docker images (e.g., large base images) from the prune cycle triggered by clear-docker-cache. The single FILTER_FLAG could not achieve this because docker system prune ignores filter flags for images and volumes.

What's the best way to test this MR?

  1. Run the script with custom per-type filters: 
    CONTAINER_FILTER_FLAGS="label=foo=bar" IMAGE_FILTER_FLAGS="label=keep=true" clear-docker-cache prune
  2. Verify docker container prune -f --filter=label=foo=bar and docker image prune -af --filter=label=keep=true are executed
  3. Run with an explicit FILTER_FLAG and verify it still applies to containers: 
    FILTER_FLAG="label=my-custom=true" clear-docker-cache
  4. Run bash -n to confirm script syntax: 
    bash -n packaging/root/usr/share/gitlab-runner/clear-docker-cache

What are the relevant issue numbers?

Closes #39234 (closed)

Merge request reports