Базовый образ

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

Пример минимального werf.yaml:

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

Приведенная конфигурация описывает образ example, базовым образом для которого является образ с именем alpine.

Базовый образ может быть указан с помощью директив from или fromImage.

from

Директива from указывает базовый образ: либо другой образ, определённый в werf.yaml (например, backend), либо внешний образ с тегом или дайджестом (например, nginx:1.25, nginx@sha256:901ee6541a7940897742572ac4709cd23a587509879f1b1202ce1f634a20b0db).

Использование внешних образов

При использовании внешнего образа, если тег не указан, то по умолчанию используется — latest:

from: <image>[:<tag>]

По умолчанию процесс сборки не зависит от digest базового образа, а зависит только от значения директивы from. Поэтому изменение базового образа в локальном хранилище или в container registry не будет влиять на сборку, пока стадия from, с указанным значением образа, находится в stages storage.

Если вам нужна проверка digest образа чтобы всегда использовать актуальный базовый образ, вы можете использовать директиву fromLatest. Это приведет к тому, что при каждом запуске werf будет проверяться актуальный digest базового образа в container registry.

Пример использования директивы fromLatest:

fromLatest: true

По умолчанию использование директивы fromLatest запрещено гитерминизмом (подробнее об этом в статье)

Использование образов проекта

В качестве базового образа можно указывать не только образ из локального хранилища или container registry, но и имя другого образа, описанного в том же файле werf.yaml.

from: <image name>

Если базовый образ уникален для конкретного приложения, то рекомендуемый способ — хранить его описание в конфигурации приложения (в файле werf.yaml) как отдельный образ вместо того, чтобы ссылаться на Docker-образ.

Также эта рекомендация будет полезной, если вам по каким-либо причинам не хватает существующего конвейера стадий. Используя в качестве базового образа образ, описанный в том же werf.yaml, вы по сути можете построить свой конвейер стадий.

fromCacheVersion

Как описано выше, в обычном случае процесс сборки активно использует кэширование. При сборке выполняется проверка — изменился ли базовый образ. В зависимости от используемых директив эта проверка на изменение digest или имени и тега образа. Если образ не изменился, то дайджест стадии from остается прежним, и если в stages storage есть образ с таким дайджестом, то он и будет использован при сборке.

С помощью директивы fromCacheVersion вы можете влиять на дайджест стадии from (т.к. значение fromCacheVersion — это часть дайджеста стадии) и, таким образом, управлять принудительной пересборкой образа. Если вы измените значение, указанное в директиве fromCacheVersion, то независимо от того, менялся базовый образ (или его digest) или остался прежним, при сборке изменится дайджест стадии from и, соответственно, всех последующих стадий. Это приведет к тому, что сборка всех стадий будет выполнена повторно.

fromCacheVersion: <arbitrary string>

Как stapel-сборщик работает с CMD и ENTRYPOINT из базового образа

Для сборки стадии werf запускает контейнер со служебными значениями CMD и ENTRYPOINT, а затем заменяет их значениями базового образа. Если в базовом образе эти значения не установлены, werf сбрасывает их следующим образом:

• [] для CMD;
• [""] для ENTRYPOINT.

Также werf сбрасывает (использует специальные пустые значения) значение ENTRYPOINT базового образа, если указано значение CMD в конфигурации (docker.CMD).

В противном случае поведение werf аналогично поведению Docker.