While building and publishing, werf creates sets of docker layers but does not delete them. As a result, stages storage and images repo are steadily growing and consuming more and more space. Also, an interrupted build process leaves stalled images. When a git branch or a git tag gets deleted, a set of stages that were built for this image remains in the images repo and stages storage. So, it is necessary to clean up the images repo and stages storage periodically. Otherwise, they will be filled with the stale images.

werf has an efficient multi-level image cleaning system. It supports the following cleaning methods:

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

Cleaning by policies

Cleaning by policies helps to organize automatic periodical cleaning of stuck 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. Cleaning up the images repo cleans images repo from stale images according to the cleaning policies.
  2. Cleaning up stages storage synchronizes stages storage with the images repo.

These steps are combined in the single top-level command cleanup.

An images repo is the primary source of information about actual and stale images. Therefore, it is essential to clean the images repo firstly and only then proceed to the stages storage.

Cleaning up the images repo

werf can automate the cleaning of the images repo. It works according to special rules called cleanup policies. These policies determine which images will be deleted while leaving all others intact.

Cleanup policies

  • by branches:
    • Each new commit updates an image for the corresponding git branch (in other words, there is the only one docker tag for each published git branch).
    • werf deletes an image from the images repo if the corresponding git branch does not exist. The image is never removed as long as the corresponding git branch exists.
    • The policy covers images tagged by werf with the --tag-git-branch option.
  • by commits:
    • werf deletes an image from the images repo if 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 number of days since the image was published. The republished image will be kept for the specified maximum number of days since the new publication date. No days limit is set by default; -1 disables the limit. The value can be specified by --git-commit-strategy-expiry-days option or $WERF_GIT_COMMIT_STRATEGY_EXPIRY_DAYS.
      • git-commit-strategy-limit. Keep the specified max number of published images in the images repo. No limit is set 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 the --tag-git-commit flag.
  • by tags:
    • werf deletes an image from the 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 number of days since the image was published. The republished image will be kept for the specified maximum number of days since the new publication date. No days limit is set 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 the specified max number of published images in the images repo. No limit is set 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 flag.

Please note that cleanup affects only images built and published by werf with one of the following arguments: --tag-git-branch, --tag-git-tag or --tag-git-commit. All other images in the images repo stay intact.

Whitelisting images

The image always remains in the images repo as long as the Kubernetes object that uses the image exists. werf scans the following kinds of objects in the Kubernetes cluster: pod, deployment, replicaset, statefulset, daemonset, job, cronjob, replicationcontroller.

The functionality can be disabled via the flag --without-kube.

Connecting to Kubernetes

werf uses the kube configuration file ~/.kube/config to learn about Kubernetes clusters and ways to connect to them. werf connects to all Kubernetes clusters defined in all contexts of the kubectl configuration to gather information about the images that are in use.

Cleaning up stages storage

Executing a stages storage cleanup command is necessary to synchronize the state of stages storage with the images repo. During this step, werf deletes stages that do not relate to images currently present in the images repo.

If the images cleanup command, — the first step of cleaning by policies, — is skipped, then the stages storage cleanup will not have any effect.

Manual cleaning

The manual cleaning approach assumes one-step cleaning with the complete removal of images from the stages storage or images repo. This method does not check whether the image is used by Kubernetes or not. Manual cleaning is not recommended for the scheduled usage (use cleaning by policies instead). In general, it is best suited for forceful image removal.

The manual cleaning approach includes the following options:

These steps are combined in a single top-level command purge.

Host cleaning

You can clean up the host machine with the following commands: