docs(wiki): dangling image-index finding — registry full of tag-tombstones

Перепрогон registryGc dryRun на descent-фиксе (master-dcd7c91) вскрыл 2-й
root-cause: реестр засорён dangling OCI image-индексами — тег жив, но его
платформенный sub-manifest отдаёт MANIFEST_UNKNOWN (вычищен прежним host-side
registry garbage-collect, не следящим index->child для multi-arch).
books-web: 19 тегов -> 3 датируемых, 16 dangling.

date-based GC защищает dangling как null-dated -> никогда не удаляет, хотя они
и есть мусор (логика задом наперёд). Рекомендация books: различать
transient-error (protect) vs MANIFEST_UNKNOWN (eligible for delete).
freedBytes от dangling ~0 (слои уже вычищены).

+registry-oci-image-index-gc.md (раздел) +index.md +log.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-18 12:51:28 +03:00
parent 85b13ae6a4
commit 93b4ef1d13
3 changed files with 20 additions and 1 deletions

View File

@@ -35,6 +35,23 @@ index → .manifests[] где platform.os/arch != "unknown" → <sub>.config.dig
Зафиксировано на books `registryGc` dryRun 2026-06-18 (`packages/task-runner/lib/registryV2.js`: `getCreated`→null, `planDeletions` ставит `protected` любой null-dated группе). Auth при этом исправен (books-ci, 401 нет) — баг чисто в обходе manifest-дерева, не в доступе.
## Dangling image-индексы — реестр уже засорён ими (2026-06-18)
Бóльшая часть тегов books-* — **dangling index**: тег указывает на живой OCI image-index, но его платформенный sub-manifest при фетче отдаёт `MANIFEST_UNKNOWN`:
```json
{ "errors":[{"code":"MANIFEST_UNKNOWN","message":"manifest unknown",
"detail":{"Name":"books-web","Revision":"sha256:8d2b447a…"}}] }
```
Sub-manifest (и его слои) физически удалены, а **тегированный родитель-index остался**. Замер books-web 2026-06-18: **19 не-buildcache тегов → 3 датируемых (живых), 16 dangling**.
**Происхождение:** классическое последствие host-side `registry garbage-collect`, который для multi-arch НЕ следует ссылкам index→child → удаляет детей-манифесты и блобы, оставляя тег-надгробие на верхнем index'е. (См. [`registry-gc-mount-and-modify-flag`](registry-gc-mount-and-modify-flag.md).)
**Ловушка для date-based GC:** `getCreated` на dangling вернёт `null` (sub недоступен) → планировщик защитит группу как «недатированную» → dangling **никогда не удаляется**, хотя это лучший кандидат на чистку. Логика задом наперёд, если не различать:
- **transient resolve error** (5xx/таймаут) → protect, safe;
- **`MANIFEST_UNKNOWN` на sub** (dangling) → **eligible for delete** (не protect); даты нет — в хвост сортировки или дроп безусловно, образ уже сломан (`docker pull` по нему падает).
**freedBytes-нюанс:** удаление dangling-индекса освобождает ~0 байт (слои уже вычищены прежним GC) — это гигиена tag-list + удаление битых pull-целей, не disk-reclaim. Реальное место по keepLastN экономится только на живых датируемых образах.
## Правила для любого GC/cleanup над этим реестром
1. **Accept на manifest-fetch** обязан включать и index, и manifest-list, и oci.image.manifest, и docker.manifest.v2 — иначе registry отдаёт не тот тип / 404 (та же media-type-гоча, что для HEAD тега в [`registry-kzntsv-auth-model`](registry-kzntsv-auth-model.md)).