feat(docs): new usage build chapter structure

Signed-off-by: Timofey Kirillov <timofey.kirillov@flant.com>
werf · Dec 14, 2022 · 78370b0 · 78370b0
1 parent 9524ec3
commit 78370b0
Show file tree

Hide file tree

Showing 27 changed files with 93 additions and 0 deletions.
diff --git a/docs/pages_en/usage/build_draft/building.md b/docs/pages_en/usage/build_draft/building.md
@@ -0,0 +1,6 @@
+---
+title: Build process
+permalink: usage/build_draft/building.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_en/usage/build_draft/images.md b/docs/pages_en/usage/build_draft/images.md
@@ -0,0 +1,6 @@
+---
+title: Images configuration
+permalink: usage/build_draft/images.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_en/usage/build_draft/overview.md b/docs/pages_en/usage/build_draft/overview.md
@@ -0,0 +1,6 @@
+---
+title: Overview
+permalink: usage/build_draft/overview.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_en/usage/build_draft/stapel.md b/docs/pages_en/usage/build_draft/stapel.md
@@ -0,0 +1,6 @@
+---
+title: Stapel
+permalink: usage/build_draft/stapel.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_en/usage/build_draft/storage.md b/docs/pages_en/usage/build_draft/storage.md
@@ -0,0 +1,6 @@
+---
+title: Storage layout
+permalink: usage/build_draft/storage.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_ru/usage/build/build_process.md b/docs/pages_ru/usage/build/build_process.md
@@ -3,6 +3,8 @@ title: Процесс сборки
 permalink: usage/build/build_process.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 Сборочный процесс werf для образов, описанных в [werf.yaml]({{ "reference/werf_yaml.html" | true_relative_url }}), подразумевает [последовательную сборку стадий]({{ "usage/build/stages_and_storage.html" | true_relative_url }}#конвеер-стадий) для описанных образов.
 
 Несмотря на то, что [_конвейеры стадий_]({{ "usage/build/stages_and_storage.html#конвеер-стадий" | true_relative_url }}) для Dockerfile-образа, Stapel-образа и Stapel-артефакта отличаются, каждая стадия подчиняется общим правилам [выборки из хранилища](#выборка-стадий), [сохранения](#сохранение-стадий-в-хранилище), а также [работы кеша и блокировок]({{ "usage/build/synchronization.html" | true_relative_url }}) в параллельных запусках.

diff --git a/docs/pages_ru/usage/build/buildah_mode.md b/docs/pages_ru/usage/build/buildah_mode.md
@@ -3,6 +3,8 @@ title: Режим сборки с использованием Buildah
 permalink: usage/build/buildah_mode.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 > ПРИМЕЧАНИЕ: werf поддерживает сборку образов с _использованием Docker-сервера_ или _с использованием Buildah_. Поддерживается сборка как Dockerfile-образов, так и stapel-образов через Buildah.
 
 Для сборки без Docker-сервера werf использует встроенный Buildah в rootless-режиме.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/artifacts.md b/docs/pages_ru/usage/build/building_images_with_stapel/artifacts.md
@@ -5,6 +5,8 @@ author: Alexey Igrychev <alexey.igrychev@flant.com>
 directive_summary: artifact
 ---
 
+<!-- TODO: remove legacy page -->
+
 ## Что такое артефакты?
 
 ***Артефакт*** — это специальный образ, используемый в других артефактах или отдельных образах, описанных в конфигурации. Артефакт предназначен преимущественно для отделения ресурсов инструментов сборки от процесса сборки образа приложения. Примерами таких ресурсов могут быть — программное обеспечение или данные, которые необходимы для сборки, но не нужны для запуска приложения, и т.п.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/assembly_instructions.md b/docs/pages_ru/usage/build/building_images_with_stapel/assembly_instructions.md
@@ -4,6 +4,8 @@ permalink: usage/build/building_images_with_stapel/assembly_instructions.html
 directive_summary: shell_and_ansible
 ---
 
+<!-- TODO: remove legacy page -->
+
 ## Пользовательские стадии
 
 ***Пользовательские стадии*** — это [_стадии_]({{ "usage/build/stages_and_storage.html" | true_relative_url }}) со сборочными инструкциями из [конфигурации]({{ "reference/werf_yaml.html#секция-image" | true_relative_url }}). Другими словами — это стадии, конфигурируемые пользователем (существуют также служебные стадии, которые пользователь конфигурировать не может). В настоящее время существует два вида сборочных инструкций: _shell_ и _ansible_.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/base_image.md b/docs/pages_ru/usage/build/building_images_with_stapel/base_image.md
@@ -5,6 +5,8 @@ author: Alexey Igrychev <alexey.igrychev@flant.com>
 directive_summary: base_image
 ---
 
+<!-- TODO: remove legacy page -->
+
 Пример минимального `werf.yaml`:
 ```yaml
 project: my-project

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/docker_directive.md b/docs/pages_ru/usage/build/building_images_with_stapel/docker_directive.md
@@ -5,6 +5,8 @@ author: Alexey Igrychev <alexey.igrychev@flant.com>
 directive_summary: docker
 ---
 
+<!-- TODO: remove legacy page -->
+
 Инструкции в [Dockerfile](https://docs.docker.com/engine/reference/builder/) можно условно разделить на две группы: сборочные инструкции и инструкции, которые влияют на manifest Docker-образа. 
 Так как werf сборщик использует свой синтаксис для описания сборки, поддерживаются только следующие Dockerfile-инструкции второй группы:
 

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/git_directive.md b/docs/pages_ru/usage/build/building_images_with_stapel/git_directive.md
@@ -4,6 +4,8 @@ permalink: usage/build/building_images_with_stapel/git_directive.html
 directive_summary: git
 ---
 
+<!-- TODO: remove legacy page -->
+
 ## Что такое git mapping?
 
 ***Git mapping*** определяет, какой файл или папка из Git-репозитория должны быть добавлены в конкретное место образа.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/import_directive.md b/docs/pages_ru/usage/build/building_images_with_stapel/import_directive.md
@@ -5,6 +5,8 @@ author: Alexey Igrychev <alexey.igrychev@flant.com>
 directive_summary: import
 ---
 
+<!-- TODO: remove legacy page -->
+
 Из-за используемых инструментов сборки, либо просто из-за исходных файлов, размер конечного образа может увеличиваться в несколько раз. Зачастую эти файлы не нужны в конечном образе. Для решения таких проблем, сообщество Docker предлагает выполнять установки инструментов, сборку и удаление ненужных файлов за один шаг.
 
 Условный пример:

diff --git a/.../pages_ru/usage/build/building_images_with_stapel/integration_with_ssh_agent.md b/.../pages_ru/usage/build/building_images_with_stapel/integration_with_ssh_agent.md
@@ -3,6 +3,8 @@ title: Интеграция с SSH-агентом
 permalink: usage/build/building_images_with_stapel/integration_with_ssh_agent.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 werf необходим ssh-ключ пользователя в следующих случаях:
 
 1. Клонирование удаленного git-репозитория, указанного в файле конфигурации `werf.yaml`.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/mount_directive.md b/docs/pages_ru/usage/build/building_images_with_stapel/mount_directive.md
@@ -5,6 +5,8 @@ author: Artem Kladov <artem.kladov@flant.com>, Alexey Igrychev <alexey.igrychev@
 directive_summary: mount
 ---
 
+<!-- TODO: remove legacy page -->
+
 Довольно часто бывают случаи, когда при сборке у вас появляются файлы которые нет необходимости оставлять в образе, и их нужно исключить. Например:
 - Большинство пакетных менеджеров создают в системе кэш пакетов и служебных файлов.
   - [APT](https://wiki.debian.org/Apt) хранит список пакетов в директории `/var/lib/apt/lists/`.

diff --git a/docs/pages_ru/usage/build/building_images_with_stapel/stage_introspection.md b/docs/pages_ru/usage/build/building_images_with_stapel/stage_introspection.md
@@ -15,6 +15,7 @@ summary: |
   </div>
 ---
 
+<!-- TODO: remove legacy page -->
 
 Написание конфигурации на начальном этапе может вызывать трудности из-за того, что при выполнении инструкций сборки какой-либо стадии не до конца понятно состояние системы в _сборочном контейнере_.
 

diff --git a/docs/pages_ru/usage/build/run_in_container/how_it_works.md b/docs/pages_ru/usage/build/run_in_container/how_it_works.md
@@ -3,6 +3,8 @@ title: Принципы работы
 permalink: usage/build/run_in_containers/how_it_works.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 > ПРИМЕЧАНИЕ: werf поддерживает сборку образов с _использованием Docker-сервера_ или _с использованием Buildah_. Поддерживается сборка как Dockerfile-образов, так и stapel-образов через Buildah.
 
 Общая информация о том, как включить Buildah в werf, доступна на странице [режима сборки с использованием Buildah]({{ "/usage/build/buildah_mode.html" | true_relative_url }}).

diff --git a/docs/pages_ru/usage/build/run_in_container/use_docker_container.md b/docs/pages_ru/usage/build/run_in_container/use_docker_container.md
@@ -3,6 +3,8 @@ title: С помощью контейнеров Docker
 permalink: usage/build/run_in_containers/use_docker_container.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 > ПРИМЕЧАНИЕ: werf поддерживает сборку образов с _использованием Docker-сервера_ или _с использованием Buildah_. Поддерживается сборка как Dockerfile-образов, так и stapel-образов через Buildah.
 
 ## Сборка образов с помощью Buildah (рекомендуемый метод)

diff --git a/docs/pages_ru/usage/build/run_in_container/use_kubernetes.md b/docs/pages_ru/usage/build/run_in_container/use_kubernetes.md
@@ -3,6 +3,8 @@ title: С помощью Kubernetes
 permalink: usage/build/run_in_containers/use_kubernetes.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 > ПРИМЕЧАНИЕ: werf поддерживает сборку образов с _использованием Docker-сервера_ или _с использованием Buildah_. Поддерживается сборка как Dockerfile-образов, так и stapel-образов через Buildah.
 
 ## 1. Подготовьте кластер Kubernetes

diff --git a/docs/pages_ru/usage/build/stages_and_storage.md b/docs/pages_ru/usage/build/stages_and_storage.md
@@ -3,6 +3,8 @@ title: Стадии и хранилище
 permalink: usage/build/stages_and_storage.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 Мы разделили сборочный процесс образов, описанных в файле конфигурации [werf.yaml]({{ "reference/werf_yaml.html" | true_relative_url }}) на этапы, [с четкими функциями и назначением](#зависимости-стадии). Каждый такой этап соответствует промежуточному образу, подобно слоям в Docker. В werf такой этап называется [стадией](#конвеер-стадий), а **конечный образ** соответствует последней собранной стадии для определённого состояния git и конфигурации werf.yaml.
 
 Стадии — это этапы сборочного процесса. ***Стадия*** определяется группой инструкций, указанных в конфигурации. Причем группировка этих инструкций не случайна, имеет определенную логику и учитывает условия и правила сборки. С каждой _стадией_ связан конкретный Docker-образ. Все стадии хранятся в [хранилище](#хранилище).

diff --git a/docs/pages_ru/usage/build/storage_layouts.md b/docs/pages_ru/usage/build/storage_layouts.md
@@ -3,6 +3,8 @@ title: Организация хранилища стадий
 permalink: usage/build/storage_layouts.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 В данной статье описано, как устроено хранилище собираемых образов в werf, какие бывают типы хранилища, какие функции выполняют эти хранилища, а также различные варианты организации хранилища в проекте.
 
 ## Хранилище стадий

diff --git a/docs/pages_ru/usage/build/synchronization.md b/docs/pages_ru/usage/build/synchronization.md
@@ -3,6 +3,8 @@ title: Синхронизация в werf
 permalink: usage/build/synchronization.html
 ---
 
+<!-- TODO: remove legacy page -->
+
 Синхронизация — это группа сервисных компонентов werf, предназначенных для координации нескольких процессов werf при выборке и сохранении стадий в хранилище, а также при публикации образов в репозиторий образов. Существует 2 таких компонента для синхронизации:
 
  1. _Кеш хранилища_ — это внутренний служебный кеш werf, который существенно повышает производительность фазы расчёта стадий в случае, если эти стадии уже есть в хранилище. Кеш хранилища содержит соответствие существующих в хранилище с дайджестом (или другими словами: содержит предварительно рассчитанный шаг алгоритма выборки стадий по дайджесту). Данный кеш является когерентным и werf автоматически сбрасывает его, если будет замечена несостыковка между хранилищем стадий и кешом хранилища.

diff --git a/docs/pages_ru/usage/build_draft/building.md b/docs/pages_ru/usage/build_draft/building.md
@@ -0,0 +1,6 @@
+---
+title: Сборочный процесс
+permalink: usage/build_draft/building.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_ru/usage/build_draft/images.md b/docs/pages_ru/usage/build_draft/images.md
@@ -0,0 +1,6 @@
+---
+title: Конфигурация образов
+permalink: usage/build_draft/images.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_ru/usage/build_draft/overview.md b/docs/pages_ru/usage/build_draft/overview.md
@@ -0,0 +1,6 @@
+---
+title: Обзор
+permalink: usage/build_draft/overview.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_ru/usage/build_draft/stapel.md b/docs/pages_ru/usage/build_draft/stapel.md
@@ -0,0 +1,6 @@
+---
+title: Stapel
+permalink: usage/build_draft/stapel.html
+---
+
+<!-- TODO: new content -->
diff --git a/docs/pages_ru/usage/build_draft/storage.md b/docs/pages_ru/usage/build_draft/storage.md
@@ -0,0 +1,6 @@
+---
+title: Организация хранилища стадий
+permalink: usage/build_draft/storage.html
+---
+
+<!-- TODO: new content -->