Minio для общего кеша GitLab Runner

Быстрые ссылки

• В чём проблема?
• Установка Minio
• Создание конфигурационного файла Minio
• Настройка Minio для GitLab
• Настройка GitLab Runner
• Запуск CI задач
• Проверка и отладка
• Безопасность и эксплуатация
• Заключение

Определение: Minio — легковесное S3-совместимое объектное хранилище. GitLab Runner — агент, выполняющий CI/CD задачи. “Кеш” — архивированные файлы, которые ускоряют повторные сборки.

В чём проблема?

GitLab CI поддерживает директиву

cache

для ускорения последующих запусков. По умолчанию кеш сохраняется локально на каждом экземпляре runner’а. Это подходит для одиночных executor’ов, но мешает, когда у вас несколько параллельных job’ов или несколько runner’ов.

Проблема в том, что локальный кеш не разделяется между параллельными исполнениями. В результате параллельные job’ы не видят кеш друг друга и страдает скорость pipeline. Переход на S3-совместимое объектное хранилище (Minio) даёт общую область хранения для кешей, что повышает шанс попадания в кеш и делает восстановление предсказуемым при параллельных запусках.

Важно: директива cache задумывалась для оптимизации, а не как средство передачи обязательных артефактов между job’ами. Однако на практике многие команды используют кеш для передачи данных — и в этом случае общий кеш решает проблему параллельного доступа.

Установка Minio

Minio Server доступен в виде бинарного файла и как пакеты

.deb

и

.rpm

. В этом руководстве мы используем Debian-пакет. Если вы используете сырую бинарную сборку, потребуется вручную добавить сервисный скрипт в вашу систему init (systemd, SysV и т.п.), чтобы Minio запускался автоматически.

Скачайте и установите пакет

.deb

по инструкции с официального сайта, чтобы получить актуальную версию. После установки пакет добавит бинарный файл и описание systemd-сервиса.

Minio ожидает выполнения под отдельным системным пользователем. Создайте его:

sudo useradd -r minio-user -s /sbin/nologin

Создайте директорию для данных Minio. Все объекты будут храниться здесь. В примере используется /mnt/minio. Присвойте её владельцем minio-user:

sudo mkdir -p /mnt/minio

sudo chown -R minio-user:minio-user /mnt/minio

sudo chmod -R 0775 /mnt/minio

После установки убедитесь, что systemd-сервис Minio присутствует (обычно /lib/systemd/system/minio.service). Запускать сервис будем позже, после создания конфигурации.

Создание конфигурационного файла Minio

Minio загружает значения конфигурации из /etc/default/minio. Создайте этот файл и добавьте:

MINIO_ROOT_USER="minio"

MINIO_ROOT_PASSWORD="P@$$w0rd"

MINIO_OPTS="--address :9600 --console-address :9601"

MINIO_VOLUMES="/mnt/minio"

Первые две строки определяют имя и пароль root-пользователя Minio. Обязательно замените P@$$w0rd на надёжный секрет в вашей среде.

MINIO_OPTS задаёт параметры запуска: в примере сервер слушает порт 9600, а веб-консоль доступна на 9601. MINIO_VOLUMES указывает каталог для хранения объектов — это /mnt/minio, созданный ранее.

Проверьте права файла конфигурации:

sudo chown minio-user:minio-user /etc/default/minio

Запустите сервис и откройте веб-консоль в браузере по адресу http://localhost:9601. Введите root-учётные данные.

sudo service minio start

Важно: если вы планируете публиковать Minio наружу, настройте HTTPS и ограничьте доступ с помощью брандмауэра и/или reverse-proxy.

Настройка Minio для GitLab

Создайте bucket для хранения кешей pipelines. В веб-консоли выберите «Buckets» → «Create Bucket» и введите имя bucket’а. В простом локальном развёртывании дополнительные функции (версионирование, шифрование на сервере) могут быть недоступны — они не обязательны для базовой работы кеша.

После создания bucket’а создайте пользователя для GitLab Runner. В разделе «Users» нажмите «Create User». Рекомендуется не использовать root-учётную запись в GitLab.

• В поле Access Key введите, например, gitlab.
• В поле Secret Key укажите надёжный пароль.
• Присвойте политику readwrite.

GitLab должен иметь права на запись и чтение кешей.

Настройка GitLab Runner

Откройте конфигурационный файл GitLab Runner, обычно расположенный в /etc/gitlab-runner/config.toml на Omnibus-инсталляциях. Найдите секцию [runners.cache] и добавьте/измените следующие строки:

