werf bundle publish / werf bundle apply

Что нужно знать перед уроком

M8 урок 3 — content-based теги. M4 урок 5 — команды nelm release. Этот урок разбирает механизм разделения сборки/публикации и деплоя через bundle — Helm-чарт вместе с образами, упакованный как единый артефакт в OCI-репозитории.

Теория

Сценарий: CI собирает и публикует, отдельная система применяет без доступа к git

1

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

werf bundle publish выполняет фактически две задачи одной командой: собирает и публикует образы приложения в registry, и публикует сам Helm-чарт (со всеми ссылками на опубликованные образы) как отдельный OCI-артефакт в том же или другом репозитории. Результат — самодостаточный «бандл», не требующий доступа к исходному git-репозиторию для последующего применения.

1

werf bundle apply --repo ghcr.io/group/project --env production --tag 1.0.0

werf bundle apply разворачивает ранее опубликованный бандл в кластер, используя только данные из OCI-репозитория — без клонирования git-репозитория, без доступа к исходному коду приложения. Полный процесс из трёх шагов для деплоя без доступа к git:

1. Собрать образы и опубликовать их в container registry.
2. Опубликовать основной Helm-чарт (содержащий ссылки на образы) в OCI-репозиторий — этот шаг выполняет werf bundle publish.
3. Применить опубликованный бандл в целевой кластер — этот шаг выполняет werf bundle apply.

Чем это отличается от обычного werf converge

werf converge (M8 урок 7) требует доступа и к git-репозиторию (для получения исходного кода и werf.yaml), и к целевому кластеру в рамках одного и того же процесса/окружения. Разделение через bundle publish/bundle apply разрывает эту связь: сборка и публикация могут произойти в одном окружении (например, в GitLab CI runner с доступом к git и к container registry, но без доступа к целевому production-кластеру), а применение — в совершенно другом (например, отдельная система деплоя внутри защищённого контура заказчика, имеющая доступ к кластеру, но не имеющая доступа ни к git, ни даже к интернету напрямую, только к внутреннему registry).

Когда это нужно: деплой из закрытого контура, разделение ролей CI/деплоя

Практические сценарии, где bundle publish/bundle apply предпочтительнее единого werf converge:

• Деплой в закрытый контур (air-gapped): заказчик имеет собственный кластер, физически или сетево изолированный от внешнего интернета и от git-репозитория разработчика. Разработчик публикует бандл в передаваемый заказчику registry (например, через werf mirror), а команда заказчика самостоятельно выполняет bundle apply внутри своего контура.
• Разделение ролей CI и деплоя: организационно CI-система (сборка, тестирование, публикация артефактов) и система деплоя (применение конкретной версии в конкретный кластер, часто с ручным подтверждением) могут управляться разными командами с разными правами доступа — CI не должен иметь прямого доступа к production-кластеру, а деплой-система не должна иметь доступа к git и секретам сборки.
• Повторяемый rollback на точную версию без пересборки: bundle apply --tag 1.0.0 детерминированно применяет именно ту версию бандла, что была опубликована ранее — без риска, что повторная сборка из git даст немного другой результат (например, из-за изменившейся зависимости, не зафиксированной строго).

Частые ошибки и подводные камни

• Путать bundle publish с обычной публикацией образов через werf export. bundle publish публикует и образы, и сам Helm-чарт как единый артефакт — это шире, чем просто публикация образов.
• Пытаться выполнить bundle apply без предварительного bundle publish для нужной версии. bundle apply работает только с уже опубликованным в OCI-репозитории бандлом — это не альтернатива converge, а именно вторая половина разделённого процесса.
• Не понимать, что bundle apply не имеет доступа к git и не может учитывать изменения кода, внесённые после публикации бандла. Любое изменение кода требует нового цикла bundle publish с новой версией/тегом — bundle apply работает исключительно с уже зафиксированным, неизменяемым артефактом.

Практика в кластере

1
2
3

werf bundle publish --repo $CI_REGISTRY_IMAGE/bundles --tag v0.1.0
werf bundle apply --repo $CI_REGISTRY_IMAGE/bundles --tag v0.1.0 --env course-m8
d8 k get all -n course-m8-vikunja

Убедитесь, что bundle apply успешно развернул приложение в кластере без обращения к локальной копии git-репозитория (попробуйте выполнить эту команду из директории вне клонированного проекта).

Практика разработки

Настройте в .gitlab-ci.yml пакета Vikunja отдельные stage’ы: publish-bundle (выполняется автоматически на CI-раннере с доступом к git) и apply-bundle (выполняется вручную, симулируя отдельную систему деплоя без доступа к git, только к registry).

Шпаргалка команд урока

1
2

werf bundle publish --repo <bundle-repo> --tag <version>
werf bundle apply --repo <bundle-repo> --tag <version> --env <env>

Полная сводная таблица — 📋 werf .

Вопросы для самопроверки

Рекомендуемая литература

Официальная документация

• werf — Deployment_Scenarios
• werf — Overview

Статьи и блоги

• Вышла werf 2.0: новый движок развёртывания Nelm — Flant на Habr.
• werf v1.2 — Stapel и инкрементальная сборка — Flant на Habr.
• GitLab + K8s + Werf — Habr.

Книги

• Nigel Poulton. Docker Deep Dive. 2023. ISBN 978-1916585206.

Связанные материалы

• Предыдущий урок: M8.03 — Content-based тегирование и алиасы.
• Следующий урок: M8.05 — werf cleanup глубоко.

✓ Урок пройден — все вопросы самопроверки отвечены верно