Очистка Container Registry в GitLab

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

Настройка политики очистки
Использование API
Последствия политики очистки
Сбор мусора (Garbage Collection)
Удаление немаркированных манифестов и слоёв
Запуск сборки мусора по расписанию
Ограничения сборки мусора

Графика с логотипом GitLab и стилизованной головой лисы

GitLab Container Registry предоставляет место для хранения Docker-образов рядом с исходным кодом проекта. Если хранить в реестре большие образы и часто пушить новые версии, расход диска быстро растёт: Registry по умолчанию сохраняет все слои навсегда, даже когда они перестали быть релевантны. В статье описано, как грамотно освободить место: сначала снять теги (cleanup policy), затем удалить неиспользуемые слои через garbage collection.

Настройка политики очистки

Первый шаг — настроить Container Registry Cleanup Policy для каждого проекта. Политики применяются на уровне проекта, поэтому вы можете задать разные правила для разных репозиториев.

Скриншот ссылки Settings в боковой панели GitLab

Перейдите в ваш проект в GitLab и откройте ссылку “Settings” в боковой панели. Выберите раздел “CI / CD” и разверните блок “Clean up image tags” внизу страницы.

Скриншот настроек политики очистки Container Registry GitLab

Переключите кнопку “Enabled” в положение включено, чтобы активировать политику. Затем выберите частоту запуска — “every day” (ежедневно) — надёжный вариант по умолчанию.

Скриншот настроек политики очистки Container Registry GitLab

Секция “Keep these tags” позволяет указать теги, которые политика не тронет. Опции “keep the most recent” и “keep tags matching” независимы друг от друга. Например, можно сохранить теги:

dev

nightly

вместе с пятью самыми свежими тэгами. Тег latest всегда включается дополнительно к указанным.

Скриншот настроек политики очистки Container Registry GitLab

Секция “Remove these tags” определяет белый список тегов, которые подлежат удалению. Теги, не совпадающие с regex-выражением, затронуты не будут. Измените значение “Remove tags older than”, чтобы установить максимальный срок жизни тега до его удаления. Нажмите зелёную кнопку “Save” для сохранения.

Важно: политика удаляет только теги (метаданные). Непосредственное удаление данных (слоёв образов) требует дополнительного шага — сборки мусора.

Использование API

Если нужно настроить политику для множества проектов, удобнее делать это через API, а не вручную через веб-интерфейс.

Пример корректной команды curl для применения политики (замените и на реальные значения):

curl --request PUT \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --header "PRIVATE-TOKEN: " \
  --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":"latest"}}' \
  "https://gitlab.example.com/api/v4/projects/"

Скриншот ID проекта в GitLab

Токен доступа можно создать на странице профиля в GitLab. Подставьте сгенерированный токен вместо . ID проекта находится на странице проекта в GitLab — используйте его в URL.

Запуск команды выше создаст политику, которая выполняется раз в месяц и очищает теги старше 14 дней. Тег latest и последний по времени (keep_n=1) останутся; остальные теги, подходящие под name_regex_delete (в примере — всё .*), попадут в область удаления.

Последствия политики очистки

Политика очистки удаляет теги у образов согласно критериям. Эти теги больше не будут отображаться в интерфейсе Container Registry проекта и их нельзя будет подтянуть (pull) по удалённому тегу.

Важно: удаление тегов не равнозначно удалению самих слоёв из дискового хранилища. После удаления тегов метаданные исчезают, но слои остаются на сервере до выполнения garbage collection. Поэтому сразу после очистки тегов вы можете не увидеть уменьшения использования диска.

Сбор мусора (Garbage Collection)

Garbage Collection удаляет слои образов, которые не связаны ни с одним тегом или манифестом. Это ключевой этап для фактической очистки диска.

Сбор мусора нужно запускать вручную на сервере GitLab по SSH. Пример команды для постинсталляций Omnibus GitLab:

sudo gitlab-ctl registry-garbage-collect

Процесс пройдёт по всем проектам и удалит неиспользуемые слои. Если до этого была запущена политика очистки, сбор мусора удалит данные, которые стали невидимы в UI.