[runners.cache]

Type = "s3"

Shared = true

[runners.cache.s3]

AccessKey = "gitlab"

SecretKey = "P@$$w0rd"

BucketName = "gitlab"

Insecure = true

ServerAddress = "192.168.0.1:9600"

Описание полей:

• Type — указывает GitLab, что используется S3-совместимое хранилище.
• Shared — включает общий режим кеша для параллельных job’ов.
• AccessKey / SecretKey — совпадают с учётной записью Minio, созданной ранее.
• BucketName — имя bucket’а в Minio.
• Insecure — true позволяет работать по HTTP; в продакшне лучше настроить HTTPS и выставить Insecure = false.
• ServerAddress — IP или DNS и порт Minio-сервера.

Перезапустите GitLab Runner:

sudo gitlab-runner restart

Совет: при использовании нескольких runner’ов убедитесь, что все они указывают на один и тот же bucket и одни и те же учётные данные.

Запуск CI задач

После настройки ваши job’ы должны загружать и выгружать кеши в Minio. В логах CI вы увидите строки наподобие Uploading cache.zip, а при восстановлении — cache.zip is up to date и successfully extracted cache.

Вы также можете просматривать содержимое bucket’а в Minio Console — GitLab создаёт папку для каждого project ID и хранит ZIP-архивы кешей по веткам и именам кеша.

Проверка и отладка

Ключевые шаги при проверке работоспособности:

1. Проверьте доступность Minio с машины runner’а: curl http://192.168.0.1:9600 или используйте mc (Minio client).
2. Убедитесь, что AccessKey/SecretKey одинаковы в Minio и в config.toml.
3. Посмотрите логи GitLab Runner и CI job’ов на предмет ошибок загрузки/скачивания.
4. Проверьте, что в bucket’е появляются ZIP-файлы после успешного run’а.

Типичные ошибки и причины:

• “403 Forbidden” — неверные ключи или политика пользователя недостаточна.
• Сетевые таймауты — DNS/маршрутизация/брандмауэр блокируют соединение.
• Неправильный путь к bucket’у — GitLab ожидает точное имя.

Критерии приёмки:

• После успешной сборки в Minio появился ZIP-файл кеша.
• Параллельные job’ы восстанавливают кеш и показывают successfully extracted cache.
• Нет ошибок доступа в логах Runner’а.

Безопасность и эксплуатация

Важно обеспечить безопасность объектного хранилища:

• Используйте HTTPS: настройте reverse-proxy (nginx, Traefik) или TLS в Minio, чтобы шифровать трафик. Затем установите Insecure = false в config.toml.
• Минимизируйте права: создайте отдельного пользователя с политикой readwrite только на нужный bucket.
• Ограничьте доступ через брандмауэр: разрешите доступ к порту только для GitLab Runner’ов.
• Резервное копирование: хотя кеши можно пересчитывать, храните резервные копии важных артефактов и конфигурации Minio.
• Мониторинг: собирайте метрики дискового пространства и латентности. Регулярно очищайте старые кеши.

Рекомендации по политике bucket’ов и IAM:

• Политика должна разрешать только get/put/list для конкретного bucket’а.
• Не используйте root-учётные данные в CI.

Жёсткая защита передачи секрета

Храните AccessKey/SecretKey в секции runner’а на защищённых машинах, либо используйте секреты и vault-решения — не храните открытые ключи в репозиториях.

Альтернативные подходы и когда Minio не подходит

Альтернативы:

• Облачные S3-сервисы (AWS S3, DigitalOcean Spaces) — проще в масштабировании, но платно.
• Central NFS/SMB-хранилище — можно использовать как общий том, но часто медленнее и сложнее для большого количества мелких файлов.
• CI-плагин-стратегии: сохранять артефакты как job artifacts вместо кеша, если требуется жёсткая гарантия доставки.

Когда Minio может не подойти:

• Если у вас высокие требования к доступности и репликации — локальный Minio на одном диске не обеспечит отказоустойчивость.
• Если вы не готовы управлять HTTPS, бэкапом и безопасностью — облачный S3 может быть проще.

Модель принятия решений (Mermaid)

flowchart TD
  A[Нужен общий кеш для GitLab?] -->|Нет| B[Оставить локальный кеш]
  A -->|Да| C[Требуется отказоустойчивость?]
  C -->|Да| D[Рассмотреть облачный S3 или HA Minio]
  C -->|Нет| E[Minio локально достаточно]
  E --> F[Настроить Minio + HTTPS + мониторинг]
  D --> G[Облачный S3 / многорегионный Minio]

