116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
---
|
||
title: Docker Registry garbage-collect mount layout + `-m` flag
|
||
type: concept
|
||
tags: [docker-registry, garbage-collect, gotcha, storage]
|
||
sources: [../sources/vds-kzntsv-bootstrap-2026-05-20.md]
|
||
updated: 2026-05-20
|
||
---
|
||
|
||
# Registry GC — mount path и `-m` flag
|
||
|
||
Распознаваемая пара ошибок при `registry garbage-collect` на offline-restored backup data. Один shoot — `-m` flag для реального удаления, второй — правильный mount path.
|
||
|
||
## Симптом 1 — `Path not found: /docker/registry/v2/repositories`
|
||
|
||
Запуск:
|
||
```bash
|
||
docker run --rm \
|
||
-v /volume1/docker/infrastucture/registry/docker:/var/lib/registry \
|
||
registry:2.8.3 garbage-collect /etc/docker/registry/config.yml
|
||
```
|
||
|
||
Ошибка: `failed to garbage collect: failed to mark: filesystem: Path not found: /docker/registry/v2/repositories`.
|
||
|
||
### Root cause
|
||
|
||
Default config файл `/etc/docker/registry/config.yml` в registry image имеет:
|
||
```yaml
|
||
storage:
|
||
filesystem:
|
||
rootdirectory: /var/lib/registry
|
||
```
|
||
|
||
Registry expect'ит файлы в `/var/lib/registry/docker/registry/v2/...`. Mounting только `docker/` subdir host'а к `/var/lib/registry/` положит данные в `/var/lib/registry/registry/v2/...` (один уровень потерян).
|
||
|
||
### Fix — mount PARENT directory
|
||
|
||
```bash
|
||
docker run --rm \
|
||
-v /volume1/docker/infrastucture/registry:/var/lib/registry \ # <-- parent dir, не /docker
|
||
registry:2.8.3 garbage-collect /etc/docker/registry/config.yml
|
||
```
|
||
|
||
Теперь internal path = `/var/lib/registry/docker/registry/v2/...` ✅.
|
||
|
||
(Original kreknin compose использовал `./:/var/lib/registry` — mount whole registry parent dir — что было корректно но для running registry, не для offline GC.)
|
||
|
||
## Симптом 2 — GC ничего не удаляет, размер прежний
|
||
|
||
После первого GC прохода видим лог:
|
||
```
|
||
blob eligible for deletion: sha256:087b41...
|
||
time="..." level=info msg="Deleting blob: /docker/registry/v2/blobs/sha256/08/087b41..."
|
||
```
|
||
|
||
Лог говорит «Deleting» — но `du -sh` показывает **прежний 99G**. Размер не изменился.
|
||
|
||
### Root cause
|
||
|
||
`registry garbage-collect` без флагов работает в **dry-run mode** (incident-free). Лог «Deleting blob» — `info` level намерения, не actual unlink.
|
||
|
||
Подобный intent vs action разделение типично для batch tools (`apt-get -s`, `git rm --dry-run`, etc.) но в registry CLI нет attention-grabbing `--dry-run` flag — а опция «реально делать» named cryptically.
|
||
|
||
### Fix — `-m` (modify) flag
|
||
|
||
```bash
|
||
docker run --rm \
|
||
-v /volume1/docker/infrastucture/registry:/var/lib/registry \
|
||
registry:2.8.3 garbage-collect -m /etc/docker/registry/config.yml
|
||
```
|
||
|
||
С `-m` после прохода размер реально уменьшается. На kreknin backup'е: **99G → 35G** (64G freed), 2-3 минуты обработки.
|
||
|
||
## Полный рецепт offline GC restored backup data
|
||
|
||
```bash
|
||
# 1. Pull registry image что соответствует production версии (compatibility)
|
||
docker pull registry:2.8.3
|
||
|
||
# 2. (Optional) dry-run для отчёта — что будет удалено
|
||
docker run --rm \
|
||
-v /path/to/restored/registry:/var/lib/registry \
|
||
registry:2.8.3 garbage-collect /etc/docker/registry/config.yml \
|
||
> gc-dry-run.log 2>&1
|
||
|
||
# 3. Реальный GC
|
||
docker run --rm \
|
||
-v /path/to/restored/registry:/var/lib/registry \
|
||
registry:2.8.3 garbage-collect -m /etc/docker/registry/config.yml
|
||
|
||
# 4. Measure delta
|
||
du -sh /path/to/restored/registry/docker
|
||
```
|
||
|
||
## Online GC (production live registry) — важные дополнения
|
||
|
||
Если делаем GC на **running** registry — нужен read-only mode чтобы избежать race condition'ов (новый push во время GC может потерять blobs):
|
||
|
||
```yaml
|
||
# Add to running registry config / env vars
|
||
storage:
|
||
maintenance:
|
||
readonly:
|
||
enabled: true
|
||
```
|
||
|
||
Затем restart registry, run GC `-m`, отключить read-only, restart again. Окно downtime — продолжительность GC (~10-30 min на средних объёмах).
|
||
|
||
## Где применено
|
||
|
||
[`vds-kzntsv`](../entities/vds-kzntsv.md) Phase 3.3 — GC kreknin'овского backup'а 99G → 35G. После того как user decided abandon миграцию и fresh install — GC оказался полезной экономией если бы tar/rsync'или (но в финале rsync не запустился).
|
||
|
||
## Ссылки
|
||
|
||
- Registry docs: [Garbage collection](https://distribution.github.io/distribution/about/garbage-collection/)
|
||
- Сессия: [`vds-kzntsv-bootstrap-2026-05-20`](../sources/vds-kzntsv-bootstrap-2026-05-20.md) Phase 3.3.
|