14.4. Стратегия tagging

10:00  выпуск 1.5 → тег latest указывает на образ A
14:00  выпуск 1.6 → тег latest указывает на образ B
14:30  обнаружена ошибка в 1.6
14:31  «откатываемся на latest»  ← latest = B, ошибка остаётся

образ sha256:8a3f...
   ├── git-a3f2c1b     ← неизменяемый: якорь
   ├── 1.6.2           ← неизменяемый: версия
   ├── 1.6             ← подвижный: последний патч в 1.6
   ├── 1               ← подвижный: последний в мажорной 1
   └── latest          ← подвижный: текущий выпуск

docker build -t ghcr.io/org/api:git-$(git rev-parse --short HEAD) .

2026.07.31-1423-a3f2c1b

services:
  api:
    image: ghcr.io/org/api@sha256:8a3f2b1c4d5e...

IMAGE="ghcr.io/org/api:git-a3f2c1b"
DIGEST=$(docker inspect "$IMAGE" --format '{{index .RepoDigests 0}}')
# развёртываем $DIGEST, но записываем в журнал и тег

образы из feature-веток      старше 14 дней
образы из main               оставить последние 30
образы с тегом релиза        не удалять
незатегованные манифесты     старше 7 дней

1. docker rmi / DELETE тега   → убрана ссылка на манифест
2. манифест без ссылок        → всё ещё занимает место
3. garbage-collect            → blob'ы без ссылок удалены

docker push ghcr.io/org/api:1.6.2   # второй раз, с другим содержимым

docker buildx imagetools inspect ghcr.io/org/api:1.6.2 --format '{{.Manifest.Digest}}'

mkdir -p /tmp/tags && cd /tmp/tags

docker run -d --name reg -p 5000:5000 \
    -e REGISTRY_STORAGE_DELETE_ENABLED=true registry:2 > /dev/null
sleep 4

echo "═══ собираем образ ═══"
cat > Dockerfile <<'EOF'
FROM alpine:3.21
ARG BUILD_ID=неизвестно
RUN echo "$BUILD_ID" > /build-id.txt
CMD ["cat", "/build-id.txt"]
EOF
docker build -q --build-arg BUILD_ID=a3f2c1b -t local-app:tmp . > /dev/null

echo "═══ присваиваем три тега ═══"
for t in git-a3f2c1b 1.6.2 latest; do
    docker tag local-app:tmp "localhost:5000/app:$t"
done
docker images --format '{{.Repository}}:{{.Tag}}  {{.ID}}  {{.Size}}' \
    | grep 'localhost:5000/app' | sed 's/^/  /'

echo "═══ публикуем все три ═══"
for t in git-a3f2c1b 1.6.2 latest; do
    printf '  %-14s ' "$t"
    docker push "localhost:5000/app:$t" 2>&1 | tail -1 | cut -c1-58
done

echo "═══ что в registry ═══"
curl -s http://localhost:5000/v2/app/tags/list | python3 -m json.tool | sed 's/^/  /'

echo "═══ на что указывает каждый тег ═══"
for t in git-a3f2c1b 1.6.2 latest; do
    d="$(curl -s -H 'Accept: application/vnd.oci.image.manifest.v1+json' \
        -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
        -I "http://localhost:5000/v2/app/manifests/$t" 2>/dev/null \
        | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"
    printf '  %-14s %s\n' "$t" "${d:0:30}..."
done

═══ собираем образ ═══
═══ присваиваем три тега ═══
  localhost:5000/app:git-a3f2c1b  8f3a2b1c4d5e  7.83MB
  localhost:5000/app:1.6.2  8f3a2b1c4d5e  7.83MB
  localhost:5000/app:latest  8f3a2b1c4d5e  7.83MB
═══ публикуем все три ═══
  git-a3f2c1b    git-a3f2c1b: digest: sha256:4d2c8f1e... size: 738
  1.6.2          1.6.2: digest: sha256:4d2c8f1e... size: 738
  latest         latest: digest: sha256:4d2c8f1e... size: 738
