С большим уважением к материалам dmosk
Runner в GitLab позволяют автоматизировать рутинные задачи при обновлении проектов в репозитории. В нашем примере мы рассмотрим ситуацию, когда у нас используется сервер GitLab для хранения проекта и 5 веб-серверов, куда должны попадать изменения после выполнения git push. Мы настроим наш CI/CD на синхронизацию файлов с помощью rsyncd. Предполагается, что у нас уже установлен GitLab на Linux, в противном случае, воспользуйтесь инструкцией для Ubuntu или CentOS.
Установка и регистрация Runner
Runner — это отдельное приложение, которое запускается для выполнения заданий CI/CD. Его можно установить на любой компьютер под управлением любой популярной операционной системы (Linux, Windows, BSD, Mac OS и так далее). Также доступны различные варианты установки — из репозитория, скачивание бинарника или запуск как приложения в Docker или кластере Kubernetes. Мы выполним установку из репозитория Linux на тот же сервер, где работает наш GitLab.
Установка
По умолчанию, Runner не устанавливается вместе с GitLab. Для его установки необходимо сначала настроить репозиторий — наши действия зависят от используемой системы.
Настройка репозитория
а) система на базе deb-пакетов (Debian / Ubuntu):
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
б) система на базе RPM-пакетов (Red Hat / CentOS):
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
в) для систем, которые не поддерживаются GitLab, но которые основаны на базе поддерживаемых систем.
Сначала загружаем скрипт:
wget https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh
* в данном примере, загружен скрипт для систем на базе пакетов RPM.
Открываем его на редактирование:
vi script.rpm.sh
Находим строки:
# remove whitespace from OS and dist name
os="${os// /}"
dist="${dist// /}"
И меняем их на что-то подобное:
# remove whitespace from OS and dist name
os="centos"
dist="8"
* в данном примере мы указали, что установка будет выполняться как для CentOS 8.
Запускаем скрипт:
bash script.rpm.sh
Установка
После настройки репозитория, выполняем установку. Команда также зависит от типа операционной системы.
а) для Debian / Ubuntu (системы на основе deb-пакетов):
apt-get install gitlab-runner
б) для Red Hat / CentOS (системы на основе RPM):
yum install gitlab-runner
После установки gitlab-runner разрешаем автозапуск сервиса и стартуем его:
systemctl enable gitlab-runner --now
Регистрация
Для корректной работы Runner его нужно связать с нашим проектом в GitLab. Для этого сначала заходим на портал последнего – переходим на страницу проекта – в меню слева выбираем Settings – CI / CD:
Находим раздел Runners:
Справа от названия кликаем по Expand:
Находим параметры для регистрации нового раннера:
… и оставляем страницу открытой — она понадобиться на следующем шаге.
В командной строке нашего сервера GitLab вводим:
gitlab-runner register
* установить и запустить Runner можно не только на локальном сервере GitLab, но мы рассмотрим только данный способ.
Система в интерактивном режиме запросит данные для регистрации — вводим их:
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.dmosk.ru/
Enter the registration token:
zX_Kvkxk7ywrgwYHsod5
Enter a description for the runner:
[git-server.dmoks.ru]: DMOSK Metrics API
Enter tags for the runner (comma-separated):
dmosk, metrics, api
Registering runner... succeeded runner=zX_Kvkxk
Enter an executor: parallels, virtualbox, docker+machine, docker-ssh+machine, kubernetes, custom, docker, docker-ssh, shell, ssh:
shell
* где:
- https://gitlab.dmosk.ru/ — адрес нашего сервера GitLab. Его можно увидеть на странице с параметрами, которую мы оставили открытой на предыдущем шаге. В моем случае, на данной странице ссылка была типа http, однако, при регистрации Runner мы ее должны поменять на https (если наш сервер использует его).
- zX_Kvkxk7ywrgwYHsod5 — токен для регистрации раннера. Его смотрим на странице с параметрами, которые мы открывали выше.
- DMOSK Metrics API — произвольное описание для нашего раннера.
- dmosk, metrics, api — теги. Рекомендуется максимально точно описывать раннер тегами. С их помощью можно указывать, на каких раннерах должны выполняться те или иные задачи.
- shell — выбираем исполнителя из предложенных вариантов. В нашем случае это просто командный интерпретатор.
В конце мы должны увидеть:
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
* если мы получим ошибку «status couldn execute post against certificate signed by unknown authority», переходим к решению ниже.
Обновим страницу с параметрами для регистрации раннера — ниже мы должны увидеть, что у нас появился один новый элемент. Кликаем по изображению редактирования справа от токена:
Выставляем следующие галочки для настройки Runner:
* где:
- Paused Runners don’t accept new jobs — если наш обработчик заданий приостановлен, он не принимает новые задания.
- This runner will only run on pipelines triggered on protected branches — Runner должен запускаться только на защищенных ветках.
- Indicates whether this runner can pick jobs without tags — раннер может запускать задания без тегов. В данном примере для первого знакомства с CI/CD мы поставим галочку, но лучше этого не делать, а управлять заданиями с помощью тегов.
- When a runner is locked, it cannot be assigned to other projects — если обработчик заблокирован, его нельзя назначать для других проектов.
В нашем примере мы рассмотрели регистрацию персонального раннера для проекта. В GitLab также предусмотрена созможность регистрации общего runner, к которому можно привязывать проекты. Сама регистрация выполняется по такому же принципу и не должна вызвать проблем. В GitLab для этого переходим в Menu – Admin – Runners.
И так, обработчик зарегистрирован и настроен. Переходим к созданию CI/CD.
Создание CI/CD для проекта
На первоначальном этапе, мы создадим простой сценарий, который просто будет выводить путь до каталога на сервере, в котором находится проект.
Переходим в GitLab на страницу проекта и кликаем по Set up CI/CD:
* данной кнопки может и не быть.
… или можно просто в корне проекта создать файл:
vi .gitlab-ci.yml
Задаем содержимое нашего сценария:
default:
tags:
- dmosk
stages:
- test
test:
stage: test
script: echo $CI_PROJECT_DIR/
* Формат текста должен быть yml, а значит, отступы имеют значение.
** В данном примере мы создаем pipeline с одним единственным этапом, которое называется test. По данному заданию будет запускаться скрипт вывода значения переменной $CI_PROJECT_DIR — путь, по которому клонируется проект и где выполняется задание (если установлен $builds_dir, эта переменная устанавливается относительно данного значения). Также обратите внимание на директиву default с указанием на использование тегов (tags) — для всех заданий мы определили тег по умолчанию, который может контролировать, на каких раннерах должно быть запущено задание.
*** Список возможных переменных можно посмотреть на официальном сайте в разделе документации GitLab CI/CD environment variables.
**** Боллее подробная шпаргалка по работе с Gitlab CI/CD представлена в инструкции Шпаргалка по написанию Gitlab Pipelines.
После сохранения файла ждем несколько секунд и перезапускаем страницу — мы должны увидеть успешный результат выполнения сценария CI/CD:
Кликнем по значку зеленой галочки и в открывшейся странице кликаем по нашей единственной стадии:
Мы должны увидеть ход процесса выполнения задания и результат его работы:
На этой же странице справа можно вручную запустить задание еще раз:
CI/CD создан. Теперь необходимо подготовить систему к синхронизации данных.
Настройка Rsyncd
Наша синхронизация будет выполняться с помощью Rsyncd. Это удобный инструмент, с помощью которого можно поддерживать актуальное состояние двух и более каталогов. Также у нас не возникнет проблем с правами — rsync после копирования будет задавать файлам нужного владельца и нам не нужно будет выдавать права root для runner с помощью файла sudoerst. Подробнее об установке и настройке Rsyncd.
Настройки нужно выполнить как на веб-серверах, так и сервере с GitLab.
Настройка на веб-серверах
Данные действия нужно выполнить на каждом веб-сервере. Мы должны установить и настроить в качестве сервиса rsyncd. Сначала установим его. В зависимости от типа Linux, наши действия будут различаться.
а) Ubuntu / Debian:
apt-get install rsync
Открываем следующий файл:
vi /etc/default/rsync
Находим запись:
RSYNC_ENABLE=false
И меняем на:
RSYNC_ENABLE=true
Запускаем:
systemctl enable rsync
systemctl start rsync
б) CentOS 7
yum install rsync
systemctl enable rsyncd --now
в) CentOS 8
yum install rsync rsync-daemon
systemctl enable rsyncd --now
После установки и запуска rsyncd, открываем его конфигурационный файл:
vi /etc/rsyncd.conf
И добавим в него следующие настройки:
max connections = 10
exclude = lost+found/ .gitlab-ci.yml
dont compress = *.gz *.tgz *.zip *.z *.Z *.rpm *.deb *.bz2 *.rar *.7z *.mp3 *.jpg
[dmosk]
path = /var/www/dmosk/www/
comment = Site dmosk.ru
uid = apache
gid = apache
read only = no
list = yes
auth users = rsync_dmosk
secrets file = /etc/rsyncd.scrt
#pre-xfer exec =
#post-xfer exec =
hosts allow = localhost 192.168.0.10
hosts deny = *
* наибольший интерес для нас имеют следующие опции:
- [dmosk] — название для экземпляра синхронизации. К нему мы будем обращаться при выполнении команды rsync.
- path — путь до каталога, в котором находятся файлы для синхронизации. Это путь до папки проекта на самом веб-сервере.
- uid/gid — пользователь и группа, от которых будет выполнена синхронизация для конкретного ресурса. Именно они будут назначены в качестве владельца файлов.
- auth users — проверка подлинности, вводом логина с паролем.
- secrets file — файл, в котором размещены логин и пароль, который будет использоваться для проверки подлинности при выполнении синхронизации.
- pre-xfer exec/post-xfer exec — команды, которые необходимо выполнить, соответственно, перед синхронизацией и после. Полезно, если наш веб-сервер необходимо перезапускать после обновления контента. Например: post-xfer exec = /usr/bin/systemctl reload uwsgi.
- hosts allow — узлы, с которых разрешено подключение для синхронизации. Тут должен быть IP-адрес нашего сервера GitLab.
Создадим файл, в котором должны быть логин и пароль для проверки подлинности rsync:
vi /etc/rsyncd.scrt
rsync_dmosk:password
* в данном примере мы задали логин rsync_dmosk и пароль password.
Необходимо задать минимально необходимые права на файл с аутентификационными данными:
chmod 600 /etc/rsyncd.scrt
Убедимся, что у целевого каталога выставлен правильный владелец:
chown -R apache:apache /var/www/dmosk/www
Можно перезапускать сервис:
systemctl restart rsyncd || systemctl restart rsync
Также необходимо создать правила в брандмауэре для разрешения TCP-порта 873, на котором работает rsyncd.
а) для систем на базе deb-пакетов (Ubuntu, Debian):
iptables -I INPUT 1 -p tcp --dport 873 -j ACCEPT
apt-get install iptables-persistent
netfilter-persistent save
б) для систем на базе RPM-пакетов (Red Hat, CentOS):
firewall-cmd --permanent --add-port=873/tcp
firewall-cmd --reload
Данные настройки выполняем на всех веб-серверах. После переходим к настройке сервера GitLab.
Настройка GitLab
На стороне сервера GitLab мы должны настроить подключение к сервисам rsyncd. Для начала устанавливаем rsync.
а) для систем на базе deb:
apt-get install rsync
б) для RPM-систем:
yum install rsync
После создаем файл, в котором будем хранить пароль для подключения к rsyncd:
vi /etc/rsyncd.scrt
password
* это тот пароль, который мы задали в аналогичном файле на стороне веб-серверов.
Задаем права минимально необходимые для чтения файла с паролем:
chmod 640 /etc/rsyncd.scrt
Задаем в качестве группы владельца файла с паролем нашего пользователя gitlab-runner:
chown :gitlab-runner /etc/rsyncd.scrt
Создаем файл, который отправим на серверы веб в качестве теста:
touch testfile
Выполняем команду для синхронизации данного файла с веб-серверами:
for i in 1 2 3 4 5; do rsync -rult --password-file=/etc/rsyncd.scrt testfile rsync_dmosk@web-0$i::dmosk; done
* обратите внимание, что в моем примере веб-серверы имеют имена web-01, web-02 и так далее, поэтому, чтобы не выполнять все 5 команд по отдельности, мы используем цикл, в котором подставляем разные цифры в названия серверов.
В итоге, на стороне веб-серверов должен появиться файл testfile. Теперь остается последний шаг — настроить созданный ранее CI/CD для синхронизации.
Настройка синхронизации в CI/CD
Переходим на страницу нашего проекта и кликаем по CI/CD configuration:
Чтобы открылся редактор, кликаем по Edit:
Или из командной строки, можно открыть на редактирование наш файл .gitlab-ci.yml:
vi .gitlab-ci.yml
Меняем содержимое нашего файла:
stages:
- copy
copy:
stage: copy
script: for i in 1 2 3 4 5; do rsync -rult --delete-after --exclude=.git/ --exclude=.gitlab-ci.yml --password-file=/etc/rsyncd.scrt $CI_PROJECT_DIR/ rsync_dmosk@web-0$i::dmosk; done
* мы заменили наш этап test на copy. В данном примере мы выполняем команду для запуска синхронизации с веб-серверами с помощью rsync. В качестве источника данных мы используем переменную $CI_PROJECT_DIR, в которой находится наш проект. В качестве экземпляра, куда синхронизируем данные используем dmosk.
Готово. Пробуем выполнить git push в наш проект. Данные должны разойтись по всем веб-серверам.
Дополнительно
Дополнительная информация, которая может быть полезна.
Запуск заданий внутри контейнера Docker
Выше мы рассмотрели регистрацию раннера, который будет запускать выполнение команд в системной оболочке (shell). Но если мы хотим, чтобы задания pipeline выполнялись внутри контейнера Docker, то пошагово мы должны сделать следующее.
Основные шаги:
1. Устанавливаем Docker Engine. Подробнее об этом смотрите инструкцию Установка Docker на Linux.
2. При регистрации раннера на последнем этапе, где предлагается выбрать средство запуска (Enter an executor), выбираем docker:
…
Enter an executor: parallels, virtualbox, docker+machine, docker-ssh+machine, kubernetes, custom, docker, docker-ssh, shell, ssh:
docker
3. При написании pipeline мы должны добавить опцию image с указанием образа, который хотим использовать:
…
copy:
stage: copy
image: dmosk/ubuntu:latest
…
* в противном случае runner будет выполнять задания в контейнере по умлчанию (его мы указываем при регистрации на Gitlab).
Дополнительно:
По умолчанию, runner всегда будет пытаться скачать образ Docker с внешнего источника. Если на целевом компьютере, где запускается runner у нас уже есть нужный образ и мы хотим, чтобы использовался именно он, открываем файл:
vi /etc/gitlab-runner/config.toml
Среди:
[[runners]]
… находим созданный раннер (определяем по описанию, которое мы задавали при регистрации) и в нем также находим [runners.docker]. Добавим опцию pull_policy:
[[runners]]
...
[runners.docker]
...
pull_policy = "if-not-present"
Перезапустим сервис.
После внесения всех нужных изменений, выполним команду, чтобы применить их:
systemctl restart gitlab-runner
Возможные ошибки
status couldn execute post against certificate signed by unknown authority
Ошибка возникает при попытке зарегистрировать Runner, а при отправке curl-запроса на сервер:
curl https://gitlab.dmosk.ru
… мы получаем сообщение о неправильном сертификате:
curl performs SSL certificate verification by default, using a "bundle"
of Certificate Authority (CA) public keys (CA certs). If the default
bundle file isn't adequate, you can specify an alternate file
using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
the bundle, the certificate verification probably failed due to a
problem with the certificate (it might be expired, or the name might
not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
the -k (or --insecure) option.
Причина: нужна полная цепочка сертификатов.
Решение: подробнее, процесс настройки https описан в инструкции Правильная настройка SSL в NGINX.
@ERROR: chroot failed
Ошибка появляется при попытке синхронизировать файлы с применением команды rsync.
Причины:
1. На целевом сервере нет целевого каталога (указан в опции path), в который необходимо синхронизировать данные.
2. Доступ к целевой папке запрещен политикой selinux.
Решение: для обоих причин опишим соответствующие решения.
1. Проверяем наличие каталога, который мы указали в конфигурационном файле /etc/rsyncd.conf (опция path). Если его нет, создаем, например:
mkdir -p /var/www/dmosk/www
2. Для начала пробуем отключить разово selinux:
setenforce 0
Если это решило проблему, либо отключаем его совсем, либо настраиваем командами:
semanage fcontext -a -t rsync_data_t '/var/www(/.*)?'
restorecon -Rv '/var/www'
setsebool -P rsync_client on
* в данном примере мы разрешам контекст безопасности rsync_data_t для всего содержимого каталога, где находятся наши сайты.
Dial unix /var/run/docker.sock: connect: permission denied
Если мы пытаемся работать с Docker из шела, то можем увидеть ошибку на подобие:
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post “http://%2Fvar%2Frun%2Fdocker.sock/v1.24/build?buildargs=%7B%7D&cachefrom=%5B%5D&cgroupparent=&cpuperiod=0&cpuquota=0&cpusetcpus=&cpusetmems=&cpushares=0&dockerfile=Dockerfile&labels=%7B%7D&memory=0&memswap=0&networkmode=default&rm=1&shmsize=0&t=skill%2Fdjango%3Av1&target=&ulimits=null&version=1”: dial unix /var/run/docker.sock: connect: permission denied
Причина:
Для подключения к docker engine у пользователя gitlab-runner нет прав.
Решение:
Достаточно добавить пользователя gitlab-runner в группу docker. Это можно сделать командой:
usermod -aG docker gitlab-runner