werf has a built-in alternative syntax for describing assembly instructions called Stapel. Here are its distinctive features:

  1. Easily support and parameterize complex configurations, reuse common snippets and generate configurations of the images of the same type using YAML format and templating.
  2. Dedicated commands for integrating with Git to enable incremental rebuilds based on the Git repository history.
  3. Image inheritance and importing files from images (similar to the Dockerfile multi-stage mechanism).
  4. Run arbitrary build instructions, specify directory mount options, and use other advanced tools to build images.
  5. More efficient caching mechanics for layers (a similar scheme is supported for Dockerfile layers when building with Buildah (currently pre-alpha)).

To build images using the Stapel builder, you have to define build instructions in the werf.yaml configuration file. Stapel is supported for both the Docker server builder backend (assembly via shell instructions or Ansible) and for Buildah (shell instructions only).

This section describes how to build images with the Stapel builder, its advanced features and how to use them.

How the Stapel stage conveyor works

A stage conveyor is an ordered sequence of conditions and rules for running stages. werf uses different stage conveyors to assemble various types of images, depending on their configuration.

Stapel Image Stapel Artifact

For each stage at every build, werf calculates a unique stage identifier called stage digest.

If a stage has no stage dependencies, it is skipped, and the stage conveyor gets reduced by one stage as a result. This means that the stage conveyor can be reduced to several stages or even to a single from stage.

Stage dependency is a piece of data that affects the stage digest. Stage dependencies include:

  • files from the Git repository with their contents;
  • instructions to build stage defined in the werf.yaml;
  • an arbitrary string specified by the user in the werf.yaml;
  • and so on.

Most stage dependencies are specified in the werf.yaml, others originate from the runtime.

The tables below illustrate dependencies of a Dockerfile image, a Stapel image, and a Stapel artifact stage dependencies. Each row covers the dependencies for a certain stage. The left column contains a brief description of the dependencies, the right column includes the related werf.yaml directives and contains links to sections with more details.

Stapel Image Stapel Artifact

stage dockerfile

target dockerfile instructions
hashsum of files related with ADD and COPY dockerfile instructions
args used in target dockerfile instructions
addHost 
image: <image name... || ~>
dockerfile: <relative path>
context: <relative path>
target: <docker stage name>
args:
  <build arg name>: <value>
addHost:
- <host:ip>

stage from

from
or from image stages-digest
or from artifact stages-digest
actual digest from registry (if fromLatest: true)
fromCacheVersion
mounts 
from: <image[:<tag>]>
fromLatest: <bool>
fromCacheVersion: <arbitrary string>
fromImage: <image name>
mount:
- from: build_dir
  to: <absolute or relative path>
- from: tmp_dir
  to: <absolute path>
- fromPath: <absolute or relative path>
  to: <absolute path>
References:

stage beforeInstall

beforeInstall bash commands or ansible tasks
cacheVersion
beforeInstallCacheVersion 
shell:
  beforeInstall:
  - <bash command>
  cacheVersion: <arbitrary string>
  beforeInstallCacheVersion: <arbitrary string>

or

ansible:
  beforeInstall:
  - <task>
  cacheVersion: <arbitrary string>
  beforeInstallCacheVersion: <arbitrary string>
References:

stage dependenciesBeforeInstall

dependencies before install 
import:
- image: <image name>
  before: install
  add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
References:

stage gitArchive

git mappings 
git:
- add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
- url: <git repo url>
  branch: <branch name>
  commit: <commit>
  tag: <tag>
  add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
References:

stage install

install bash commands or ansible tasks
installCacheVersion
git files hashsum by install stageDependency 
git:
- stageDependencies:
    install:
    - <relative path or glob>

shell:
  install:
  - <bash command>
  installCacheVersion: <arbitrary string>

or

ansible:
  install:
  - <task>
  installCacheVersion: <arbitrary string>
References:

stage dependenciesAfterInstall

dependencies after install 
import:
- image: <image name>
  after: install
  add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
References:

stage beforeSetup

beforeSetup bash commands or ansible tasks
beforeSetupCacheVersion
git files hashsum by beforeSetup stageDependency 
git:
- stageDependencies:
    beforeSetup:
    - <relative path or glob>

shell:
  beforeSetup:
  - <bash command>
  beforeSetupCacheVersion: <arbitrary string>

or

ansible:
  beforeSetup:
  - <task>
  beforeSetupCacheVersion: <arbitrary string>
References:

stage dependenciesBeforeSetup

dependencies before setup 
import:
- image: <image name>
  before: setup
  add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
References:

stage setup

setup bash commands or ansible tasks
setupCacheVersion
git files hashsum by setup stageDependency 
git:
- stageDependencies:
    setup:
    - <relative path or glob>

shell:
  setup:
  - <bash command>
  setupCacheVersion: <arbitrary string>

or

ansible:
  setup:
  - <task>
  setupCacheVersion: <arbitrary string>
References:

stage gitCache

size of git diff between last used commit and actual
References:

stage dependenciesAfterSetup

dependencies after setup 
import:
- image: <image name>
  after: setup
  add: <absolute path>
  to: <absolute path>
  owner: <owner>
  group: <group>
  includePaths:
  - <relative path or glob>
  excludePaths:
  - <relative path or glob>
References:

stage gitLatestPatch

presence of git diff changes between last used commit and actual
References:

stage dockerInstructions

docker instructions 
docker:
  VOLUME:
  - <volume>
  EXPOSE:
  - <expose>
  ENV:
    <env name>: <env value>
  LABEL:
    <label name>: <label value>
  ENTRYPOINT: <entrypoint>
  CMD: <cmd>
  WORKDIR: <workdir>
  USER: <user>
  HEALTHCHECK: <healthcheck>
References: