Build and publish processes create sets of docker layers but do not delete them. As a result, stages storage and images repo instantly grow and consume more and more space. Interrupted build process leaves stale images. When git branch or git tag has been deleted, a set of stages which were built for this image also leave in images repo and stages storage. It is necessary to periodically clean up images repo and stages storage. Otherwise, it will be filled with stale images.

Werf has an efficient multi-level images cleaning. There are following cleaning approaches:

  1. Cleaning by policies
  2. Manual cleaning
  3. Host cleaning

Cleaning by policies

Cleaning by policies helps to organize automatic periodical cleaning of stale images. It implies regular gradual cleaning according to cleaning policies. This is the safest way of cleaning because it does not affect your production environment.

The cleaning by policies method includes the steps in the following order:

  1. Cleanup images repo cleans images repo from stale images according to the cleaning policies.
  2. Cleanup stages storage performs syncing stages storage with images repo.

These steps are combined in one top-level command cleanup.

A images repo is the primary source of information about actual and stale images. Therefore, it is essential to clean images repo on the first step and only then stages storage.

Cleanup images repo

There is a werf ability to automate cleaning of images repo. It works according to special rules called cleanup policies. These policies determine which images to delete and which not to.

Cleanup policies

  • by branches:
    • Every new commit updates an image for the git branch (there is the only one docker tag for each published git branch).
    • Werf deletes an image from images repo when the corresponding git branch does not exist. The image always remains, while the corresponding git branch exists.
    • The policy covers images tagged by werf with --tag-git-branch option.
  • by commits:
    • Werf deletes an image from images repo when the corresponding git commit does not exist.
    • For the remaining images, the following policies apply:
      • git-commit-strategy-expiry-days. Keep published images in the images repo for the specified maximum days since image published. Republished image will be kept specified maximum days since new publication date. No days limit by default, -1 disables the limit. Value can be specified by --git-commit-strategy-expiry-days option or $WERF_GIT_COMMIT_STRATEGY_EXPIRY_DAYS.
      • git-commit-strategy-limit. Keep specified max number of published images in the images repo. No limit by default, -1 disables the limit. Value can be specified by --git-commit-strategy-limit or $WERF_GIT_COMMIT_STRATEGY_LIMIT.
    • The policy covers images tagged by werf with --tag-git-commit option.
  • by tags:
    • Werf deletes an image from images repo when the corresponding git tag does not exist.
    • For the remaining images, the following policies apply:
      • git-tag-strategy-expiry-days. Keep published images in the images repo for the specified maximum days since image published. Republished image will be kept specified maximum days since new publication date. No days limit by default, -1 disables the limit. Value can be specified by --git-tag-strategy-expiry-days option or $WERF_GIT_TAG_STRATEGY_EXPIRY_DAYS.
      • git-tag-strategy-limit. Keep specified max number of published images in the images repo. No limit by default, -1 disables the limit. Value can be specified by --git-tag-strategy-limit or $WERF_GIT_TAG_STRATEGY_LIMIT.
    • The policy covers images tagged by werf with --tag-git-tag option.

Pay attention, that cleanup affects only images built by werf and images tagged by werf with one of the following options: --tag-git-branch, --tag-git-tag or --tag-git-commit. Other images in the images repo stay as they are.

Whitelist of images

The image always remains in images repo while exists kubernetes object which uses the image. In kubernetes cluster, werf scans the following kinds of objects: pod, deployment, replicaset, statefulset, daemonset, job, cronjob, replicationcontroller.

The functionality can be disabled by option --without-kube.

Connecting to kubernetes

Werf gets information about kubernetes clusters and how to connect to them from the kube configuration file ~/.kube/config. Werf connects to all kubernetes clusters, defined in all contexts of kubectl configuration, to gather images that are in use.

Cleanup stages storage

Executing a stages storage cleanup command is necessary to update it according to a images repo. On this step, werf deletes stages which do not relate to images currently existing in the images repo.

If the images cleanup command, — the first step of cleaning by policies, — was skipped, then stages storage cleanup makes no sense.

Manual cleaning

Manual cleaning approach assumes one-step cleaning with the complete removal of images from stages storage or images repo. This method does not check whether the image used by kubernetes or not. Manual cleaning is not recommended for automatic usage (use cleaning by policies instead). In general it suitable for forced images removal.

The manual cleaning approach includes the following options:

These steps are combined in one top-level command purge.

Host cleaning

There are following commands to cleanup host machine: