from stage 
from: <image[:<tag>]>
fromLatest: <bool>
fromCacheVersion: <arbitrary string>
fromImage: <image name>

Here’s a minimal werf.yaml. It describes an image named example that is based on a base image named alpine:

project: my-project
configVersion: 1
---
image: example
from: alpine

A base image can be declared with from or fromImage directive.

from, fromLatest

The from directive defines the name and tag of a base image. If no tag is specified, the tag defaults to latest.

from: <image>[:<tag>]

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:

fromLatest: true

By default, giterminism does not allow the use of the fromLatest directive (you can read more about it here)

fromImage

In addition to the image from the repository, the base image can also refer to an image defined in the same werf.yaml.

fromImage: <image name>

If the base image is specific to a particular application, it makes sense to store its description together with images 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.

Conveyor with fromImage stages

fromCacheVersion

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 CMD and 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:

  • [] for CMD;
  • [""] for ENTRYPOINT.

On top of that, werf resets (using special empty values) ENTRYPOINT of the base image if the CMD parameter is specified in the configuration (docker.CMD).

Otherwise, the behavior of werf is similar to that of Docker.