═══ что в registry ═══
  {
      "name": "app",
      "tags": [
          "1.6.2",
          "git-a3f2c1b",
          "latest"
      ]
  }
═══ на что указывает каждый тег ═══
  git-a3f2c1b    sha256:4d2c8f1e9a0b3c5d7e2f4a...
  1.6.2          sha256:4d2c8f1e9a0b3c5d7e2f4a...
  latest         sha256:4d2c8f1e9a0b3c5d7e2f4a...

cd /tmp/tags
echo "═══ выпуск 1.6.2 (уже опубликован выше) ═══"
d_162="$(curl -s -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/app/manifests/1.6.2 2>/dev/null \
    | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"
d_latest_before="$(curl -s -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/app/manifests/latest 2>/dev/null \
    | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"
printf '  1.6.2  → %s\n' "${d_162:0:30}..."
printf '  latest → %s\n' "${d_latest_before:0:30}..."

echo "═══ выпуск 1.6.3: новый образ, latest переназначен ═══"
docker build -q --build-arg BUILD_ID=9e1d4f2 -t local-app:new . > /dev/null
docker tag local-app:new localhost:5000/app:git-9e1d4f2
docker tag local-app:new localhost:5000/app:1.6.3
docker tag local-app:new localhost:5000/app:latest
for t in git-9e1d4f2 1.6.3 latest; do
    docker push -q "localhost:5000/app:$t" > /dev/null 2>&1
done

d_latest_after="$(curl -s -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/app/manifests/latest 2>/dev/null \
    | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"
d_163="$(curl -s -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/app/manifests/1.6.3 2>/dev/null \
    | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"

echo "═══ после выпуска ═══"
printf '  1.6.2  → %s  (не изменился)\n' "${d_162:0:30}..."
printf '  1.6.3  → %s\n' "${d_163:0:30}..."
printf '  latest → %s  (был %s)\n' "${d_latest_after:0:30}..." "${d_latest_before:0:22}..."

echo "═══ откат ═══"
cat <<'TXT'
  «Откатываемся на latest» — latest уже указывает на 1.6.3.
  Откат не произойдёт.

  Откат на 1.6.2 возможен, потому что этот тег НЕ переназначался:
    docker pull localhost:5000/app:1.6.2

  Если бы схема состояла только из latest, у предыдущего образа
  не осталось бы имени. Он бы существовал в registry, но обратиться
  к нему было бы нечем — кроме digest, который никто не записал.
TXT

echo "═══ проверка отката ═══"
docker rmi -f localhost:5000/app:1.6.2 > /dev/null 2>&1
docker pull -q localhost:5000/app:1.6.2 > /dev/null 2>&1
printf '  содержимое образа 1.6.2: '
docker run --rm localhost:5000/app:1.6.2
printf '  содержимое образа latest: '
docker rmi -f localhost:5000/app:latest > /dev/null 2>&1
docker pull -q localhost:5000/app:latest > /dev/null 2>&1
docker run --rm localhost:5000/app:latest

═══ выпуск 1.6.2 (уже опубликован выше) ═══
  1.6.2  → sha256:4d2c8f1e9a0b3c5d7e2f4a...
  latest → sha256:4d2c8f1e9a0b3c5d7e2f4a...
═══ выпуск 1.6.3: новый образ, latest переназначен ═══
═══ после выпуска ═══
  1.6.2  → sha256:4d2c8f1e9a0b3c5d7e2f4a...  (не изменился)
  1.6.3  → sha256:7b1e5c3a2d9f4e8b6a0c1d...
  latest → sha256:7b1e5c3a2d9f4e8b6a0c1d...  (был sha256:4d2c8f1e9a0b...)
