# Автоматическая регистрация 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/)