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

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

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

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

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

from, fromLatest

Директива from определяет имя и тег базового образа. Если тег не указан, то по умолчанию — latest.

from: <image>[:<tag>]

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

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

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

fromLatest: true
herebyIAdmitThatFromLatestMightBreakReproducibility: true

Обратите внимание, что если вы включаете fromLatest, то werf начинает использовать digest актуального базового образа при подсчете сигнатуры стадии from. Это может приводить к неконтролируемым сменам сигнатур стадий: все образы стадий, собранные ранее, становятся неактуальными, если меняется базовый образ в репозитории. Примеры проблем, которые может вызвать это поведение в CI процессах (например, в pipeline GitLab):

  • Сборка прошла успешно, но затем обновляется базовый образ, и следующие задания pipeline (например, деплой) уже не работают. Это происходит потому, что еще не существует конечного образа, собранного с учетом обновленного базового образа.
  • Собранное приложение успешно развернуто, но затем обновляется базовый образ, и повторный запуск деплоя уже не работает. Это также происходит потому, что еще не существует конечного образа, собранного с учетом обновленного базового образа.

Если вы всё же хотите использовать функционал данной директивы, добавьте также параметр herebyIAdmitThatFromLatestMightBreakReproducibility: true рядом с параметром fromLatest.

Крайне не рекоммендуется использовать актуальный базовый образ таким способом. Используйте конкретный неизменный tag или переодически обновляйте значение fromCacheVersion для обеспечения предсказуемого и контролируемого жизненного цикла приложения

fromImage и fromImageArtifact

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

fromImage: <image name>
fromImageArtifact: <artifact name>

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

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

fromCacheVersion

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

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

fromCacheVersion: <arbitrary string>