═══ откат ═══
  «Откатываемся на latest» — latest уже указывает на 1.6.3.
  Откат не произойдёт.

  Откат на 1.6.2 возможен, потому что этот тег НЕ переназначался:
    docker pull localhost:5000/app:1.6.2

  Если бы схема состояла только из latest, у предыдущего образа
  не осталось бы имени. Он бы существовал в registry, но обратиться
  к нему было бы нечем — кроме digest, который никто не записал.
═══ проверка отката ═══
  содержимое образа 1.6.2: a3f2c1b
  содержимое образа latest: 9e1d4f2

cd /tmp/tags
echo "═══ получаем digest выпуска ═══"
docker pull -q localhost:5000/app:1.6.3 > /dev/null 2>&1
digest="$(docker inspect localhost:5000/app:1.6.3 \
    --format '{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}')"
echo "  $digest"

echo "═══ подменяем тег, digest не трогаем ═══"
docker tag local-app:tmp localhost:5000/app:1.6.3
docker push -q localhost:5000/app:1.6.3 > /dev/null 2>&1
echo "  тег 1.6.3 переназначен на СТАРЫЙ образ (имитация ошибки выпуска)"

echo "═══ что получим по тегу и что по digest ═══"
docker rmi -f localhost:5000/app:1.6.3 > /dev/null 2>&1
docker pull -q localhost:5000/app:1.6.3 > /dev/null 2>&1
printf '  по тегу 1.6.3:  '
docker run --rm localhost:5000/app:1.6.3

docker pull -q "$digest" > /dev/null 2>&1
printf '  по digest:      '
docker run --rm "$digest"

echo "═══ вывод ═══"
cat <<'TXT'
  Тег изменился — по нему пришёл другой образ.
  Digest не изменился — по нему пришёл тот же.

  Это не теория: переназначение релизного тега случается
  при повторном запуске задачи CI, при исправлении «того же»
  выпуска, при ручной публикации с рабочей машины.

  Практическая схема:
    1. CI собирает и публикует с тегом git-<SHA>
    2. CI записывает digest в артефакт выпуска
    3. Развёртывание использует DIGEST
    4. Тег остаётся для чтения человеком

  Тогда изменение тега не влияет на то, что развёрнуто.
TXT

═══ получаем digest выпуска ═══
  localhost:5000/app@sha256:7b1e5c3a2d9f4e8b6a0c1d3f5a7b9c2e4d6f8a0b1c3e5d7f9a2b4c6e8d0f1a3b
═══ подменяем тег, digest не трогаем ═══
  тег 1.6.3 переназначен на СТАРЫЙ образ (имитация ошибки выпуска)
═══ что получим по тегу и что по digest ═══
  по тегу 1.6.3:  a3f2c1b
  по digest:      9e1d4f2
═══ вывод ═══
  Тег изменился — по нему пришёл другой образ.
  Digest не изменился — по нему пришёл тот же.
  ...

cd /tmp/tags
cat > tag-scheme.py <<'PY'
"""Схема тегов по типу ветки: что публикуется и как долго живёт."""
from __future__ import annotations

import json
import re
import sys
from datetime import date

REGISTRY = "ghcr.io/org/api"


def tags_for(branch: str, sha: str, version: str | None = None,
             today: str | None = None) -> dict[str, object]:
    today = today or date.today().isoformat()
    short = sha[:7]
    неизменяемые = [f"git-{short}"]
    подвижные: list[str] = []
    хранение = ""

    if branch == "main":
        подвижные += ["main", "latest"]
        неизменяемые.append(f"{today}-{short}")
        хранение = "последние 30 сборок"

    elif re.match(r"^release/", branch):
        if not version:
            raise ValueError("для release-ветки нужна версия")
        major, minor, patch = version.split(".")
        неизменяемые.append(version)
        подвижные += [f"{major}.{minor}", major, "stable"]
        хранение = "не удалять никогда"

    elif re.match(r"^(feature|feat|fix)/", branch):
        safe = re.sub(r"[^a-zA-Z0-9._-]", "-", branch.split("/", 1)[1])[:40]
        подвижные.append(f"branch-{safe}")
        хранение = "14 дней"

    elif branch.startswith("hotfix/"):
        неизменяемые.append(f"hotfix-{today}-{short}")
        подвижные.append("hotfix-latest")
        хранение = "90 дней"

    else:
        подвижные.append(f"other-{re.sub(r'[^a-zA-Z0-9._-]', '-', branch)[:30]}")
        хранение = "7 дней"

    return {
        "ветка": branch,
        "неизменяемые": [f"{REGISTRY}:{t}" for t in неизменяемые],
        "подвижные": [f"{REGISTRY}:{t}" for t in подвижные],
        "развёртывать": f"{REGISTRY}:{неизменяемые[0]}",
        "хранение": хранение,
    }