Обычно на загружённых инсталляциях первый запуск может вернуть значительный объём свободного места — от сотен мегабайт до десятков гигабайт, в зависимости от истории пушей и объёма контейнерных слоёв.

Удаление немаркированных манифестов и слоёв

Чтобы освободить ещё больше места, можно запустить более агрессивную очистку, удалив немаркированные манифесты и нетронутые слои. Это более рискованная операция, но часто желаемая:

sudo gitlab-ctl registry-garbage-collect -m

Флаг -m удалит слои, которые не связаны с тэгированными манифестами. Это приведёт к потере кэша слоёв и промежуточных шагов сборки.

Почему это отключено по умолчанию: Docker и Registry хранят слои по хешу содержимого. Даже если слой не имеет тега, по его идентификатору его можно подтянуть, если он всё ещё хранится. Удаление таких слоёв делает восстановление невозможным без повторного пуша.

Рекомендация: использовать -m только если вы уверены, что никто в организации не полагается на доступ к старым слоям по content-addressable ID, а все потребители работают с тегами.

Запуск сборки мусора по расписанию

Политики очистки выполняются автоматически по указанной частоте. Сбор мусора по умолчанию не настроен автоматически, поэтому стоит добавить задание в crontab для регулярного запуска.

Создайте файл /etc/cron.d/registry-garbage-collection со следующим содержимым, чтобы запускать сбор мусора каждую неделю в понедельник в 02:00:

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
0 2 * * 1 root gitlab-ctl registry-garbage-collect

Локализация времени: 02:00 — удобный период, когда активность пользователей минимальна. Если у вас глобальная команда, подберите окно с минимальной нагрузкой для всех ключевых регионов.

Важно: если вы используете флаг -m, подумайте о запуске его реже (например, раз в месяц) и после уведомления команд, что возможна потеря кэша.

Ограничения сборки мусора

Время выполнения зависит от объёма удаляемых данных. На больших инсталляциях операция может занять длительное время.
Во время выполнения сборки мусора сервис Container Registry должен быть либо остановлен, либо переведён в режим только для чтения. В противном случае возможны конфликтующие операции записи.
Переключение режима требует пересборки конфигурации GitLab: sudo gitlab-ctl reconfigure. Эта команда сама по себе может вызвать кратковременные простои в зависимости от инфраструктуры.

Чтобы перевести Registry в режим только для чтения, отредактируйте /etc/gitlab/gitlab.rb и внесите изменения в блок registry['maintenance'] приблизительно так:

registry['storage'] = {
  'maintenance' => {
    'readonly' => {
      'enabled' => true
    }
  }
}

Затем выполните sudo gitlab-ctl reconfigure, запустите сбор мусора, после чего верните enabled в false и снова выполните reconfigure.

Важно: в больших установках добавление/удаление режима readonly и вызов reconfigure следует тестировать в staging-среде.

Практический план действий (SOP)

Оценка:
- Посмотрите текущее использование места: df, du, или интерфейс GitLab (Admin Area -> Monitoring -> Storage).
- Определите проекты с наибольшим вкладом в Registry.
Подготовка:
- Уведомьте команды о планируемых работах, особенно если планируется режим readonly или полный останов сервиса.
- Подготовьте бэкап конфигурации и метаданных (если применимо).
Настройка политики очистки:
- Настройте политику в UI или примените через API для выбранных проектов.
- Тестируйте на одном проекте: задайте мягкие параметры (например, older_than=30d, keep_n=5).
Тестовый запуск:
- Дождитесь срабатывания политики или вызовите её вручную при частоте один раз в день.
- Проверьте UI: теги исчезли как ожидается.
Сбор мусора:
- Переведите Registry в readonly, если нужно.
- Выполните sudo gitlab-ctl registry-garbage-collect (с флагом -m только после оценки рисков).
- Мониторьте процесс и логи: /var/log/gitlab/registry
Проверка:
- Проверьте использование диска.
- Выполните тестовый pull/push основных образов.
Автоматизация:
- Добавьте cron для регулярного запуска сборки мусора и документируйте политику.
Ретроспектива:
- Оцените эффект, обновите правила хранения и уведомления команд.

