Synchronization is a group of service components of the werf to coordinate multiple werf processes when selecting and publishing stages into storage. There are 2 such synchronization components:

  1. Stages storage cache is an internal werf cache, which significantly improves performance of the werf invocations when stages already exists in the storage. Stages storage cache contains the mapping of stages existing in storage by the digest (or in other words this cache contains precalculated result of stages selection by digest algorithm). This cache should be coherent with storage itself and werf will automatically reset this cache automatically when detects an inconsistency between storage cache and storage.
  2. Lock manager. Locks are needed to organize correct publishing of new stages into storage, publishing images into images-repo and for concurrent deploy processes that uses the same release name.

All commands that requires storage (--repo) param also use synchronization service components address, which defined by the --synchronization option or WERF_SYNCHRONIZATION=... environment variable.

There are 3 types of sycnhronization components:

  1. Local. Selected by --synchronization=:local param.
    • Local storage cache is stored in the ~/.werf/shared_context/storage/stages_storage_cache/1/PROJECT_NAME/DIGEST files by default, each file contains a mapping of images existing in storage by some digest.
    • Local lock manager uses OS file-locks in the ~/.werf/service/locks as implementation of locks.
  2. Kubernetes. Selected by --synchronization=kubernetes://NAMESPACE[:CONTEXT][@(base64:CONFIG_DATA)|CONFIG_PATH] param.
    • Kubernetes storage cache is stored in the specified NAMESPACE in ConfigMap named by project cm/PROJECT_NAME.
    • Kubernetes lock manager uses ConfigMap named by project cm/PROJECT_NAME (the same as storage cache) to store distributed locks in the annotations. Lockgate library is used as implementation of distributed locks using kubernetes resource annotations.
  3. Http. Selected by --synchronization=http[s]://DOMAIN param.
    • There is a public instance of synchronization server available at domain https://synchronization.werf.io.
    • Custom http synchronization server can be run with werf synchronization command.

werf uses --synchronization=:local (local storage cache and local lock manager) by default when local storage is used.

werf uses --synchronization=https://synchronization.werf.io (http storage cache and http lock manager) by default when container registry is used as storage.

User may force arbitrary non-default address of synchronization service components if needed using explicit --synchronization=:local|(kubernetes://NAMESPACE[:CONTEXT][@(base64:CONFIG_DATA)|CONFIG_PATH])|(http[s]://DOMAIN) param.

NOTE: Multiple werf processes working with the same project should use the same storage and synchronization.