Provision
—— XP

GitLab Runner: кто выполняет задачи

теория~6 минут+210 XP

Кто на самом деле выполняет команды из .gitlab-ci.yml? Не сам GitLab: он хранит описание конвейера, раздаёт работу и показывает результат, но ни одной команды не запускает. Это делает GitLab Runner — отдельная программа на какой-то машине. Пока раннера нет, конвейер стоит, сколько бы задач в нём ни было, поэтому без этого урока ни одна следующая практика не заработает.

Раннер написан на Go, ставится пакетом или запускается контейнером gitlab/gitlab-runner, и одна его копия может обслуживать много проектов. С GitLab они в тех же отношениях, что диспетчер такси с водителем: диспетчер принимает заказы, но за руль не садится, а водитель сам выходит на линию и спрашивает «есть заказ?». Отсюда главное свойство раннера: команды выполняются в предсказуемом окружении и там, где они нужны, например рядом с твоим стендом.

Как раннер получает работу

Раннер раз в несколько секунд сам обращается к GitLab по его адресу (external_url) и спрашивает, нет ли задач для него. Получил — выполнил, отправил журнал и результат обратно.

Две колонки: платформа хранит описание, историю и секреты, но ничего не выполняет; раннер забирает задачу, выполняет и отчитывается. Ниже три следствия того, где именно работает раннер.
Задачу забирает раннер сам — соединение идёт изнутри наружу, поэтому порты открывать не надо. А от того, где он стоит, зависит и скорость сборки, и что ему вообще доступно.

Из направления соединения следует удобная вещь: раннер может стоять за домашним роутером или в закрытой сети, и ему не нужны входящие порты. Нужно только, чтобы он видел GitLab.

Задача без подходящего раннера не падает, а висит в статусе pending с подписью «This job is stuck». Это первая типичная грабля: конвейер «не запускается», а на деле его просто некому выполнить.

Исполнители

Раннер сам задачу не выполняет — он поручает её исполнителю (executor). Исполнитель определяет, где именно пойдут команды. Тебе нужны два:

Исполнители, которые встретишь
docker
Каждая задача — в новом контейнере из образа, указанного в image. После задачи контейнер удаляется. Самый частый выбор.
shell
Команды идут прямо на машине раннера от его пользователя. Ключ image игнорируется. Нужен, когда задача должна трогать саму машину.

Есть и другие — kubernetes (каждая задача в поде кластера), ssh, virtualbox, — но в первый месяц работы ты увидишь именно эти два. Мы возьмём docker: он изолирует задачи друг от друга и каждый раз начинает с чистого листа.

Для сборки образов внутри задачи нужен Docker, а внутри контейнера задачи его нет. Самый простой выход — пробросить в контейнер задачи сокет Docker с хоста, /var/run/docker.sock: это файл-дверь, через который программа docker разговаривает с демоном. Тогда команда docker build в задаче на деле выполняется демоном стенда.

Удобство стоит дорого: доступ к сокету — это фактически root на машине. Любая задача сможет запустить любой контейнер с любыми томами. На учебном стенде это приемлемо, на рабочем сервере для сборки берут отдельную машину или инструменты без демона — Kaniko, Buildah.

Только раннер с любым исполнителем ничего не выполнит, пока GitLab ему не доверяет: случайная программа не должна забирать задачи с секретами твоего проекта.

Регистрация по токену

Чтобы раннер начал брать задачи, его регистрируют. С GitLab 16 способ такой: сначала раннер создают в интерфейсе — в проекте Settings → CI/CD → Runners → New project runner. Там же задают теги и галочку «брать задачи без тегов». GitLab в ответ показывает токен с префиксом glrt- — один раз, потом его не посмотреть.

Затем на машине раннера запускают gitlab-runner register и отдают ему адрес GitLab, этот токен и тип исполнителя. Раннер записывает всё в файл config.toml и выходит на линию. В интерфейсе рядом с раннером загорается зелёный кружок — он на связи.

В старых статьях ты встретишь другой способ: один общий registration token проекта, который вставляли в команду. Он устарел, с GitLab 18 выключен по умолчанию, и пользоваться им не надо.

Теги — метки раннера, по которым задача выбирает исполнителя. Задача с tags: [docker] пойдёт только к раннеру с таким тегом. Если раннеру не разрешено брать задачи без тегов, а у задачи тегов нет, она повиснет в pending — вторая типичная грабля.

Раннеры бывают трёх уровней: проекта (обслуживает один проект), группы (все проекты группы) и инстанса (весь GitLab, создаёт администратор). На стенде хватит раннера проекта.

Словарь урока

Раннер
Программа gitlab-runner, которая сама забирает задачи у GitLab и выполняет их. ↩ к тексту
Исполнитель
Способ выполнения задачи: docker — в новом контейнере, shell — прямо на машине. ↩ к тексту
Токен раннера
Ключ с префиксом glrt-, который GitLab выдаёт при создании раннера в интерфейсе. Передаётся команде register.
config.toml
Файл настроек раннера: адрес GitLab, токен, исполнитель, тома для контейнеров задач.
Тег раннера
Метка, по которой задача выбирает раннер. Нет подходящего — задача висит в pending.

Что спросят на собеседовании

  • Конвейер завис в pending. Что проверить?
    Есть ли раннер на связи для этого проекта, совпадают ли теги задачи и раннера, разрешено ли раннеру брать задачи без тегов. Чаще всего дело в тегах.
  • Чем опасен проброс docker.sock в задачи?
    Доступ к сокету равен root на машине: задача может запустить любой контейнер с любым томом. Сборочный раннер держат на отдельной машине или собирают через Kaniko и Buildah.

Что дальше

Дальше — поднять раннер рядом с GitLab и зарегистрировать его по токену.

Проверь себя+210 XPдве попытки
1
Как раннер работает
Кто к кому подключается, когда раннер получает задачу?
2
Исполнители
Что делает исполнитель docker с каждой задачей?
3
Регистрация
Откуда в новом способе регистрации берётся токен с префиксом glrt-?
4
Безопасность
Почему раннер с доступом к Docker-сокету хоста опасен?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.