Чек-листы по ролям

Чек-лист администратора GitLab:

Оценить текущее использование диска и список больших проектов.
Согласовать окно обслуживания с командами.
Настроить политики очистки в проектах или через API.
Запустить сбор мусора в тестовой среде.
Перевести Registry в readonly перед массовой операцией.
[ ] Выполнить gitlab-ctl reconfigure и нужную команду сборки мусора.
Проверить логи, откатить readonly и перезапустить сервисы при необходимости.

Чек-лист разработчика/владельца проекта:

Проверить, используются ли старые теги в CI/CD конвейерах.
Включить в конвейере сборку артефактов с уникальными тегами, если нужно.
[ ] Убедиться, что критические продовые образы помечены тэгами, которые вы сохраняете (например, stable, production).
Обновить документацию команды о стратегии хранения образов.

Модель принятия решения

Mermaid диаграмма, помогающая решить, запускать ли -m флаг:

graph TD
  A[Оценка потребностей] --> B{Кто использует content-addressable ID?}
  B -- Да --> C[Не использовать -m]
  B -- Нет --> D{Нужна ли максимальная очистка диска?}
  D -- Да --> E[Запустить с -m в контролируемом окне]
  D -- Нет --> C
  C --> F[Обычная сборка мусора]
  E --> F

Матрица рисков и смягчения

Риск	Вероятность	Влияние	Меры смягчения
Потеря кэша слоёв при использовании -m	Средняя	Высокое	Уведомить команды, запускать в non-peak, делать тесты в staging
Простой Registry во время reconfigure	Средняя	Среднее	Тестировать reconfigure в staging, выбрать окно с минимальной активностью
Непреднамеренное удаление важных образов	Низкая	Высокое	Настроить правила `keep tags`, держать резервные образы в другом реестре
Длительная операция GC на больших данных	Высокая	Среднее	Планировать окно, предусмотреть мониторинг и таймауты

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

Теги, отмеченные для удаления, исчезают из UI и не pull-ятся.
Отчёт о сборке мусора не показывает ошибок, влияющих на целостность данных.
Использование диска сократилось в пределах ожидаемого диапазона (какая бы количественная оценка ни была у вас).
CI/CD тесты, зависящие от образов, проходят после операции.

Краткий глоссарий

Container Registry — реестр контейнерных образов, встроенный в GitLab.
Tag / Тег — метка версии образа, используемая при pull/push.
Layer / Слой — часть образа Docker, хранится по content-hash.
Garbage collection — процесс удаления неиспользуемых слоёв.
readonly — режим реестра, при котором запрещены операции записи.

Примеры и шаблоны

Пример API-запроса для массовой настройки проектов (bash-псевдоскрипт):

for project in $(curl -s --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab.example.com/api/v4/projects?membership=true" | jq -r '.[].id'); do
  curl --request PUT \
    --header 'Content-Type: application/json;charset=UTF-8' \
    --header "PRIVATE-TOKEN: $TOKEN" \
    --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":"latest"}}' \
    "https://gitlab.example.com/api/v4/projects/$project"
  echo "Applied policy to project $project"
done

Шаблон уведомления командам (короткий):

Уважаемые коллеги, в ночь с Понедельника на Вторник в 02:00 будет запущена плановая очистка Container Registry. В ходе работ возможны ограничения на push образов. Если ваши пайплайны зависят от нечасто используемых тегов — пометьте их как keep до конца недели.

Итог

Настройка политики очистки и регулярная сборка мусора — простые и эффективные меры для контроля использования диска GitLab Container Registry. Политика удаляет теги и упрощает управление версиями, а garbage collection физически освобождает место. Планируйте операции, уведомляйте команды, тестируйте на staging и автоматизируйте запуск, чтобы минимизировать влияние на рабочие процессы.

Важно: прежде чем включать агрессивные опции, такие как -m, оцените риски для ваших пайплайнов и процессов восстановления.