feat(build): add mutate image spec config feature (#6578)

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>

Author: iapershin

docs/_data/werf_yaml.yml

@@ -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
@@ -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:
@@ -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

docs/_includes/reference/cli/werf_build.md

@@ -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)

docs/_includes/reference/cli/werf_bundle_publish.md

@@ -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)

docs/_includes/reference/cli/werf_converge.md

@@ -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

docs/_includes/reference/cli/werf_export.md

@@ -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)

docs/_includes/reference/cli/werf_helm_get_autogenerated_values.md

@@ -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)

docs/_includes/reference/cli/werf_plan.md

@@ -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

docs/_includes/reference/cli/werf_render.md

@@ -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

docs/pages_en/usage/build/images.md

@@ -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

docs/pages_en/usage/build/stapel/dockerfile.md

@@ -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)).