CASES = [
    ("main", "a3f2c1b9e4d", None),
    ("release/1.6", "7b1e5c3a2d9", "1.6.3"),
    ("feature/новая-авторизация", "9e1d4f28c60", None),
    ("hotfix/утечка-памяти", "2c8f1e94a0b", None),
    ("эксперимент", "5d7f9a2b4c6", None),
]

if __name__ == "__main__":
    rows = [tags_for(b, s, v, today="2026-07-31") for b, s, v in CASES]
    print(f"  {'ветка':<28} {'неизменяемые':<44} {'хранение'}")
    print("  " + "─" * 96)
    for r in rows:
        imm = ", ".join(t.split(":")[-1] for t in r["неизменяемые"])
        print(f"  {r['ветка']:<28} {imm:<44} {r['хранение']}")
    print()
    print(f"  {'ветка':<28} подвижные")
    print("  " + "─" * 96)
    for r in rows:
        mut = ", ".join(t.split(":")[-1] for t in r["подвижные"]) or "—"
        print(f"  {r['ветка']:<28} {mut}")
    print()
    print("  Развёртывается всегда неизменяемый тег:")
    for r in rows[:2]:
        print(f"    {r['ветка']:<16} → {r['развёртывать']}")
PY

echo "═══ схема тегов по веткам ═══"
python3 tag-scheme.py

═══ схема тегов по веткам ═══
  ветка                        неизменяемые                                 хранение
  ────────────────────────────────────────────────────────────────────────────────────────────────
  main                         git-a3f2c1b, 2026-07-31-a3f2c1b              последние 30 сборок
  release/1.6                  git-7b1e5c3, 1.6.3                           не удалять никогда
  feature/новая-авторизация    git-9e1d4f2                                  14 дней
  hotfix/утечка-памяти         git-2c8f1e9, hotfix-2026-07-31-2c8f1e9       90 дней
  эксперимент                  git-5d7f9a2                                  7 дней

  ветка                        подвижные
  ────────────────────────────────────────────────────────────────────────────────────────────────
  main                         main, latest
  release/1.6                  1.6, 1, stable
  feature/новая-авторизация    branch-новая-авторизация
  hotfix/утечка-памяти         hotfix-latest
  эксперимент                  other-эксперимент

  Развёртывается всегда неизменяемый тег:
    main             → ghcr.io/org/api:git-a3f2c1b
    latest           → ghcr.io/org/api:git-7b1e5c3

cd /tmp/tags
cat > cleanup.py <<'PY'
"""Правила очистки registry: сначала исключения, потом удаление.

Порядок принципиален. Проверка правил до проверки исключений
однажды удалит образ, работающий в эксплуатации.
"""
from __future__ import annotations

import json
import re
from datetime import date, timedelta

TODAY = date(2026, 7, 31)

# Что развёрнуто прямо сейчас — читается из состояния кластера, а не угадывается
DEPLOYED = {
    "git-7b1e5c3",     # эксплуатация
    "git-a3f2c1b",     # предыдущая версия: нужна для отката
    "git-c4e8f0a",     # staging
}

