diff --git a/docs/_data/sidebars/_documentation.yml b/docs/_data/sidebars/_documentation.yml index d9a8e9dc40..cac8ca3e47 100644 --- a/docs/_data/sidebars/_documentation.yml +++ b/docs/_data/sidebars/_documentation.yml @@ -17,39 +17,19 @@ entries: - title: Build f: - - title: Overview (NEW) + - title: Overview url: /usage/build_draft/overview.html - - title: Images configuration (NEW) + - title: Image configuration url: /usage/build_draft/images.html - title: Build process - url: /usage/build/build_process.html - - - title: Stages and storage - url: /usage/build/stages_and_storage.html - - - title: Storage layouts - url: /usage/build/storage_layouts.html - - - title: Buildah mode - url: /usage/build/buildah_mode.html - - - title: Synchronization in werf - url: /usage/build/synchronization.html - - - title: Run in containers - f: - - title: How it works - url: /usage/build/run_in_containers/how_it_works.html - - - title: Use Docker container - url: /usage/build/run_in_containers/use_docker_container.html + url: /usage/build_draft/building.html - - title: Use Kubernetes - url: /usage/build/run_in_containers/use_kubernetes.html + - title: Storage layout + url: /usage/build_draft/storage.html - - title: Building images with Stapel (UPDATED) + - title: Building images with Stapel f: - title: Overview url: /usage/build_draft/stapel/overview.html @@ -173,42 +153,19 @@ entries: - title: Сборка f: - - title: Обзор (NEW) + - title: Обзор url: /usage/build_draft/overview.html - - title: Конфигурация образов (NEW) + - title: Конфигурация образов url: /usage/build_draft/images.html - - title: Сборочный процесс (NEW) + - title: Сборочный процесс url: /usage/build_draft/building.html - - title: Процесс сборки - url: /usage/build/build_process.html - - - title: Стадии и хранилище - url: /usage/build/stages_and_storage.html - - title: Организация хранилища стадий - url: /usage/build/storage_layouts.html - - - title: Buildah - url: /usage/build/buildah_mode.html - - - title: Синхронизация в werf - url: /usage/build/synchronization.html - - - title: Запуск в контейнерах - f: - - title: Принципы работы - url: /usage/build/run_in_containers/how_it_works.html - - - title: В Docker-контейнере - url: /usage/build/run_in_containers/use_docker_container.html - - - title: В Kubernetes - url: /usage/build/run_in_containers/use_kubernetes.html + url: /usage/build_draft/storage.html - - title: Сборка образов с помощью Stapel (NEW) + - title: Сборка образов с помощью Stapel f: - title: Обзор url: /usage/build_draft/stapel/overview.html diff --git a/docs/pages_ru/usage/build_draft/all_in_one.md b/docs/pages_ru/usage/build_draft/all_in_one.md index 6a26ce2ea3..ce8d03894e 100644 --- a/docs/pages_ru/usage/build_draft/all_in_one.md +++ b/docs/pages_ru/usage/build_draft/all_in_one.md @@ -13,99 +13,6 @@ ## Организация хранилища -В данной статье описано, как устроено хранилище собираемых образов в werf, какие бывают типы хранилища, какие функции выполняют эти хранилища, а также различные варианты организации хранилища в проекте. - -### Типы хранилища - -#### Первичный репозиторий - -* Задаётся параметром `--repo` (или переменной окружения `WERF_REPO`). -* У проекта всегда есть только один такой репозиторий. - -Данное хранилище является основным и объединяет в себе несколько функций: - -1. История проекта. - - Хранилище метаданных, связанных с Git-репозиторием, для собираемых образов и стадий. - - История проекта позволяет реализовать продвинутый алгоритм безопасной очистки старых стадий на основе истории Git-репозитория (команда `werf cleanup`). -1. Синхронизация сборки в распределённом окружении. - - Данное хранилище позволяет запускать сборку в распределённом окружении и эффективно переиспользовать собираемые стадии в таком окружении. Это возможно за счёт механизмов распределённой синхронизации, встроенных в werf. Эти механизмы работают исключительно с первичным репозиторием. - - Как только стадия попадает в первичный репозиторий, эта стадия может быть переиспользована другими сборочными процессами, которые могут быть запущены с произвольного хоста. -1. Сборочный кэш ранее собранных стадий. - - Ранее собранные стадии по возможности переиспользуются вместо того, чтобы собираться заново. - - Данная функция схожа с привычным локальным сборочным кэшом в Docker server, однако в случае werf этот кэш находится в container registry. -1. Хранилище финальных образов, используемых при запуске приложения в Kubernetes. - - Kubernetes будет скачивать образы из этого репозитория для запуска контейнеров приложения. - - В качестве финальных образов напрямую используются те же стадии, из которых состоит собранный образ. - -**Очистка (ВАЖНО!).** Для корректной и полноценной работы werf первичный репозиторий должен быть надёжным (persistent) хранилищем, образы из которого удаляются лишь специальной командой очистки `werf cleanup`. Первичный репозиторий — это не просто сборочный кэш проекта, но и хранилище его истории, похожее на историю коммитов в Git-репозитории. - -Помимо первичного репозитория в werf есть другие типы репозиториев, которые могут выполнять часть его функций. Они будут рассмотрены далее. Стоит помнить, что **без первичного репозитория werf не работает, а все другие репозитории — дополнительные**; они были созданы, чтобы снять часть функций первичного репозитория в вашей инсталляции проекта. - -#### Вторичный репозиторий - -* Задаётся параметром `--secondary-repo` (или переменной окружения `WERF_SECONDARY_REPO_`). -* Может быть указан один или несколько таких репозиториев. - -Данное хранилище — это репозиторий только для чтения (read-only), выполняющий функцию сборочного кэша ранее собранных стадий *(см. функции [первичного репозитория](#первичный-репозиторий))*. - -Как правило, в качестве secondary-repo может быть указан уже существующий первичный репозиторий от другой инсталляции проекта. Отсутствующие стадии по мере необходимости будут скопированы из вторичного репозитория в первичный вместо сборки с нуля. Вновь собранные же стадии будут помещены только в первичный репозиторий, потому что вторичный репозиторий всегда read-only, т.е. мы не имеем права в него записывать новые данные. - -**Очистка** вторичного репозитория не требуется, т.к. этот репозиторий в то же время является первичным для другой инсталляции проекта и его данные управляются там. - -#### Кэширующий репозиторий - -* Задаётся параметром `--cache-repo` (или переменной окружения `WERF_CACHE_REPO_`). -* Может быть указан один или несколько таких репозиториев. - -Выполняет функцию сборочного кэша ранее собранных стадий *(см. функции [первичного репозитория](#первичный-репозиторий))*. Кэширующий репозиторий отличается от вторичного тем, что он read-write, т.е. используется как для записи новых стадий в кэш, так и для использования собранных стадий из этого кэша. - -Существующие стадии будут скопированы из кэширующего репозитория в первичный, поскольку первичный репозиторий обязан содержать все собранные стадии образов проекта. Вновь собранные стадии будут опубликованы и в первичный репозиторий, и в кэширующий репозиторий. - -Стадии, которые используются в качестве базовых для сборки новых стадий: -* будут скачиваться из кэша, -* если их нет в кэширующем репозитории — будут скачиваться из первичного репозитория, а затем загружены в кэширующий для дальнейшего использования. - -Другими словами, кэширующий репозиторий заполняется не только вновь собираемыми стадиями, но и базовыми стадиями, используемыми для сборки новых стадий. - -Кэширующий репозиторий никогда не используется при запуске приложения в Kubernetes. - -**Очистка** кэширующего репозитория осуществляется путём его полного удаления. После очистки такой репозиторий будет вновь наполнен актуальными часто используемыми данными. - -#### Финальный репозиторий - -* Задаётся параметром `--final-repo` (или переменной окружения `WERF_FINAL_REPO`). -* Может быть указан только один такой репозиторий. - -Данный репозиторий будет использоваться исключительно для публикации финальных образов, задействованных для деплоя приложения в Kubernetes. -- Вновь собираемые образы попадают сначала в первичный репозиторий, и затем копируются в финальный. -- Финальный репозиторий никогда не хранит промежуточные стадии образов, в нем есть лишь последняя стадия образа. -- Финальный репозиторий никогда не хранит промежуточные образы (артефакты), нужные для сборки конечных образов. Сюда попадают только конечные образы, используемые в Kubernetes. - -**Очистка** данного репозитория выполняется командой `werf cleanup` в паре с первичным репозиторием (для этого необходимо указывать два параметра команде `werf cleanup`: `--repo` и `--final-repo`). - -### Примеры организации хранилища стадий - -Рассмотрим варианты использования и комбинации описанных репозиториев. Стоит отметить, что любой из описанных вариантов требует указания [первичного репозитория](#первичный-репозиторий). - -#### 1. Стандарт - -* **Первичный** репозиторий доступен со всех сборочных хостов, а также из кластера Kubernetes. Другие репозитории не используются. -* При сборке образов сборочный кэш будет скачиваться и загружаться в первичный репозиторий. При выкате Kubernetes будет скачивать финальные образы приложения из данного репозитория. -* В большинстве случаев следует использовать именно эту простую схему. Также данная схема подходит, если нет уверенности в том, что требуется для проекта. - -#### 2. Дополнительный кэш в локальной сети - -* **Первичный** репозиторий доступен со всех сборочных хостов, а также из кластера Kubernetes. -* **Кэширующий** репозиторий работает в локальной сети с быстрым доступом. -* При сборке образов сборочный кэш загружается и в первичный репозиторий, и в кэширующий репозиторий. Стадии образов, требуемые для сборки других стадий, будут скачиваться из кэширующего репозитория. - -#### 3. Полная оптимизация - -* **Первичный** репозиторий располагается в локальной сети с быстрым доступом и доступен со всех сборочных хостов. Доступ к данному репозиторию из кластера Kubernetes не требуется. В отличие от кэширующего репозитория, первичный не может быть полностью очищен или удалён без последствий для работы werf, поэтому требуется обеспечить персистивность и надёжность данного хранилища. -* Опционально могут быть подняты дополнительные **кэширующие** репозитории в локальной сети с быстрым доступом. -* **Финальный** репозиторий располагается близко к кластеру Kubernetes для того, чтобы запускаемое приложение быстро скачивало образы приложения (скачивание финальных образов со стороны Kubernetes будет происходить чаще, чем их загрузка со сборочных хостов). Также к финальному репозиторию требуется доступ на запись со всех сборочных хостов. В финальный репозиторий будут загружены лишь конечные образы приложения (без промежуточных образов артефактов, которые нужны для сборки других образов). - - +В данной статье описано, как устроено хранилище собираемых образов в werf, какие бывают типы хранилища, какие функции выполняют эти хранилища, а также различные варианты организации хранилища в проекте. + +## Типы хранилища + +### Первичный репозиторий + +* Задаётся параметром `--repo` (или переменной окружения `WERF_REPO`). +* У проекта всегда есть только один такой репозиторий. + +Данное хранилище является основным и объединяет в себе несколько функций: + +1. История проекта. + - Хранилище метаданных, связанных с Git-репозиторием, для собираемых образов и стадий. + - История проекта позволяет реализовать продвинутый алгоритм безопасной очистки старых стадий на основе истории Git-репозитория (команда `werf cleanup`). +1. Синхронизация сборки в распределённом окружении. + - Данное хранилище позволяет запускать сборку в распределённом окружении и эффективно переиспользовать собираемые стадии в таком окружении. Это возможно за счёт механизмов распределённой синхронизации, встроенных в werf. Эти механизмы работают исключительно с первичным репозиторием. + - Как только стадия попадает в первичный репозиторий, эта стадия может быть переиспользована другими сборочными процессами, которые могут быть запущены с произвольного хоста. +1. Сборочный кэш ранее собранных стадий. + - Ранее собранные стадии по возможности переиспользуются вместо того, чтобы собираться заново. + - Данная функция схожа с привычным локальным сборочным кэшом в Docker server, однако в случае werf этот кэш находится в container registry. +1. Хранилище финальных образов, используемых при запуске приложения в Kubernetes. + - Kubernetes будет скачивать образы из этого репозитория для запуска контейнеров приложения. + - В качестве финальных образов напрямую используются те же стадии, из которых состоит собранный образ. + +**Очистка (ВАЖНО!).** Для корректной и полноценной работы werf первичный репозиторий должен быть надёжным (persistent) хранилищем, образы из которого удаляются лишь специальной командой очистки `werf cleanup`. Первичный репозиторий — это не просто сборочный кэш проекта, но и хранилище его истории, похожее на историю коммитов в Git-репозитории. + +Помимо первичного репозитория в werf есть другие типы репозиториев, которые могут выполнять часть его функций. Они будут рассмотрены далее. Стоит помнить, что **без первичного репозитория werf не работает, а все другие репозитории — дополнительные**; они были созданы, чтобы снять часть функций первичного репозитория в вашей инсталляции проекта. + +### Вторичный репозиторий + +* Задаётся параметром `--secondary-repo` (или переменной окружения `WERF_SECONDARY_REPO_`). +* Может быть указан один или несколько таких репозиториев. + +Данное хранилище — это репозиторий только для чтения (read-only), выполняющий функцию сборочного кэша ранее собранных стадий *(см. функции [первичного репозитория](#первичный-репозиторий))*. + +Как правило, в качестве secondary-repo может быть указан уже существующий первичный репозиторий от другой инсталляции проекта. Отсутствующие стадии по мере необходимости будут скопированы из вторичного репозитория в первичный вместо сборки с нуля. Вновь собранные же стадии будут помещены только в первичный репозиторий, потому что вторичный репозиторий всегда read-only, т.е. мы не имеем права в него записывать новые данные. + +**Очистка** вторичного репозитория не требуется, т.к. этот репозиторий в то же время является первичным для другой инсталляции проекта и его данные управляются там. + +### Кэширующий репозиторий + +* Задаётся параметром `--cache-repo` (или переменной окружения `WERF_CACHE_REPO_`). +* Может быть указан один или несколько таких репозиториев. + +Выполняет функцию сборочного кэша ранее собранных стадий *(см. функции [первичного репозитория](#первичный-репозиторий))*. Кэширующий репозиторий отличается от вторичного тем, что он read-write, т.е. используется как для записи новых стадий в кэш, так и для использования собранных стадий из этого кэша. + +Существующие стадии будут скопированы из кэширующего репозитория в первичный, поскольку первичный репозиторий обязан содержать все собранные стадии образов проекта. Вновь собранные стадии будут опубликованы и в первичный репозиторий, и в кэширующий репозиторий. + +Стадии, которые используются в качестве базовых для сборки новых стадий: +* будут скачиваться из кэша, +* если их нет в кэширующем репозитории — будут скачиваться из первичного репозитория, а затем загружены в кэширующий для дальнейшего использования. + +Другими словами, кэширующий репозиторий заполняется не только вновь собираемыми стадиями, но и базовыми стадиями, используемыми для сборки новых стадий. + +Кэширующий репозиторий никогда не используется при запуске приложения в Kubernetes. + +**Очистка** кэширующего репозитория осуществляется путём его полного удаления. После очистки такой репозиторий будет вновь наполнен актуальными часто используемыми данными. + +### Финальный репозиторий + +* Задаётся параметром `--final-repo` (или переменной окружения `WERF_FINAL_REPO`). +* Может быть указан только один такой репозиторий. + +Данный репозиторий будет использоваться исключительно для публикации финальных образов, задействованных для деплоя приложения в Kubernetes. +- Вновь собираемые образы попадают сначала в первичный репозиторий, и затем копируются в финальный. +- Финальный репозиторий никогда не хранит промежуточные стадии образов, в нем есть лишь последняя стадия образа. +- Финальный репозиторий никогда не хранит промежуточные образы (артефакты), нужные для сборки конечных образов. Сюда попадают только конечные образы, используемые в Kubernetes. + +**Очистка** данного репозитория выполняется командой `werf cleanup` в паре с первичным репозиторием (для этого необходимо указывать два параметра команде `werf cleanup`: `--repo` и `--final-repo`). + +## Примеры организации хранилища стадий + +Рассмотрим варианты использования и комбинации описанных репозиториев. Стоит отметить, что любой из описанных вариантов требует указания [первичного репозитория](#первичный-репозиторий). + +### 1. Стандарт + +* **Первичный** репозиторий доступен со всех сборочных хостов, а также из кластера Kubernetes. Другие репозитории не используются. +* При сборке образов сборочный кэш будет скачиваться и загружаться в первичный репозиторий. При выкате Kubernetes будет скачивать финальные образы приложения из данного репозитория. +* В большинстве случаев следует использовать именно эту простую схему. Также данная схема подходит, если нет уверенности в том, что требуется для проекта. + +### 2. Дополнительный кэш в локальной сети + +* **Первичный** репозиторий доступен со всех сборочных хостов, а также из кластера Kubernetes. +* **Кэширующий** репозиторий работает в локальной сети с быстрым доступом. +* При сборке образов сборочный кэш загружается и в первичный репозиторий, и в кэширующий репозиторий. Стадии образов, требуемые для сборки других стадий, будут скачиваться из кэширующего репозитория. + +### 3. Полная оптимизация + +* **Первичный** репозиторий располагается в локальной сети с быстрым доступом и доступен со всех сборочных хостов. Доступ к данному репозиторию из кластера Kubernetes не требуется. В отличие от кэширующего репозитория, первичный не может быть полностью очищен или удалён без последствий для работы werf, поэтому требуется обеспечить персистивность и надёжность данного хранилища. +* Опционально могут быть подняты дополнительные **кэширующие** репозитории в локальной сети с быстрым доступом. +* **Финальный** репозиторий располагается близко к кластеру Kubernetes для того, чтобы запускаемое приложение быстро скачивало образы приложения (скачивание финальных образов со стороны Kubernetes будет происходить чаще, чем их загрузка со сборочных хостов). Также к финальному репозиторию требуется доступ на запись со всех сборочных хостов. В финальный репозиторий будут загружены лишь конечные образы приложения (без промежуточных образов артефактов, которые нужны для сборки других образов).