14.1. Основы registry

mkdir -p /tmp/reglab && cd /tmp/reglab

# ─── Разбор ссылок ────────────────────────────────────────────────────
cat > refparse.py <<'PY'
"""Разбор ссылки на образ с указанием подстановок по умолчанию.

Правило различения registry и namespace: первая часть считается
registry, если содержит точку, двоеточие или равна localhost.
Иначе это namespace на Docker Hub.
"""
from __future__ import annotations

import json
import sys

DEFAULT_REGISTRY = "docker.io"
DEFAULT_NAMESPACE = "library"
DEFAULT_TAG = "latest"


def looks_like_registry(part: str) -> bool:
    return "." in part or ":" in part or part == "localhost"


def parse(ref: str) -> dict[str, object]:
    original = ref
    digest = None
    if "@" in ref:
        ref, digest = ref.split("@", 1)

    parts = ref.split("/")
    defaults: list[str] = []

    if looks_like_registry(parts[0]):
        registry, rest = parts[0], parts[1:]
    else:
        registry, rest = DEFAULT_REGISTRY, parts
        defaults.append(f"registry={DEFAULT_REGISTRY}")

    if not rest:
        raise ValueError(f"нет имени репозитория: {original}")

    repo = rest[-1]
    tag = None
    if ":" in repo:
        repo, tag = repo.rsplit(":", 1)
    if tag is None and digest is None:
        tag, _ = DEFAULT_TAG, defaults.append(f"тег={DEFAULT_TAG}")

    namespace = "/".join(rest[:-1])
    if not namespace:
        if registry == DEFAULT_REGISTRY:
            namespace = DEFAULT_NAMESPACE
            defaults.append(f"namespace={DEFAULT_NAMESPACE} → официальный образ")
        else:
            namespace = ""

    # Полное имя собирается из РАЗОБРАННЫХ частей, а не дополнением исходной
    segments = [registry] + ([namespace] if namespace else []) + [repo]
    full = "/".join(segments)
    if tag:
        full += f":{tag}"
    if digest:
        full += f"@{digest}"

    return {
        "ссылка": original,
        "registry": registry,
        "namespace": namespace or "(нет)",
        "repository": repo,
        "тег": tag,
        "digest": digest,
        "подставлено": defaults,
        "полное_имя": full,
        "официальный": registry == DEFAULT_REGISTRY and namespace == DEFAULT_NAMESPACE,
    }


if __name__ == "__main__":
    print(json.dumps([parse(r) for r in sys.argv[1:]],
                     ensure_ascii=False, indent=2))
PY

# ─── Измерение публикации ─────────────────────────────────────────────
cat > measure-push.sh <<'SH'
#!/usr/bin/env bash
# Считает, сколько слоёв передано и сколько пропущено при публикации.
set -uo pipefail

REF="${1:?укажите образ}"
out="$(docker push "$REF" 2>&1)"

pushed="$(echo "$out" | grep -c ': Pushed' || echo 0)"
exists="$(echo "$out" | grep -c ': Layer already exists' || echo 0)"
digest="$(echo "$out" | grep -o 'digest: sha256:[0-9a-f]*' | head -1 | cut -d' ' -f2)"
total=$((pushed + exists))

printf '%s|%s|%s|%s\n' "$pushed" "$exists" "$total" "${digest:-нет}"
SH
chmod +x measure-push.sh

fail=0
ok()  { printf '  ✓ %s\n' "$1"; }
bad() { printf '  ✗ %s\n' "$1"; fail=1; }

printf '\n═══ Требование 1: разбор пяти ссылок ═══\n'
python3 refparse.py \
    "python" "python:3.13-slim" "myorg/api:1.2" \
    "ghcr.io/myorg/api:1.2" "localhost:5000/svc@sha256:abc123" \
    | python3 -c "
