Add gitlab-runner-docker-mtls/readme.MD
This commit is contained in:
parent
fa19c7c29e
commit
1f45d681c3
214
gitlab-runner-docker-mtls/readme.MD
Normal file
214
gitlab-runner-docker-mtls/readme.MD
Normal file
@ -0,0 +1,214 @@
|
||||
# Автоматическая регистрация 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/)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user