Бандлы и чарты

О бандлах и чартах

Бандл — это способ дистрибуции чарта и связанных с ним образов как единого целого.

Командой werf bundle publish можно опубликовать чарт и связанные образы для дальнейшего развёртывания с werf. При этом для развёртывания доступ к Git-репозиторию приложения больше не потребуется.

Эта же команда подходит для публикации чарта. Опубликованный в OCI-репозиторий чарт может использоваться в качестве основного или зависимого чарта с werf, Helm, Argo CD, Flux и другими решениями.

При упаковке werf автоматически добавляет следующие данные в чарт:

• имена собираемых образов и их динамических тегов в Values чарта;
• значения, переданных через параметры командной строки или переменные окружения, в Values чарта;
• глобальные пользовательские и служебные аннотации и лейблы для добавления в ресурсы чарта при развёртывании командой werf bundle apply.

Опубликованный бандл (чарт и связанные с ним образы) можно копировать в другой репозиторий container registry или выгружать в/из архива с помощью одной команды werf bundle copy.

Аутентификация в container registry

Перед работой с образами необходимо аутентифицироваться в container registry. Сделать это можно командой werf cr login:

werf cr login <registry url>

Например:

# Login with username and password from command line
werf cr login -u username -p password registry.example.com

# Login with token from command line
werf cr login -p token registry.example.com

# Login into insecure registry (over http)
werf cr login --insecure-registry registry.example.com

В случае использования команды ci-env с поддерживаемыми CI/CD-системами аутентификация во встроенные container registry выполняется в рамках команды, поэтому использование команды werf cr login в этом случае не требуется.

Публикация бандла

Опубликовать бандл в OCI-репозиторий можно следующим способом:

1. Создайте werf.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 в виде OCI-образа example.org/bundles/mybundle:latest:

   werf bundle publish --repo example.org/bundles/mybundle
   

Публикация нескольких бандлов из одного Git-репозитория

Разместите .helm с содержимым чарта и соответствующий ему werf.yaml в отдельную директорию для каждого бандла:

bundle1/
  .helm/
    templates/
    # ...
  werf.yaml
bundle2/
  .helm/
    templates/
    # ...
  werf.yaml

Теперь опубликуйте каждый бандл по отдельности:

cd bundle1
werf bundle publish --repo example.org/bundles/bundle1

cd ../bundle2
werf bundle publish --repo example.org/bundles/bundle2

Исключение файлов или директорий из публикуемого чарта

Файл .helmignore, находящийся в корне чарта, может содержать фильтры по именам файлов, при соответствии которым файлы или директории не будут добавляться в чарт при публикации. Формат правил такой же, как и в .gitignore, за исключением:

• ** не поддерживается;

• ! в начале строки не поддерживается;

• .helmignore не исключает сам себя по умолчанию.

Также опция --disable-default-values для команды werf bundle publish позволяет исключить из публикуемого чарта файл values.yaml.

Использование произвольных тегов образов

Для использования произвольных тегов образов для бандлов необходимо задать шаблон именования с помощью опции --use-custom-tag (WERF_USE_CUSTOM_TAG).

Пример использования:

werf bundle publish --repo example.org/bundles/mybundle --tag "%image%-my-custom-tag"

Подробнее про кастомные теги можно прочитать в документации.

Указание версии чарта при публикации

По умолчанию чарт публикуется с тегом latest. Указать иной тег, например, семантическую версию для публикуемого чарта, можно опцией --tag:

werf bundle publish --repo example.org/bundles/mybundle --tag v1.0.0

Результат: опубликован чарт example.org/bundles/mybundle:v1.0.0.

Если при публикации будет обнаружено, что в OCI-репозитории уже существует чарт с таким тегом, то чарт в репозитории будет перезаписан.

Изменение версии опубликованного чарта

Для изменения тега уже опубликованного чарта скопируйте бандл с новым тегом с помощью команды werf bundle copy, например:

werf bundle copy --from example.org/bundles/mybundle:v1.0.0 --to example.org/bundles/renamedbundle:v2.0.0

Копирование бандла в другой репозиторий

Для удобного копирования бандла в другой репозиторий имеется команда werf bundle copy. Кроме непосредственного копирования чарта и связанных с ним образов эта команда также обновит сохранённые в чарте Values, указывающие на путь к образам.

Пример:

werf bundle copy --from example.org/bundles/mybundle:v1.0.0 --to other.example.org/bundles/mybundle:v1.0.0

Экспорт бандла из container registry в архив

После публикации бандл может быть экспортирован из репозитория в локальный архив для дальнейшей дистрибуции иными способами с помощью команды werf bundle copy, например:

werf bundle copy --from example.org/bundles/mybundle:v1.0.0 --to archive:archive.tar.gz

Импорт бандла из архива в репозиторий

Экспортированный в архив бандл можно снова импортировать в тот же или другой OCI-репозиторий командой werf bundle copy, например:

werf bundle copy --from archive:archive.tar.gz --to other.example.org/bundles/mybundle:v1.0.0

После этого вновь опубликованный бандл (чарт и его образы) снова можно использовать привычными способами.

Container registries, поддерживающие публикацию бандлов

Для публикации бандлов требуется container registry, поддерживающий спецификацию OCI (Open Container Initiative). Список наиболее популярных container registries, совместимость с которыми была проверена: