From 1f45d681c3fde73d2ed40c604b7759afb427660d Mon Sep 17 00:00:00 2001
From: pashko <pm@pm.org.ru>
Date: Sat, 9 Aug 2025 19:19:26 +0800
Subject: [PATCH] Add gitlab-runner-docker-mtls/readme.MD

---
 gitlab-runner-docker-mtls/readme.MD | 214 ++++++++++++++++++++++++++++
 1 file changed, 214 insertions(+)
 create mode 100644 gitlab-runner-docker-mtls/readme.MD

diff --git a/gitlab-runner-docker-mtls/readme.MD b/gitlab-runner-docker-mtls/readme.MD
new file mode 100644
index 0000000..dcde1b7
--- /dev/null
+++ b/gitlab-runner-docker-mtls/readme.MD
@@ -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/)
+