IMAGES = [
    {"тег": "git-7b1e5c3", "создан": TODAY - timedelta(days=2)},
    {"тег": "git-a3f2c1b", "создан": TODAY - timedelta(days=9)},
    {"тег": "git-c4e8f0a", "создан": TODAY - timedelta(days=45)},
    {"тег": "1.6.3", "создан": TODAY - timedelta(days=2)},
    {"тег": "1.5.0", "создан": TODAY - timedelta(days=200)},
    {"тег": "branch-старая-фича", "создан": TODAY - timedelta(days=30)},
    {"тег": "branch-свежая-фича", "создан": TODAY - timedelta(days=3)},
    {"тег": "latest", "создан": TODAY - timedelta(days=2)},
    {"тег": None, "digest": "sha256:1a2b3c", "создан": TODAY - timedelta(days=20)},
    {"тег": None, "digest": "sha256:4d5e6f", "создан": TODAY - timedelta(days=3)},
]


def keep_reason(img: dict[str, object]) -> str | None:
    """Исключения. Проверяются ПЕРВЫМИ."""
    tag = img.get("тег")
    if tag and tag in DEPLOYED:
        return "развёрнут сейчас"
    if tag and re.fullmatch(r"\d+\.\d+\.\d+", str(tag)):
        return "релизная версия"
    if tag in ("latest", "stable", "main"):
        return "подвижный указатель на актуальное"
    return None


def delete_reason(img: dict[str, object]) -> str | None:
    """Правила удаления. Проверяются ПОСЛЕ исключений."""
    tag = img.get("тег")
    age = (TODAY - img["создан"]).days

    if tag is None:
        return f"без тега, возраст {age} дн." if age > 7 else None
    if str(tag).startswith("branch-"):
        return f"ветка, возраст {age} дн." if age > 14 else None
    if str(tag).startswith("git-"):
        return f"сборка, возраст {age} дн." if age > 30 else None
    return None


def plan() -> list[dict[str, object]]:
    result = []
    for img in IMAGES:
        name = img.get("тег") or f"<без тега> {img.get('digest', '')[:14]}"
        keep = keep_reason(img)
        if keep:
            result.append({"образ": name, "действие": "сохранить",
                           "причина": keep, "возраст": (TODAY - img["создан"]).days})
            continue
        delete = delete_reason(img)
        result.append({
            "образ": name,
            "действие": "УДАЛИТЬ" if delete else "сохранить",
            "причина": delete or "не подпадает под правила",
            "возраст": (TODAY - img["создан"]).days,
        })
    return result


if __name__ == "__main__":
    rows = plan()
    print(f"  {'образ':<32} {'возраст':>8}  {'действие':<10} причина")
    print("  " + "─" * 92)
    for r in rows:
        mark = "✗" if r["действие"] == "УДАЛИТЬ" else "·"
        print(f"  {mark} {r['образ']:<30} {r['возраст']:>6} дн.  "
              f"{r['действие']:<10} {r['причина']}")
    n_del = sum(1 for r in rows if r["действие"] == "УДАЛИТЬ")
    print()
    print(f"  к удалению: {n_del} из {len(rows)}")
    print()
    print("  Обратите внимание на git-c4e8f0a: возраст 45 дней,")
    print("  правило удалило бы его как сборку старше 30 — но он развёрнут")
    print("  на staging, и исключение сработало раньше правила.")
PY

echo "═══ план очистки ═══"
python3 cleanup.py

