215 lines
6.4 KiB
Markdown
215 lines
6.4 KiB
Markdown
# Автоматическая регистрация 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. Создайте структуру проекта
|
||
|
||
```bash
|
||
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`
|
||
|
||
```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`).
|
||
|
||
---
|
||
|
||
|
||
> Убедитесь, что скрипт исполняемый:
|
||
> ```bash
|
||
> chmod +x register-runner.sh
|
||
> ```
|
||
|
||
---
|
||
|
||
### 3. `docker-compose.yml`
|
||
|
||
```yaml
|
||
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
|
||
|
||
```bash
|
||
# Запустите
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
### 7. Проверьте логи
|
||
|
||
```bash
|
||
docker-compose logs -f
|
||
```
|
||
|
||
Ожидаемый вывод:
|
||
```
|
||
Registering GitLab Runner with mTLS-enabled Docker executor...
|
||
...
|
||
Starting GitLab Runner...
|
||
```
|
||
|
||
---
|
||
|
||
## Проверка: `config.toml`
|
||
|
||
После запуска в папке `./config` появится `config.toml`. Он должен содержать:
|
||
|
||
```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` | Приватный ключ |
|
||
|
||
> Если у вас другие имена — переименуйте:
|
||
> ```bash
|
||
> 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.
|
||
|
||
---
|
||
|
||
## Дополнительно
|
||
|
||
- [Официальная документация GitLab Runner](https://docs.gitlab.com/runner/)
|
||
- [Настройка Docker с mTLS](https://docs.docker.com/engine/security/protect-access/)
|
||
- [GitLab CI/CD Pipeline Configuration](https://docs.gitlab.com/ee/ci/yaml/)
|
||
|