Вступление
В этой статье мы рассмотрим основы использования werf в рамках различных систем CI/CD.
Также доступна статья, в которой обсуждаются более продвинутые вопросы общей интеграции в процесс CI/CD.
werf изначально поддерживает GitLab CI/CD и GitHub Actions, а также предлагает специальную команду werf ci-env
(она необязательна и позволяет настраивать параметры werf, описываемые в этой статье, автоматически и единообразно). Дополнительные сведения можно найти в следующих документах:
Команды werf, которые понадобятся
Следующие базовые команды werf выступают строительными блоками для построения пайплайнов:
werf converge
;werf dismiss
;werf cleanup
.
Также имеются некоторые специальные команды:
werf build
позволяет собирать необходимые образы;werf run
позволяет проводить модульное тестирование собранных образов.
Встраивание werf в систему CI/CD
Обычно процесс встраивания werf в задания CI/CD-систем прост и необременителен. Для этого достаточно выполнить следующие действия:
- Обеспечьте заданию CI/CD доступ к кластеру Kubernetes и container registry.
- Проведите checkout на нужный коммит git в репозитории проекта.
- Запустите команду
werf converge
, чтобы развернуть приложение; запуститеwerf dismiss
, чтобы удалить его из Kubernetes; выполнитеwerf cleanup
, чтобы удалить неиспользуемые образы из container registry.
Подключение к кластеру Kubernetes
werf подключается и работает с кластером Kubernetes через файлы kubeconfig. По умолчанию используется ~/.kube/config
, но вы можете изменить это с помощью флагов (--kube-config
или --kube-config-base64
) или соответствующих переменных среды (например, WERF_KUBE_CONFIG
) .
Настройка доступа задания CI/CD к container registry
Если используются непубличные образы, собранные специально для конкретного проекта, приходится использовать приватный container registry. В этом случае хост, на котором работает раннер CI/CD, должен иметь доступ к container registry, чтобы публиковать собранные образы. Кроме того, кластеру Kubernetes необходим доступ для скачивания этих образов.
Если клиент docker
уже настроен на доступ к приватному container registry с вашего хоста, дополнительное конфигурирование werf не требуется, поскольку он использует те же настройки, что и docker (каталог с настройками по умолчанию ~/.docker/
или переменную среды DOCKER_CONFIG
).
docker login registry.mydomain.org/application -u USER -p PASSWORD
Если постоянный логин раннер-хоста в container registry не требуется, выполните процедуру входа в каждом из заданий Ci/CD. Мы рекомендуем создавать временную конфигурацию docker для каждого CI/CD-задания (вместо использования директории по умолчанию ~/.docker/
), чтобы предотвратить конфликт разных заданий, выполняющихся на одном и том же раннере в одно и то же время.
# Job 1
export DOCKER_CONFIG=$(mktemp -d)
docker login registry.mydomain.org/application -u USER -p PASSWORD
# Job 2
export DOCKER_CONFIG=$(mktemp -d)
docker login registry.mydomain.org/application -u USER -p PASSWORD
Настройка целевого окружения для werf
Обычно приложение развертывается в различные окружения (production
, staging
, testing
, и т.д.).
В werf имеется опциональный параметр --env
(или переменная среды WERF_ENV
), с помощью которого можно задать имя используемого окружения. Оно влияет на название соответствующего пространства имен Kubernetes и название Helm-релиза. Мы рекомендуем проверять имя окружения в процессе выполнения CI/CD-задания (например, с помощью встроенных переменных окружения вашей CI/CD-системы) и соответствующим образом устанавливать параметр --env
.
Задаем переменную среду WERF_ENV
:
WERF_ENV=production werf converge
Или используем встроенные переменные среды CI/CD-системы:
werf converge --env $CI_ENVIRONMENT_NAME
Другие настройки werf, связанные с CI/CD
Существуют и другие настройки (как правило, они настраиваются для werf в CI/CD):
- Кастомные аннотации и лейблы для всех развернутых ресурсов Kubernetes
- имя приложения;
- URL-адрес приложения в Git;
- версия приложения;
- URL converge-задания в CI/CD;
- git-коммит;
- git-тег;
- git-ветвь;
- и т.д.
Кастомные аннотации и лейблы можно задавать с помощью опций --add-annotation
, --add-label
(или переменных среды WERF_ADD_ANNOTATION_<ARBITRARY_STRING>
, WERF_ADD_LABEL_<ARBITRARY_STRING>
).
-
Подсветка логов, ширина вывода и пользовательские параметры задаются с помощью флагов
--log-color-mode=on|off
,--log-terminal-width=N
,--log-project-dir
(а также с помощью соответствующих переменных средыWERF_COLOR_MODE=on|off
,WERF_LOG_TERMINAL_WIDTH=N
,WERF_LOG_PROJECT_DIR=1
). -
Особый режим работы werf под названием “уничтожитель процессов”. Он обнаруживает отмененное задание CI/CD и автоматически завершает процесс werf. Эта функциональность востребована не во всех системах, а только в тех, которые не умеют посылать правильный сигнал о завершении порожденным процессам (например, в GitLab CI/CD). В этом случае лучше включить опцию werf
--enable-process-exterminator
(или установить переменную окруженияWERF_ENABLE_PROCESS_EXTERMINATOR=1
).
Давайте зададим кастомные аннотации, настроим логирование и включим режим “уничтожителя процессов” с помощью переменных среды:
export WERF_ADD_ANNOTATION_APPLICATION_NAME="project.werf.io/name=myapp"
export WERF_ADD_ANNOTATION_APPLICATION_GIT_URL="project.werf.io/git-url=https://mygit.org/myapp"
export WERF_ADD_ANNOTATION_APPLICATION_VERSION="project.werf.io/version=v1.4.14"
export WERF_ADD_ANNOTATION_CI_CD_JOB_URL="ci-cd.werf.io/job-url=https://mygit.org/myapp/jobs/256385"
export WERF_ADD_ANNOTATION_CI_CD_GIT_COMMIT="ci-cd.werf.io/git-commit=a16ce6e8b680f4dcd3023c6675efe5df3f40bfa5"
export WERF_ADD_ANNOTATION_CI_CD_GIT_TAG="ci-cd.werf.io/git-tag=v1.4.14"
export WERF_ADD_ANNOTATION_CI_CD_GIT_BRANCH="ci-cd.werf.io/git-branch=master"
export WERF_LOG_COLOR_MODE=on
export WERF_LOG_TERMINAL_WIDTH=95
export WERF_LOG_PROJECT_DIR=1
export WERF_ENABLE_PROCESS_EXTERMINATOR=1
Что дальше?
В этом разделе рассказывается, как управлять отслеживанием ресурсов в процессе развертывания.
Также рекомендуем ознакомиться со статьей “Основы рабочего процесса CI/CD”. В ней описываются различные способы настройки рабочих процессов CI/CD.
В разделе “Руководства” можно найти инструкцию, подходящую для вашего проекта. Эти руководства также содержат подробную информацию о настройке конкретных систем CI/CD.