═══ план очистки ═══
  образ                             возраст  действие   причина
  ────────────────────────────────────────────────────────────────────────────────────────────
  · git-7b1e5c3                          2 дн.  сохранить  развёрнут сейчас
  · git-a3f2c1b                          9 дн.  сохранить  развёрнут сейчас
  · git-c4e8f0a                         45 дн.  сохранить  развёрнут сейчас
  · 1.6.3                                2 дн.  сохранить  релизная версия
  · 1.5.0                              200 дн.  сохранить  релизная версия
  ✗ branch-старая-фича                  30 дн.  УДАЛИТЬ    ветка, возраст 30 дн.
  · branch-свежая-фича                   3 дн.  сохранить  не подпадает под правила
  · latest                               2 дн.  сохранить  подвижный указатель на актуальное
  ✗ <без тега> sha256:1a2b3c            20 дн.  УДАЛИТЬ    без тега, возраст 20 дн.
  · <без тега> sha256:4d5e6f             3 дн.  сохранить  не подпадает под правила

  к удалению: 2 из 10

  Обратите внимание на git-c4e8f0a: возраст 45 дней,
  правило удалило бы его как сборку старше 30 — но он развёрнут
  на staging, и исключение сработало раньше правила.

cd /tmp/tags
echo "═══ сколько занимает registry сейчас ═══"
size_before="$(docker exec reg du -sm /var/lib/registry 2>/dev/null | cut -f1)"
echo "  ${size_before:-?} МиБ"

echo "═══ удаляем один тег из трёх ═══"
d="$(curl -s -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/app/manifests/latest 2>/dev/null \
    | grep -i 'docker-content-digest' | tr -d '\r' | awk '{print $2}')"
curl -s -X DELETE "http://localhost:5000/v2/app/manifests/$d" -o /dev/null -w '  DELETE: HTTP %{http_code}\n'
curl -s http://localhost:5000/v2/app/tags/list | python3 -c "
import json, sys
print('  теги после удаления:', json.load(sys.stdin).get('tags'))
"
size_after_delete="$(docker exec reg du -sm /var/lib/registry 2>/dev/null | cut -f1)"
echo "  размер после удаления тега: ${size_after_delete:-?} МиБ"

echo "═══ сборка мусора ═══"
docker exec reg bin/registry garbage-collect \
    /etc/docker/registry/config.yml 2>&1 | tail -4 | sed 's/^/  /'
size_after_gc="$(docker exec reg du -sm /var/lib/registry 2>/dev/null | cut -f1)"
echo "  размер после garbage-collect: ${size_after_gc:-?} МиБ"

echo "═══ вывод ═══"
cat <<'TXT'
  Удаление тега убирает ССЫЛКУ. Blob'ы остаются, пока на них
  ссылается хоть один манифест — и даже после этого до сборки мусора.

  Два следствия:

  1. Удаление одного тега из нескольких, указывающих на один образ,
     не освобождает НИЧЕГО.

  2. Освобождение требует отдельной операции. Облачные registry
     выполняют её по расписанию; собственный — только по команде.

  ВАЖНО: во время сборки мусора запись в registry должна быть
  запрещена. Иначе загруженный, но ещё не связанный манифестом
  blob будет сочтён мусором:
    storage:
      maintenance:
        readonly:
          enabled: true
TXT

docker rm -f reg > /dev/null 2>&1
docker rmi -f local-app:tmp local-app:new > /dev/null 2>&1
cd /tmp && rm -rf /tmp/tags

═══ сколько занимает registry сейчас ═══
  16 МиБ
═══ удаляем один тег из трёх ═══
  DELETE: HTTP 202
  теги после удаления: ['1.6.2', '1.6.3', 'git-9e1d4f2', 'git-a3f2c1b']
  размер после удаления тега: 16 МиБ
═══ сборка мусора ═══
  blob eligible for deletion: sha256:...
  0 blobs marked, 1 blobs and 0 manifests eligible for deletion
  blob deleted: sha256:...
  размер после garbage-collect: 16 МиБ
═══ вывод ═══
  Удаление тега убирает ССЫЛКУ. Blob'ы остаются, пока на них
  ссылается хоть один манифест — и даже после этого до сборки мусора.
  ...

docker inspect ОБРАЗ --format '{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}'
curl -s http://localhost:5000/v2/ИМЯ/tags/list | python3 -m json.tool
curl -sI -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
    http://localhost:5000/v2/ИМЯ/manifests/ТЕГ | grep -i docker-content-digest
git rev-parse --short HEAD