Skip to content

Commit

Permalink
feat(build): add mutate image spec config feature (#6578)
Browse files Browse the repository at this point in the history
Signed-off-by: Yaroslav Pershin <62902094+iapershin@users.noreply.github.com>
Signed-off-by: Aleksei Igrychev <aleksei.igrychev@palark.com>
Co-authored-by: Aleksei Igrychev <aleksei.igrychev@palark.com>
  • Loading branch information
iapershin and alexey-igrychev authored Feb 1, 2025
1 parent 30b50c4 commit 799193e
Show file tree
Hide file tree
Showing 41 changed files with 1,529 additions and 32 deletions.
166 changes: 164 additions & 2 deletions docs/_data/werf_yaml.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,47 @@ sections:
description:
en: "Enable layer-by-layer caching of Dockerfile instructions in container registry globally for all images"
ru: "Включить послойное кеширование инструкций Dockerfile в container registry глобально для всех образов"
- name: imageSpec
description:
en: Global image configuration options according to the OCI specification, which will be applied to all images
ru: Глобальная конфигурация образов согласно OCI спецификации, которая применяется ко всем образам
collapsible: true
isCollapsedByDefault: false
detailsCustomLinks:
en:
- text: Changing image configuration spec
article: "/usage/build/images.md#changing-image-configuration-spec"
ru:
- text: Изменение конфигурации образов
article: "/usage/build/images.md#изменение-конфигурации-образов"
directives:
- name: author
value: "string"
description:
en: Author of the image
ru: Автор образа
- name: clearHistory
value: "bool"
description:
en: Remove all image build history
ru: Удалить всю историю сборки образа
- name: config
description:
en: Common image configuration
ru: Общая конфигурация образа
collapsible: true
isCollapsedByDefault: false
directives:
- name: clearWerfLabels
value: "bool"
description:
en: Clear werf labels
ru: Сбросить метки werf
- name: removeLabels
value: "[ string || /REGEXP/, ... ]"
description:
en: List of labels to remove
ru: Список меток для удаления
- name: deploy
description:
en: Settings for deployment
Expand Down Expand Up @@ -328,6 +369,126 @@ sections:
description:
en: "Name of build argument which will contain specified type of information about image"
ru: "Имя аргумента (Dockerfile build-args), который будет содержать указанный тип информации об образе"
- &common_image_spec_config
name: imageSpec
description:
en: Image configuration according to the OCI specification
ru: Конфигурация образа согласно OCI спецификации
detailsCustomLinks:
en:
- text: Changing image configuration spec
article: "/usage/build/images.md#changing-image-configuration-spec"
ru:
- text: Изменение конфигурации образов
article: "/usage/build/images.md#изменение-конфигурации-образов"
directives:
- name: author
value: "string"
description:
en: Author of the image
ru: Автор образа
- name: clearHistory
value: "bool"
description:
en: Remove all image build history
ru: Удалить всю историю сборки образа
- name: config
description:
en: Common image configuration
ru: Общая конфигурация образа
collapsible: true
isCollapsedByDefault: false
directives:
- name: clearWerfLabels
value: "bool"
description:
en: Clear werf labels
ru: Сбросить метки werf
- name: removeLabels
value: "[ string || /REGEXP/, ... ]"
description:
en: List of labels to remove
ru: Список меток для удаления
- name: removeVolumes
value: "[string, ...]"
description:
en: List of volumes to remove
ru: Список томов для удаления
- name: removeEnv
value: "[string, ...]"
description:
en: List of environment variables to remove
ru: Список переменных окружения для удаления
- name: clearEntrypoint
value: "bool"
description:
en: Remove ENTRYPOINT
ru: Очистить ENTRYPOINT
- name: clearCmd
value: "bool"
description:
en: Remove CMD
ru: Очистить CMD
- name: volumes
value: "[string, ...]"
description:
en: List of volumes to add
ru: Список томов для добавления
detailsLink: "https://docs.docker.com/engine/reference/builder/#volume"
- name: labels
value: "{ name string: value string, ... }"
description:
en: List of labels to add
ru: Список меток для добавления
detailsLink: "https://docs.docker.com/engine/reference/builder/#label"
- name: env
value: "{ name string: value string, ... }"
description:
en: List of environment variables to add
ru: Список переменных окружения для добавления
detailsLink: "https://docs.docker.com/engine/reference/builder/#env"
- name: expose
value: "[string, ...]"
description:
en: Set exposed ports
ru: Установить порты открытые порты
detailsLink: "https://docs.docker.com/engine/reference/builder/#expose"
- name: user
value: "string"
description:
en: Set user
ru: Установить пользователя
detailsLink: "https://docs.docker.com/engine/reference/builder/#user"
- name: cmd
value: "[string, ...]"
description:
en: Set CMD
ru: Установить CMD
detailsLink: "https://docs.docker.com/engine/reference/builder/#cmd"
- name: entrypoint
value: "[string, ...]"
description:
en: Set ENTRYPOINT
ru: Установить ENTRYPOINT
detailsLink: "https://docs.docker.com/engine/reference/builder/#entrypoint"
- name: workingDir
value: "string"
description:
en: Set WORKDIR
ru: Установить WORKDIR
detailsLink: "https://docs.docker.com/engine/reference/builder/#workdir"
- name: stopSignal
value: "string"
description:
en: Set STOPSIGNAL
ru: Установить STOPSIGNAL
detailsLink: "https://docs.docker.com/engine/reference/builder/#stopsignal"
- name: healthcheck
value: "{ test: [string, ...], interval: string, retries: int }"
description:
en: Healthcheck configuration. Intervals are in seconds.
ru: Конфигурация проверки состояния. Интервалы в секундах.
detailsLink: "https://docs.docker.com/engine/reference/builder/#healthcheck"

- id: stapel-section
description:
Expand Down Expand Up @@ -655,10 +816,11 @@ sections:
detailsArticle:
en: "/usage/build/stapel/instructions.html#dependency-on-the-cacheversion"
ru: "/usage/build/stapel/instructions.html#зависимость-от-значения-cacheversion"
- <<: *common_image_spec_config
- name: docker
description:
en: "Set of directives to effect on an image manifest"
ru: "Набор директив для изменения манифеста образа"
en: "Set of directives to change the image manifest (DEPRECATED). Incompatible with the imageSpec directive"
ru: "Набор директив для изменения манифеста образа (DEPRECATED). Несовместимо с директивой imageSpec"
detailsArticle:
all: "/usage/build/stapel/dockerfile.html"
collapsible: true
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_build.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ werf build [IMAGE_NAME...] [options]
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-config=''
Kubernetes config file path (default $WERF_KUBE_CONFIG, or $WERF_KUBECONFIG, or
$KUBECONFIG)
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_bundle_publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ werf bundle publish [IMAGE_NAME...] [options]
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-config=''
Kubernetes config file path (default $WERF_KUBE_CONFIG, or $WERF_KUBECONFIG, or
$KUBECONFIG)
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_converge.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ werf converge --repo registry.mydomain.com/web --env production
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-api-server=''
Kubernetes API server address (default $WERF_KUBE_API_SERVER)
--kube-burst-limit=100
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_export.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ werf export [IMAGE_NAME...] [options]
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-config=''
Kubernetes config file path (default $WERF_KUBE_CONFIG, or $WERF_KUBECONFIG, or
$KUBECONFIG)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ werf helm get-autogenerated-values [IMAGE_NAME...] [options]
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-config=''
Kubernetes config file path (default $WERF_KUBE_CONFIG, or $WERF_KUBECONFIG, or
$KUBECONFIG)
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ werf plan --repo registry.mydomain.com/web --env production
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-api-server=''
Kubernetes API server address (default $WERF_KUBE_API_SERVER)
--kube-burst-limit=100
Expand Down
2 changes: 1 addition & 1 deletion docs/_includes/reference/cli/werf_render.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ werf render [IMAGE_NAME...] [options]
STAGE_NAME should be one of the following: from, beforeInstall,
dependenciesBeforeInstall, gitArchive, install, dependenciesAfterInstall, beforeSetup,
dependenciesBeforeSetup, setup, dependenciesAfterSetup, gitCache, gitLatestPatch,
dockerInstructions, dockerfile
dockerInstructions, dockerfile, imageSpec
--kube-api-server=''
Kubernetes API server address (default $WERF_KUBE_API_SERVER)
--kube-burst-limit=100
Expand Down
91 changes: 91 additions & 0 deletions docs/pages_en/usage/build/images.md
Original file line number Diff line number Diff line change
Expand Up @@ -382,6 +382,97 @@ import:

For more info on how to write Stapel instructions refer to the [documentation]({{"usage/build/stapel/base.html" | true_relative_url }}).

## Changing image configuration spec

In OCI (Open Container Initiative), [image configuration spec](https://github.com/opencontainers/image-spec/blob/main/config.md) is the image specification that describes its structure and metadata. The `imageSpec` directive in `werf.yaml` provides flexible options for managing and configuring various aspects of images:

- Flexibility in managing specification fields.
- Removal or resetting of unnecessary components: labels, environment variables, volumes, commands, and build history.
- A unified configuration mechanism for all supported backends and syntaxes.
- Rules that apply both to all images in a project and to individual images.

### Global configuration

Example configuration that will apply to all images in the project:

```yaml
project: test
configVersion: 1
build:
imageSpec:
author: "Frontend Maintainer <frontend@example.com>"
clearHistory: true
config:
removeLabels:
- "unnecessary-label"
- /org.opencontainers.image..*/
labels:
app: "my-app"
```

This configuration will be applied to all images in the project: labels and author will be set for all images, and unnecessary labels will be removed.

### Configuration for a specific image

Example configuration for an individual image:

```yaml
project: test
configVersion: 1
---
image: frontend_image
from: alpine
imageSpec:
author: "Frontend Maintainer <frontend@example.com>"
clearHistory: true
config:
user: "1001:1001"
exposedPorts:
- "8080/tcp"
env:
NODE_ENV: "production"
API_URL: "https://api.example.com"
entrypoint:
- "/usr/local/bin/start.sh"
volumes:
- "/app/data"
workingDir: "/app"
labels:
frontend-version: "1.2.3"
stopSignal: "SIGTERM"
removeLabels:
- "old-frontend-label"
- /old-regex-label.*/
removeVolumes:
- "/var/cache"
removeEnv:
- "DEBUG"
```

> **Note:** Configuration for a specific image takes precedence over global configuration. String values will be overwritten, and for multi-valued directives, the data will be merged based on priority.

### Build process changes

Changing the image configuration does not directly affect the build process but allows you to configure aspects such as removing unnecessary volumes or adding environment variables for the base image. Example:

```yaml
image: base
from: postgres:12.22-bookworm
imageSpec:
config:
removeVolumes:
- "/var/lib/postgresql/data"
---
image: app
fromImage: base
git:
add: /postgresql/data
to: /var/lib/postgresql/data
```

In this example, the base image `postgres:12.22-bookworm` has unnecessary volumes removed, which can then be used in the `app` image.


## Linking images

### Inheritance and importing files
Expand Down
2 changes: 2 additions & 0 deletions docs/pages_en/usage/build/stapel/dockerfile.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ author: Alexey Igrychev <alexey.igrychev@flant.com>
directive_summary: docker
---

> The `docker` directive is deprecated and will be removed in v3. Please use the `imageSpec` directive instead. Read more about the `imageSpec` directive [here]({{ "usage/build/images.html#changing-image-configuration-spec" | true_relative_url }}).
[Dockerfile instructions](https://docs.docker.com/engine/reference/builder/) can be divided into two groups: build-time instructions and other instructions affecting an image manifest. Build-time instructions do not make sense in a werf build process. Thus, werf supports only following instructions:

* `USER` to set the user name (or UID) and optionally the user group (or GID) (read more [here](https://docs.docker.com/engine/reference/builder/#user)).
Expand Down
Loading

0 comments on commit 799193e

Please sign in to comment.