TNT/devops
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
devops/gitlab-runner-docker-mtls/readme.MD

6.4 KiB
Raw Blame History

Автоматическая регистрация GitLab Runner с mTLS

Этот проект позволяет автоматически зарегистрировать GitLab Runner, подключающийся к Docker Daemon через mTLS (взаимную аутентификацию). Это необходимо, когда Docker работает в безопасном режиме: tcp://host:2376 с сертификатами.

Использование mTLS — лучшая практика для production-сред.

Требования

  1. Установленные Docker и Docker Compose.
  2. Доступ к GitLab-серверу.
  3. Токен регистрации раннера (REGISTRATION_TOKEN) — см. ниже.
  4. Docker Daemon, настроенный на mTLS (порт 2376, сертификаты: ca.pem, cert.pem, key.pem).
  5. Сертификаты должны быть доступны на хосте в папке ./certs.

Получение токена регистрации раннера (REGISTRATION_TOKEN)

Токен используется для регистрации Runner в GitLab. Его можно получить на разных уровнях:

1. Для проекта

  • Перейдите в проект → Settings → CI/CD → Runners.
  • В разделе Set up a specific Runner manually скопируйте Registration token.

2. Для группы

  • Откройте группу → Group Settings → CI/CD → Runners.
  • Скопируйте Registration token из раздела регистрации.

3. Для администратора (общие раннеры)

  • Перейдите в Admin Area → Overview → Runners.
  • Скопируйте Registration token из раздела Set up a shared Runner manually.

Начиная с GitLab 17.7, токены стали называться Runner authentication tokens, и их срок действия ограничен. При истечении — обновите токен и перезапустите контейнер.

Инструкция по настройке

1. Создайте структуру проекта

git clone https://gitlab01.pm.org.ru/devops/infra/docker-compose/ci_cd_systems/gitlab/gitlab-runner-docker-mtls.git

Скопируйте в паку ./certs следующие файлы: ca.pem, cert.pem, key.pem

.
├── docker-compose.yml
├── .env
├── register-runner.sh
└── certs/
    ├── ca.pem
    ├── cert.pem
    └── key.pem

2. Заполните .env

# Образ и имя контейнера
CONTAINER_IMAGE=gitlab/gitlab-runner:latest
CONTAINER_NAME=gitlab-runner-mtls

# Настройки подключения к GitLab
CI_SERVER_URL=https://gitlab.example.com
REGISTRATION_TOKEN=glrt-xxxxxxxxxx

# Executor и образ
EXECUTOR=docker
DOCKER_IMAGE=docker:27.3.1
DESCRIPTION=MTLS-Enabled Docker Runner

# Параллелизм
CONCURRENT=10

# Отключение кэша (true/false)
DISABLE_CACHE=false

# Настройки mTLS для Docker
DOCKER_HOST=tcp://your-docker-host-ip:2376
DOCKER_TLS_VERIFY=true
CERT_PATH=/certs

Замените your-docker-host-ip на IP-адрес сервера с Docker Daemon (например, 192.168.1.10).

Убедитесь, что скрипт исполняемый:

chmod +x register-runner.sh

3. docker-compose.yml

version: '3'
services:
  gitlab-runner:
    image: ${CONTAINER_IMAGE}
    container_name: ${CONTAINER_NAME}
    restart: always
    env_file:
      - .env
    volumes:
      - ./config:/etc/gitlab-runner
      - ./certs:/certs:ro
    entrypoint: ["/register-runner.sh"]

Не монтируйте в docker-compose.yml /var/run/docker.sock — он не нужен при mTLS.

4. Запустите Runner

# Запустите
docker-compose up -d

7. Проверьте логи

docker-compose logs -f

Ожидаемый вывод:

Registering GitLab Runner with mTLS-enabled Docker executor...
...
Starting GitLab Runner...

Проверка: config.toml

После запуска в папке ./config появится config.toml. Он должен содержать:

concurrent = 10

[[runners]]
  name = "MTLS-Enabled Docker Runner"
  url = "https://gitlab.example.com"
  token = "glrt-..."
  executor = "docker"
  [runners.docker]
    host = "tcp://your-docker-host-ip:2376"
    tls_verify = true
    cert_path = "/certs"
    image = "docker:27.3.1"
    disable_cache = false
    remove_container = true

Требования к сертификатам

GitLab Runner ожидает в CERT_PATH файлы с конкретными именами:

Файл Назначение
ca.pem Корневой сертификат
cert.pem Клиентский сертификат
key.pem Приватный ключ

Если у вас другие имена — переименуйте:

mv ca.crt ca.pem
mv client-cert.pem cert.pem
mv client-key.pem key.pem

Возможные проблемы

Проблема Решение
x509: certificate signed by unknown authority Убедитесь, что ca.pem подписан доверенным CA
tls: bad certificate Проверьте, что cert.pem и key.pem соответствуют друг другу
connection refused Проверьте, открыт ли порт 2376 и разрешён ли доступ с IP Runner'а
config.toml: Key already defined Удалите config.toml и перезапустите

Преимущества этого подхода

  • Никакого docker.sock — безопаснее.
  • Автоматическая регистрация.
  • Поддержка mTLS "из коробки".
  • Готово к production.

Дополнительно