Merge pull request #5281 from werf/docs-usage-update-distribute-chart…

…s-chapter-ru

docs(usage): update RU distribute/charts chapter

docs/_data/breadcrumbs.yml

@@ -19,7 +19,7 @@ en:
     url: usage/deploy/overview.html
   /usage/distribute: &documentation-usage-distribute
     title: Distribute
-    url: usage/distribute/charts.html
+    url: usage/distribute/bundles.html
   /usage/cleanup: &documentation-usage-cleanup
     title: Cleanup
     url: usage/cleanup/cr_cleanup.html

docs/_data/sidebars/_documentation.yml

@@ -208,8 +208,8 @@ entries:
               - title: Образы
                 url: /usage/distribute/images.html
 
-              - title: Чарты, бандлы
-                url: /usage/distribute/charts.html
+              - title: Бандлы и чарты
+                url: /usage/distribute/bundles.html
 
           - title: Очистка
             f:

docs/_data/sidebars/documentation.yml

@@ -838,8 +838,8 @@ entries:
               - title: Образы
                 url: /usage/distribute/images.html
 
-              - title: Чарты, бандлы
-                url: /usage/distribute/charts.html
+              - title: Бандлы и чарты
+                url: /usage/distribute/bundles.html
 
           - title: Очистка
             f:

docs/pages_ru/resources/how_to_migrate_from_v1_1_to_v1_2.md

@@ -218,7 +218,7 @@ werf предоставляет следующие команды compose:
 - Бандлы позволяют разделить процесс создания нового релиза кода приложения и процесс деплоя этого релиза в кластер kubernetes.
 - Бандлы хранятся в container registry.
 - Работа с бандлами предполагает 2 основных шага: 1) публикация бандла для приложения из рабочей директории git проекта в container registry; 2) деплой ранее опубликованного бандла из container registry в кластер kubernetes.
-- Больше информации [в документации]({{ "/usage/distribute/charts.html" | true_relative_url }}).
+- Больше информации [в документации]({{ "/usage/distribute/bundles.html" | true_relative_url }}).
 
 ### Переработка основного командного интерфейса и поведения команд
 

docs/pages_ru/usage/distribute/bundles.md

