team2oy/docker-gc repository overview

⁠docker-gc

• Usage⁠
  • Excluding Images From Garbage Collection⁠
  • Excluding Containers From Garbage Collection⁠
  • Running as a Docker Image⁠
    • Build the Docker Image⁠
    • Running as a Docker Container⁠

A simple Docker container and image garbage collection script.

• Containers that exited more than an hour ago are removed.
• Images that don't belong to any remaining container after that are removed.

Although docker normally prevents removal of images that are in use by containers, we take extra care to not remove any image tags (e.g., ubuntu:14.04, busybox, etc) that are in use by containers. A naive docker rmi $(docker images -q) will leave images stripped of all tags, forcing docker to re-pull the repositories when starting new containers even though the images themselves are still on disk.

This script is intended to be run as a cron job, but you can also run it as a Docker container (see below⁠).

⁠Excluding Images From Garbage Collection

There can be images that are large that serve as a common base for many application containers, and as such, make sense to pin to the machine, as many derivative containers will use it. This can save time in pulling those kinds of images. There may be other reasons to exclude images from garbage collection. To do so, create /etc/docker-gc-exclude, or if you want the file to be read from elsewhere, set the EXCLUDE_FROM_GC environment variable to its location. This file can contain image name patterns (in the grep sense), one per line, such as spotify/cassandra:latest or it can contain image ids (truncated to the length shown in docker images which is 12.

An example image excludes file might contain:

spotify/cassandra:latest
redis:.*
9681260c3ad5

⁠Excluding Containers From Garbage Collection

There can also be containers (for example data only containers) which you would like to exclude from garbage collection. To do so, create /etc/docker-gc-exclude-containers, or if you want the file to be read from elsewhere, set the EXCLUDE_CONTAINERS_FROM_GC environment variable to its location. This file should container name patterns (in the grep sense), one per line, such as mariadb-data.

An example container excludes file might contain:

mariadb-data
drunk_goodall

⁠Forcing deletion of images that have multiple tags

By default, docker will not remove an image if it is tagged in multiple repositories. If you have a server running docker where this is the case, for example in CI environments where dockers are being built, re-tagged, and pushed, you can enable a force flag to override this default.

FORCE_IMAGE_REMOVAL=1 docker-gc

⁠Forcing deletion of containers

By default, if an error is encountered when cleaning up a container, Docker will report the error back and leave it on disk. This can sometimes lead to containers accumulating. If you run into this issue, you can force the removal of the container by setting the environment variable below:

FORCE_CONTAINER_REMOVAL=1 docker-gc

⁠Excluding Recently Exited Containers and Images From Garbage Collection

By default, docker-gc will not remove a container if it exited less than 3600 seconds (1 hour) ago. In some cases you might need to change this setting (e.g. you need exited containers to stick around for debugging for several days). Set the GRACE_PERIOD_SECONDS variable to override this default.

GRACE_PERIOD_SECONDS=86400 docker-gc

This setting also prevents the removal of images that have been created less than GRACE_PERIOD_SECONDS seconds ago.

⁠Dry run

By default, docker-gc will proceed with deletion of containers and images. To test your command-line options set the DRY_RUN variable to override this default.

DRY_RUN=1 docker-gc

⁠Building docker image

A makefile is provided for building and pushing docker image. Docker version can be specified on build time with variable 'DOCKER_VERSION'. There's also another variable in the makefile that specifies the actual version of the software package ('VERSION'). These two variables are used to generate the used docker tag name.

To build and push a docker image that uses Docker version '1.11.2' and software version 'prod' you'd execute:

DOCKER_VERSION=1.11.2 VERSION=prod DOCKER_REPOSITORY=team2oy/docker-gc make -f Makefile.docker image push

This will create image named team2oy/docker-gc:1.11.2_prod and push it into docker repository.

⁠Running as a Docker Container

The docker-gc container requires access to the docker socket in order to function, so you need to map it when running, e.g.:

$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v /etc:/etc:ro team2oy/docker-gc

The /etc directory is also mapped so that it can read any exclude files that you've created.