from: <image[:<tag>]> fromLatest: <bool> fromCacheVersion: <arbitrary string> fromImage: <image name> fromArtifact: <artifact name>
Here’s a minimal
werf.yaml. It describes a image named
example that is based on a base image named
project: my-project configVersion: 1 --- image: example from: alpine
Base image can be declared with
from directive defines the name and tag of a base image. If absent, tag defaults to
By default, the assembly process does not depend on actual base image digest in the repository, only on from directive value. Thus, changing base image locally or in the repository does not matter if from stage is already exists in storage.
If you want always build the image with actual base image you should use fromLatest directive. fromLatest directive allows connecting the assembly process with the base image digest getting from the repository.
Pay attention, werf uses actual base image digest in stage digest if fromLatest is specified. Thus, the usage of this directive might break the reproducibility of previous builds. If the base image is changed in the registry, all previously built stages become not usable.
- Previous pipeline jobs (e.g. deploy) cannot be retried without the image rebuild after changing base image in the registry.
- If base image is modified unexpectedly it might lead to the inexplicably failed pipeline. For instance, the modification occurs after successful build and the following jobs will be failed due to changing of stages digests alongside base image digest.
If you want to use this directive, you need to disable giterminism mode with
We do not recommend using the actual base image such way. Use a particular unchangeable tag or periodically change fromCacheVersion value to provide controllable and predictable lifecycle of software
fromImage and fromArtifact
Besides using docker image from a repository, the base image can refer to image or artifact, that is described in the same
fromImage: <image name> fromArtifact: <artifact name>
If a base image is specific to a particular application, it is reasonable to store its description with images and artifacts which are used it as opposed to storing the base image in a Docker registry.
Also, this method can be useful if the stages of stage conveyor are not enough for building the image. You can design your stage conveyor.
fromCacheVersion directive allows to manage image reassembly.
fromCacheVersion: <arbitrary string>