from: <image[:<tag>]>
fromLatest: <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>