import json, sys
rows = json.load(sys.stdin)
print(f\"    {'ссылка':<34} {'полное имя':<44} офиц.\")
print('    ' + '─' * 88)
for r in rows:
    print(f\"    {r['ссылка']:<34} {r['полное_имя']:<44} {'да' if r['официальный'] else 'нет'}\")
print()
for r in rows:
    if r['подставлено']:
        print(f\"    {r['ссылка']}: {', '.join(r['подставлено'])}\")
"
official_count="$(python3 refparse.py python python:3.13-slim myorg/api:1.2 \
    ghcr.io/myorg/api:1.2 "localhost:5000/svc@sha256:abc123" \
    | python3 -c "import json,sys; print(sum(1 for r in json.load(sys.stdin) if r['официальный']))")"
ghcr_full="$(python3 refparse.py "ghcr.io/myorg/api:1.2" \
    | python3 -c "import json,sys; print(json.load(sys.stdin)[0]['полное_имя'])")"
printf '    официальных образов: %s\n' "$official_count"
printf '    ghcr.io собран как: %s\n' "$ghcr_full"
[ "$official_count" -eq 2 ] && [ "$ghcr_full" = "ghcr.io/myorg/api:1.2" ] \
    && ok "подстановки определены верно, registry не задвоен" \
    || bad "официальных=$official_count, ghcr=$ghcr_full"

printf '\n═══ Подготовка: локальный registry ═══\n'
docker run -d --name lab-reg -p 5000:5000 -v lab-reg-data:/var/lib/registry \
    registry:2 > /dev/null 2>&1
sleep 4
code="$(curl -s -o /dev/null -w '%{http_code}' http://localhost:5000/v2/ 2>/dev/null)"
printf '    registry отвечает: HTTP %s\n' "$code"
[ "$code" = "200" ] || { echo "    registry не поднялся"; exit 1; }

cat > Dockerfile.base <<'EOF'
FROM python:3.13-slim
RUN pip install --no-cache-dir click==8.3.0
ARG VARIANT=a
RUN echo "вариант ${VARIANT}" > /variant.txt
EOF

docker build -q -f Dockerfile.base --build-arg VARIANT=a -t localhost:5000/app:a . > /dev/null
docker build -q -f Dockerfile.base --build-arg VARIANT=b -t localhost:5000/app:b . > /dev/null
printf '    два образа собраны\n'

printf '\n═══ Требование 2: повторная публикация общих слоёв ═══\n'
r_a="$(./measure-push.sh localhost:5000/app:a)"
r_b="$(./measure-push.sh localhost:5000/app:b)"
IFS='|' read -r pa ea ta da <<EOF
$r_a
EOF
IFS='|' read -r pb eb tb db <<EOF
$r_b
EOF
printf '    %-28s %-9s %-12s %s\n' "публикация" "передано" "пропущено" "всего слоёв"
printf '    %s\n' "──────────────────────────────────────────────────────────────"
printf '    %-28s %-9s %-12s %s\n' "app:a (первая)" "$pa" "$ea" "$ta"
printf '    %-28s %-9s %-12s %s\n' "app:b (общая база)" "$pb" "$eb" "$tb"
printf '    экономия на второй: %s из %s слоёв не передавались\n' "$eb" "$tb"
[ "${eb:-0}" -gt 0 ] && [ "${pb:-0}" -lt "${pa:-99}" ] \
    && ok "общие слои пропущены: проверка HEAD вернула 200" \
    || bad "передано=$pb пропущено=$eb"

printf '\n═══ Требование 3: другой репозиторий ═══\n'
docker tag localhost:5000/app:a localhost:5000/second/app:a
r_c="$(./measure-push.sh localhost:5000/second/app:a)"
IFS='|' read -r pc ec tc dc <<EOF
$r_c
EOF
printf '    %-28s %-9s %-12s %s\n' "second/app:a (тот же образ)" "$pc" "$ec" "$tc"
printf '    digest app:a          %s\n' "${da:0:30}..."
printf '    digest second/app:a   %s\n' "${dc:0:30}..."
if [ "$da" = "$dc" ]; then
    printf '    digest СОВПАДАЕТ — образ тот же\n'
    same_digest=1
else
    printf '    digest различается\n'
    same_digest=0
fi
[ "${pc:-0}" -ge "${pa:-0}" ] && [ "$same_digest" = "1" ] \
    && ok "тот же образ передан заново: дедупликация в пределах репозитория" \
    || bad "передано=$pc (в первый раз $pa), digest совпал=$same_digest"

printf '\n═══ Требование 4: три digest ═══\n'
docker pull -q python:3.13-slim > /dev/null 2>&1
cfg="$(docker inspect python:3.13-slim --format '{{.Id}}')"
repo="$(docker inspect python:3.13-slim --format '{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}')"
printf '    %-22s %s\n' "config digest (Id)" "${cfg:0:40}..."
printf '    %-22s %s\n' "RepoDigest" "${repo:0:56}..."
plat="$(docker manifest inspect python:3.13-slim 2>/dev/null | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
except Exception:
    print(''); raise SystemExit
ms = [m for m in d.get('manifests', [])
      if m.get('platform', {}).get('architecture') not in (None, 'unknown')]
if ms:
    print(f\"манифестов платформ: {len(ms)}; первый: {ms[0]['digest'][:30]}...\")
else:
    print('одиночный манифест')
" 2>/dev/null)"
printf '    %-22s %s\n' "manifest digest" "${plat:-недоступен без сети}"
printf '\n    назначение каждого:\n'
printf '      Id          локальный идентификатор конфигурации; в pull не передаётся\n'
printf '      RepoDigest  существует в registry; им закрепляют версию в FROM\n'
printf '      manifest    конкретная платформа; выбирается при pull автоматически\n'
[ -n "$cfg" ] && [ -n "$repo" ] && [ "$cfg" != "$repo" ] \
    && ok "три значения различны; для закрепления пригоден RepoDigest" \
    || bad "Id=$cfg RepoDigest=$repo"

printf '\n═══ Требование 5: целостность ═══\n'
id_before="$(docker inspect localhost:5000/app:a --format '{{.Id}}')"
printf '    Id до удаления:  %s\n' "${id_before:0:40}..."
docker rmi -f localhost:5000/app:a localhost:5000/second/app:a > /dev/null 2>&1
docker pull -q localhost:5000/app:a > /dev/null 2>&1
id_after="$(docker inspect localhost:5000/app:a --format '{{.Id}}')"
printf '    Id после pull:   %s\n' "${id_after:0:40}..."
[ "$id_before" = "$id_after" ] \
    && ok "получен тот же образ; проверка sha256 встроена в адресацию" \
    || bad "Id различается: было $id_before, стало $id_after"

printf '\n═══ Требование 6: проверка подстановок ═══\n'
cat > check-ref.sh <<'SH'
#!/usr/bin/env bash
# Предупреждает о ссылках, полагающихся на подстановки по умолчанию.
set -uo pipefail
issues=0
for ref in "$@"; do
    info="$(python3 refparse.py "$ref")"
    n_def="$(echo "$info" | python3 -c "import json,sys; print(len(json.load(sys.stdin)[0]['подставлено']))")"
    full="$(echo "$info" | python3 -c "import json,sys; print(json.load(sys.stdin)[0]['полное_имя'])")"
    tag="$(echo "$info" | python3 -c "import json,sys; print(json.load(sys.stdin)[0]['тег'] or '')")"
    dig="$(echo "$info" | python3 -c "import json,sys; print(json.load(sys.stdin)[0]['digest'] or '')")"

    printf '  %-34s → %s\n' "$ref" "$full"
    if [ "$tag" = "latest" ] && [ -z "$dig" ]; then
        printf '      ⚠ тег latest подставлен: образ не закреплён\n'
        issues=$((issues + 1))
    fi
    if [ -z "$dig" ] && [ "$n_def" -gt 0 ]; then
        printf '      · подстановок по умолчанию: %s\n' "$n_def"
    fi
    [ -n "$dig" ] && printf '      ✓ закреплён по digest\n'
done
printf '\n  ссылок, требующих внимания: %s\n' "$issues"
[ "$issues" -gt 0 ] && exit 1
exit 0
SH
chmod +x check-ref.sh

./check-ref.sh "python" "python:3.13-slim" "ghcr.io/org/api@sha256:abc123"; rc_warn=$?
printf '    код возврата при неявных ссылках: %s\n' "$rc_warn"
./check-ref.sh "ghcr.io/org/api@sha256:abc123" > /dev/null 2>&1; rc_clean=$?
printf '    код возврата на закреплённой ссылке: %s\n' "$rc_clean"
[ "$rc_warn" -eq 1 ] && [ "$rc_clean" -eq 0 ] \
    && ok "проверка различает закреплённые и неявные ссылки" \
    || bad "коды: $rc_warn и $rc_clean"

printf '\n═══ ИТОГ ═══\n'
[ "$fail" -eq 0 ] && echo "  все требования выполнены" || echo "  ЕСТЬ ПРОВАЛЫ"

docker rm -f lab-reg > /dev/null 2>&1
docker volume rm lab-reg-data > /dev/null 2>&1
docker rmi -f localhost:5000/app:a localhost:5000/app:b > /dev/null 2>&1
cd /tmp && rm -rf /tmp/reglab
exit "$fail"

═══ Требование 1: разбор пяти ссылок ═══
    ссылка                             полное имя                                   офиц.
    ────────────────────────────────────────────────────────────────────────────────────────
    python                             docker.io/library/python:latest              да
    python:3.13-slim                   docker.io/library/python:3.13-slim           да
    myorg/api:1.2                      docker.io/myorg/api:1.2                      нет
    ghcr.io/myorg/api:1.2              ghcr.io/myorg/api:1.2                        нет
    localhost:5000/svc@sha256:abc123   localhost:5000/svc@sha256:abc123             нет

    python: registry=docker.io, тег=latest, namespace=library → официальный образ
    python:3.13-slim: registry=docker.io, namespace=library → официальный образ
    myorg/api:1.2: registry=docker.io
    официальных образов: 2
    ghcr.io собран как: ghcr.io/myorg/api:1.2
  ✓ подстановки определены верно, registry не задвоен

═══ Подготовка: локальный registry ═══
    registry отвечает: HTTP 200
    два образа собраны

═══ Требование 2: повторная публикация общих слоёв ═══
    публикация                   передано  пропущено    всего слоёв
    ──────────────────────────────────────────────────────────────
    app:a (первая)               5         0            5
    app:b (общая база)           1         4            5
    экономия на второй: 4 из 5 слоёв не передавались
  ✓ общие слои пропущены: проверка HEAD вернула 200

═══ Требование 3: другой репозиторий ═══
    second/app:a (тот же образ)  5         0            5
    digest app:a          sha256:4d2c8f1e9a0b3c5d7e2f4a...
    digest second/app:a   sha256:4d2c8f1e9a0b3c5d7e2f4a...
    digest СОВПАДАЕТ — образ тот же
  ✓ тот же образ передан заново: дедупликация в пределах репозитория

═══ Требование 4: три digest ═══
    config digest (Id)     sha256:9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f...
    RepoDigest             python@sha256:4a1e2b3c4d5e6f7a8b9c0d1e2f3a4b5c...
    manifest digest        манифестов платформ: 8; первый: sha256:7f3e2a1b9c8d4e...

    назначение каждого:
      Id          локальный идентификатор конфигурации; в pull не передаётся
      RepoDigest  существует в registry; им закрепляют версию в FROM
      manifest    конкретная платформа; выбирается при pull автоматически
  ✓ три значения различны; для закрепления пригоден RepoDigest

═══ Требование 5: целостность ═══
    Id до удаления:  sha256:3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
    Id после pull:   sha256:3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
  ✓ получен тот же образ; проверка sha256 встроена в адресацию

═══ Требование 6: проверка подстановок ═══
  python                             → docker.io/library/python:latest
      ⚠ тег latest подставлен: образ не закреплён
      · подстановок по умолчанию: 3
  python:3.13-slim                   → docker.io/library/python:3.13-slim
      · подстановок по умолчанию: 2
  ghcr.io/org/api@sha256:abc123      → ghcr.io/org/api@sha256:abc123
      ✓ закреплён по digest

  ссылок, требующих внимания: 1
    код возврата при неявных ссылках: 1
    код возврата на закреплённой ссылке: 0
  ✓ проверка различает закреплённые и неявные ссылки

═══ ИТОГ ═══
  все требования выполнены