Допустим имеется какой-то проект в Gitlab CI/CD, который использует werf и хранилище стадий :local. В данной статье приведены шаги для переключения такого проекта на удалённое хранилище стадий. Удалённое хранилище стадий позволяет запускать werf с произвольных хостов открывая возможность распределённой работы werf.

Требуемая версия werf: >= v1.1.10.

Требования к хосту:

  • Доступ к docker registry, который будет использован как хранилище стадий для проекта.
  • Доступ к кластеру Kubernetes.

Важно. Обязательно выполнить команду switch-from-local для избежания дальнейшего нарушения целостности из-за одновременного использования и :local и registry — этот шаг пропускать нельзя. (См. далее).

Важно. Возможен небольшой простой в работе CI/CD для тех веток, которые ещё не успели получить изменения из PR с переходом на удалённое хранилище стадий. Этот простой будет активирован после выполнения команды switch-from-local — с этого момента надо как можно быстрее донести изменения из MR по переключению во все ветки, потому что локальное хранилище стадий перестанет работать после выполнения этой команды (См. далее).

Шаги по переключению

  1. Опциональный шаг. Скопировать уже существующие на runner стадии в registry. Этот шаг является полностью безопасным и не мешает работе с проектом. Это рекомендуемый для выполнения шаг, потому что он ускорит дальнейший шаг switch-from-local и предотвратит пересборку стадий, которые уже существуют в локальном хранилище стадий, при подготовке MR в одном из дальнейших шагов.
    • Перейти в директорию проекта на gitlab-runner.
    • Узнать адрес docker repo проекта через интерфейс Gitlab CI/CD / Packages / Container Registry.
    • Copy address of the project docker repo and add /stages suffix. For example: registry.mycompany.com/web/catalog/myproject/stages. NOTE: Werf ci-env command will automatically use CI_REGISTRY_IMAGE/stages as a stages storage, that’s why it is required to use /stages suffix and not an arbitrary one.
    • Копируем адрес — например, registry.mycompany.com/web/catalog/myproject — и добавляем суффикс /stages: registry.mycompany.com/web/catalog/myproject/stages. Важно: При использовании werf ci-env автоматически будет использоваться следующий адрес для хранения стадий: CI_REGISTRY_IMAGE/stages — поэтому надо использовать именно этот адрес, а не произвольный.
    • Логинимся в docker registry: docker login registry.mycompany.com/web/catalog/myproject/stages -uUSER -pTOKEN. Токен для вашего пользователя можно получить через интерфейс Gitlab CI/CD.
    • Запускаем команду копирования стадий: werf stages sync --from :local --to registry.mycompany.com/web/catalog/myproject/stages.
  2. Обязательный шаг. Подготавливаем MR с изменениями для перевода на распределённые билды: убрать явно указанный параметр --stages-storage :local (или переменную окружения WERF_STAGES_STORAGE) во всех командах. Дождаться успешной сборки этого MR (в случае если конфигурация системы предусматривает это).
  3. Обязательный шаг. Запускаем команду переключения stages-storage с local на registry. Важно: После того как команда отработает надо как можно быстрее донести изменения из MR в мастер, а затем и во все ветки с активной разработкой, потому что после выполнения этой команды будет установлен блок на использование stages-storage :local для избежания дальнейшего нарушения целостности из-за одновременного использования и локального, и удалённого хранилища стадий.
  4. Принять MR из шага 2.
  5. Актуализировать все активно используемые git-ветки, которые требуют CI/CD: требуется merge/rebase новых изменений внесённых на шаге 4.

Замечание. Если надо перевести сразу весь проект, то логично написать скрипт, который делает всем проектам sync — потому что это потенциально долгая опрерация. Затем пока он работает можно подготовить MR для всех проектов. Затем по одному вызвать stages move-from-local для каждого проекта и принимать MR.

Шаги по откату

  1. Если switch-from-local успел пройти, то он удалил локальный кеш. Чтобы его вернуть, надо запустить следующий sync: werf stages sync --from registry.mycompany.com/web/catalog/myproject/stages --to :local.
  2. Удалить файл блокировки на запуск команд с :local для проекта: rm ~/.werf/service/stages_switch_from_local_block/PROJECT_NAME — этот файл блокировки был создан на шаге 3.
  3. Создать MR, в котором откатить изменения внесенные на шаге 2.
  4. Остановить все job-ы, где работает werf и не запускать новых.
  5. Принять новый MR и перенести изменения во все ветки, где уже работает сборка с использованием registry.