@@ -0,0 +1,142 @@
+---
+title: Бандлы и чарты
+permalink: usage/distribute/bundles.html
+---
+
+## О бандлах и чартах
+
+*Чарты* в werf это Helm-чарты с некоторыми дополнительными возможностями. *Бандлы* в werf по существу являются чартами в OCI-репозитории и используются для тех же целей, что и обычные чарты, но предоставляют ещё один ряд дополнительных возможностей:
+
+* сохранение имён собираемых образов и их динамических тегов в Values бандла;
+
+* копирование и бандла и связанных с ним собранных образов в другой репозиторий с автоматическим обновлением путей к этим образам в Values бандла с помощью одной команды `werf bundle copy`;
+
+* сохранение глобальных пользовательских и служебных аннотаций и лейблов для ресурсов в бандле;
+
+* сохранение переданных через параметры командной строки или переменные окружения Values в бандле.
+
+*Любой* опубликованный в OCI-репозитории чарт является бандлом. *Любой* бандл также является чартом, хотя будучи использованным как обычный чарт часть его дополнительных возможностей вроде сохранённых глобальных служебных аннотаций станет недоступной.
+
+Для публикации и чартов и бандлов используется одна команда — `werf bundle publish`. Эта команда публикует именно бандл, но при этом опубликованный бандл можно использовать и как бандл, и как чарт, в свете того, что бандл является расширенной версией чарта.
+
+## Публикация бандла
+
+Опубликовать бандл в OCI-репозиторий можно следующим способом:
+
+1. Создайте `werf.yaml`, если его ещё нет:
+
+   ```yaml
+   # werf.yaml:
+   project: mybundle
+   configVersion: 1
+   ```
+
+2. Разместите файлы бандла в директории основного чарта (по умолчанию `.helm` в корне Git-репозитория). Заметьте, что при публикации в бандл будут включены *только* следующие файлы и директории:
+
+   ```
+   .helm/
+     charts/
+     templates/
+     crds/
+     files/
+     Chart.yaml
+     values.yaml
+     values.schema.json
+     LICENSE
+     README.md
+   ```
+
+   Для публикации дополнительных файлов/директорий выставьте переменную окружения `WERF_BUNDLE_SCHEMA_NONSTRICT=1`, после чего будут публиковаться *все* файлы и директории в директории основного чарта, а не только вышеуказанные.
+
+3. Следующей командой соберите и опубликуйте описанные в `werf.yaml` образы (если таковые есть) и опубликуйте содержимое `.helm` как бандл `example.org/bundles/mybundle:latest` в виде OCI-образа:
+
+   ```shell
+   werf bundle publish --repo example.org/bundles/mybundle
+   ```
+
+## Публикация нескольких бандлов из одного Git-репозитория
+
+Разместите `.helm` с содержимым бандла и соответствующий ему `werf.yaml` в отдельную директорию для каждого бандла:
+
+```
+bundle1/
+  .helm/
+    templates/
+    ...
+  werf.yaml
+bundle2/
+  .helm/
+    templates/
+    ...
+  werf.yaml
+```
+
+Теперь опубликуйте каждый бандл по отдельности:
+
+```shell
+cd bundle1
+werf bundle publish --repo example.org/bundles/bundle1
+
+cd ../bundle2
+werf bundle publish --repo example.org/bundles/bundle2
+```
+
+## Исключение файлов или директорий из публикуемого бандла
+
+Файл `.helmignore`, находящийся в корне бандла, может содержать фильтры по именам файлов, при соответствии которым файлы или директории не будут добавляться в бандл при публикации. Формат правил такой же, как и в [.gitignore](https://git-scm.com/docs/gitignore), за исключением:
+
+- `**` не поддерживается;
+
+- `!` в начале строки не поддерживается;
+
+- `.helmignore` не исключает сам себя по умолчанию.
+
+Также опция `--disable-default-values` для команды `werf bundle publish` позволяет исключить из публикуемого бандла файл `values.yaml`.
+
+## Версионирование бандлов
+
+По умолчанию бандл публикуется с тегом `latest`. Указать иной тег, например семантическую версию для публикуемого бандла, можно опцией `--tag`:
+
+```shell
+werf bundle publish --repo example.org/bundles/mybundle --tag v1.0.0
+```
+
+Результат: опубликован бандл `example.org/bundles/mybundle:v1.0.0`.
+
+Если при публикации будет обнаружено, что в OCI-репозитории уже существует бандл с таким тегом, то бандл в репозитории будет перезаписан.
+
+## Копирование бандла и его образов в другой репозиторий
+
+Для удобного копирования бандла и связанных с ним собранных образов в другой репозиторий имеется команда `werf bundle copy`. Кроме непосредственного копирования бандла и образов эта команда также обновит сохранённые в бандле Values, указывающие на путь к образам.
+
+Пример:
+
+```shell
+werf bundle copy --from example.org/bundles/mybundle:v1.0.0 --to other.example.org/bundles/mybundle:v1.0.0
+```
+
+## Изменение имени или тега опубликованного бандла
+
+Для изменения имени или тега уже опубликованного бандла скопируйте бандл с новым именем/тегом с помощью команды `werf bundle copy`, например:
+
+```shell
+werf bundle copy --from example.org/bundles/mybundle:v1.0.0 --to example.org/bundles/renamedbundle:v2.0.0
+```
+
+## Container Registries, поддерживающие публикацию бандлов
+
+Для публикации бандлов требуется Container Registry, поддерживающий спецификацию OCI ([Open Container Initiative](https://github.com/opencontainers/image-spec)). Список наиболее популярных Container Registries, совместимость с которыми была проверена:
+
+| Container Registry        | Поддерживает публикацию бандлов |
+| ------------------------- |:-------------------------------:|
+| AWS ECR                   | +                               |
+| Azure CR                  | +                               |
+| Docker Hub                | +                               |
+| GCR                       | +                               |
+| GitHub Packages           | +                               |
+| GitLab Registry           | +                               |
+| Harbor                    | +                               |
+| JFrog Artifactory         | +                               |
+| Yandex Container Registry | +                               |
+| Nexus                     | +                               |
+| Quay                      | -                               |