Руководство по внедрению (SOP)

Шаги для команды DevOps:

1. Подготовить сервер с диском и сетевым доступом от runner’ов.
2. Установить Minio и создать пользователя minio-user.
3. Создать /etc/default/minio и задать секреты.
4. Создать bucket и user в Minio Console.
5. Настроить config.toml у каждого GitLab Runner’а.
6. Перезапустить runner’ы и запустить тестовую pipeline.
7. Проверить появление ZIP в bucket’е и восстановление кеша.
8. Включить HTTPS и обновить Insecure = false.

Проверочные тесты (Acceptance):

• Запустить pipeline с явным кешированием, дождаться Uploading cache.zip.
• Запустить параллельные job’ы, убедиться, что восстановление кеша происходит корректно.
• Проверить отсутствие ошибок доступа и корректность прав в Minio.

План восстановления инцидента

Симптом: runner не может загрузить кеш — ошибки 403/404/timeout.

1. Проверить сетевую доступность Minio: curl -v http://:9600.
2. Проверить учётные данные в config.toml.
3. Проверить права пользователя в консоли Minio.
4. Если диск заполнен — удалить старые кеши через консоль или mc.
5. Восстановить конфигурацию из резервной копии, если она была перезаписана.
6. При необходимости временно переключить runner обратно на локальный кеш (rollback).

Критерий отката (rollback): если среднее время сборки после перехода на Minio увеличилось существенно и это не исчерпывается оптимизацией, вернуть локальный кеш и провести дополнительный анализ.

Рекомендации по мониторингу и TCO

Что мониторить:

• Доступность Minio (HTTP(S) health checks).
• Использование диска и рост bucket’а.
• Время загрузки/скачивания ZIP-файлов.

Impact×Effort: переход на Minio обычно даёт средний-высокий эффект по снижению времени CI при умеренном усилии по установке и настройке. Если инфраструктура уже управляемая, усилия малы.

Совместимость и миграция

• GitLab поддерживает S3-совместимый API, поэтому Minio совместим без кода.
• При миграции с облака на локальный Minio убедитесь, что ключи и имена bucket’ов совпадают, или обновите config.toml и правило именования кешей.
• При масштабировании используйте распределённые диски или Minio в режиме Erasure Coding / distributed mode (за пределами этой инструкции).

Рольные чек-листы

Администратор Minio:

• Установил Minio и пользователи/политики.
• Настроил TLS и брандмауэр.
• Обеспечил мониторинг и бэкап.

DevOps-инженер (GitLab):

• Настроил config.toml всех runner’ов.
• Протестировал pipeline и восстановление кеша.
• Настроил запись секретов и ротацию ключей.

Разработчик:

• Обновил .gitlab-ci.yml, чтобы корректно использовались кеши.
• Проверил, что параллельные job’ы получают кеш.

Примеры конфигураций и шаблоны

Пример минимального .gitlab-ci.yml с кешем:

cache:
  key: "my-cache"
  paths:
    - node_modules/

stages:
  - build

build-job:
  stage: build
  script:
    - npm ci
    - npm run build

Критерии приёмки (повтор):

• node_modules упакованы в cache.zip и загружены в Minio.
• Следующая задача получает successfully extracted cache.

Глоссарий (1 строка)

• Minio — S3-совместимое объектное хранилище с лёгким развёртыванием.
• S3 — API хранения объектов, разработанный Amazon.
• GitLab Runner — агент выполнения CI/CD job’ов.
• Bucket — логическая корзина для объектов в S3-совместимом хранилище.
• Cache — файлы, сохраняемые между запусками для ускорения сборок.

Заключение

Minio — простой и быстрый способ получить общий кеш для GitLab Runner без использования облачных сервисов. Для базовой работы достаточно локального развёртывания, но в продакшне рекомендуются HTTPS, ограничения доступа и мониторинг. Тестируйте изменения, следите за производительностью pipeline и корректируйте политику хранения кешей.

Важно: общий кеш помогает при параллельных job’ах, но добавляет накладные операции — архивирование и загрузку. Наблюдайте за метриками сборки после перехода, чтобы убедиться, что эффект положительный.

Краткая памятка: создайте отдельного пользователя Minio с правами readwrite, используйте HTTPS в продакшне, и проверяйте логи CI и содержимое bucket’а для уверенности в работоспособности.