from: <image[:<tag>]> fromLatest: <bool> fromCacheVersion: <arbitrary string> fromImage: <image name> fromArtifact: <artifact name>
Here’s a minimal
werf.yaml. It describes an image named
example that is based on a base image named
project: my-project configVersion: 1 --- image: example from: alpine
A base image can be declared with
from directive defines the name and tag of a base image. If no tag is specified, the tag defaults to
By default, the assembly process does not depend on the actual base image digest in the repository, it only depends on the value of the from directive. Thus, changing the base image locally or in the repository will not affect the build as long as the from stage exists in the storage.
Use the fromLatest directive to ensure that the current base image is used. If this directive is set, werf will check for the current digest of the base image in the container registry at each run.
Here is an example of how to use the fromLatest directive:
By default, giterminism does not allow the use of the
fromLatestdirective (you can read more about it here)
fromImage and fromArtifact
In addition to the image from the repository, the base image can also refer to an image or an artifact defined in the same
fromImage: <image name> fromArtifact: <artifact name>
If the base image is specific to a particular application, it makes sense to store its description together with images and artifacts which use it as opposed to storing the base image in a container registry.
This method comes in handy if the stages of the existing stage conveyor are not enough for building the image. Using the image described in the same
werf.yaml as the base image, you can essentially build your own stage conveyor.
As described above, normally the build process actively uses caching. During the build, a werf checks to see if the base image has changed. Depending on the directives used, the digest or the image name and tag are checked for changes. If the image is unchanged, the digest of the from stage is unchanged as well. If there is an image with this digest in the stages storage, it will be used during the build.
You can use the
fromCacheVersion directive to manipulate the digest of the
from stage (since the
fromCacheVersion value is part of the stage digest) and thus force the rebuild of the image. If you modify the value specified in the
fromCacheVersion directive, then regardless of whether the base image (or its digest) is changed or stays the same, the digest of the
from stage (as well as all subsequent stages) will change. This will result in rebuilding all the stages.
fromCacheVersion: <arbitrary string>
How the Stapel builder processes CMD and ENTRYPOINT
To build a stage, werf runs a container with the
ENTRYPOINT service parameters and then substitutes them with the values of the base image. If these values are not set in the base image, werf resets them as follows:
On top of that, werf resets (using special empty values)
ENTRYPOINT of the base image if the
CMD parameter is specified in the configuration (
Otherwise, the behavior of werf is similar to that of Docker.