14.3. Локальный registry

docker run -d --name registry \
    -p 5000:5000 \
    -v registry-data:/var/lib/registry \
    --restart unless-stopped \
    registry:2

curl -s http://localhost:5000/v2/          # {} при успехе
curl -s http://localhost:5000/v2/_catalog  # список репозиториев

{
  "insecure-registries": ["registry.local:5000", "192.168.1.0/24"]
}

docker run -d --name registry \
    -p 443:443 \
    -v registry-data:/var/lib/registry \
    -v "$PWD/certs:/certs:ro" \
    -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/cert.pem \
    -e REGISTRY_HTTP_TLS_KEY=/certs/key.pem \
    registry:2

/etc/docker/certs.d/registry.local:5000/ca.crt

proxy:
  remoteurl: https://registry-1.docker.io

docker run -d --name mirror -p 5000:5000 \
    -v mirror-data:/var/lib/registry \
    -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
    registry:2

{
  "registry-mirrors": ["http://mirror.local:5000"]
}

docker run -d --name test-registry -p 0:5000 \
    -e REGISTRY_STORAGE_DELETE_ENABLED=true \
    registry:2

/var/lib/registry/docker/registry/v2/
├── blobs/sha256/<2 символа>/<полный digest>/data
└── repositories/<имя>/
    ├── _layers/sha256/<digest>/link       ← ссылка на blob
    ├── _manifests/tags/<тег>/current/link ← куда указывает тег
    └── _manifests/revisions/sha256/<digest>/link

docker exec registry bin/registry garbage-collect \
    /etc/docker/registry/config.yml --dry-run

storage:
  maintenance:
    readonly:
      enabled: true

mkdir -p /tmp/localreg && cd /tmp/localreg

echo "═══ запуск с volume ═══"
docker run -d --name reg -p 5000:5000 \
    -v reg-data:/var/lib/registry \
    -e REGISTRY_STORAGE_DELETE_ENABLED=true \
    registry:2 > /dev/null
sleep 4

echo "═══ проверка API ═══"
printf '  /v2/          '
curl -s -w 'HTTP %{http_code}  тело: ' http://localhost:5000/v2/ && echo
printf '  /v2/_catalog  '
curl -s -w 'HTTP %{http_code}  тело: ' http://localhost:5000/v2/_catalog && echo

echo "═══ публикуем образ ═══"
docker pull -q alpine:3.21 > /dev/null
docker tag alpine:3.21 localhost:5000/test/alpine:1.0
docker push localhost:5000/test/alpine:1.0 2>&1 | tail -2 | sed 's/^/  /'

echo "═══ что теперь в каталоге ═══"
curl -s http://localhost:5000/v2/_catalog | python3 -m json.tool | sed 's/^/  /'
curl -s http://localhost:5000/v2/test/alpine/tags/list | python3 -m json.tool | sed 's/^/  /'

echo "═══ данные переживают пересоздание container'а ═══"
docker rm -f reg > /dev/null
docker run -d --name reg -p 5000:5000 -v reg-data:/var/lib/registry \
    registry:2 > /dev/null
sleep 4
curl -s http://localhost:5000/v2/_catalog | python3 -c "
import json, sys
d = json.load(sys.stdin)
repos = d.get('repositories') or []
print(f'  репозиториев после пересоздания: {len(repos)} {repos}')
"

═══ запуск с volume ═══
═══ проверка API ═══
  /v2/          HTTP 200  тело: {}
  /v2/_catalog  HTTP 200  тело: {"repositories":[]}
═══ публикуем образ ═══
  1f3e2d4c5b6a: Pushed
  1.0: digest: sha256:8a3f2b1c... size: 528
═══ что теперь в каталоге ═══
  {
      "repositories": [
          "test/alpine"
      ]
  }
  {
      "name": "test/alpine",
      "tags": [
          "1.0"
      ]
  }
═══ данные переживают пересоздание container'а ═══
  репозиториев после пересоздания: 1 ['test/alpine']

cd /tmp/localreg
echo "═══ подключаем registry к пользовательской сети ═══"
docker network create reg-net > /dev/null 2>&1
docker network connect reg-net reg 2>/dev/null || true

echo "═══ обращение БЕЗ порта ═══"
docker run --rm --network reg-net alpine:3.21 sh -c '
    apk add --no-cache curl > /dev/null 2>&1
    curl -s -o /dev/null -w "  curl к reg:5000/v2/ → HTTP %{http_code}\n" http://reg:5000/v2/
' 2>/dev/null

echo "═══ что делает docker pull с именем без точки ═══"
timeout 25 docker pull reg/test/alpine:1.0 2>&1 | head -2 | sed 's/^/  /' || true

echo "═══ то же имя С портом ═══"
docker run --rm --network reg-net docker:cli sh -c '
    docker pull reg:5000/test/alpine:1.0 2>&1 | tail -1
' 2>/dev/null | sed 's/^/  /' || echo "  (требует доступа к socket — см. пояснение ниже)"

echo "═══ правило ═══"
cat <<'TXT'
  reg/test/alpine       → docker.io/reg/test/alpine   ✗ уходит на Docker Hub
  reg:5000/test/alpine  → registry reg:5000            ✓ верно

  Первая часть считается адресом registry, только если содержит
  точку, двоеточие или равна localhost.

  Практическое следствие для Compose: обращаться к сервису-registry
  нужно с портом — reg:5000/образ, а не reg/образ.
TXT

═══ подключаем registry к пользовательской сети ═══
═══ обращение БЕЗ порта ═══
  curl к reg:5000/v2/ → HTTP 200
═══ что делает docker pull с именем без точки ═══
  Error response from daemon: pull access denied for reg/test/alpine,
  repository does not exist or may require 'docker login'
═══ то же имя С портом ═══
  (требует доступа к socket — см. пояснение ниже)
═══ правило ═══
  reg/test/alpine       → docker.io/reg/test/alpine   ✗ уходит на Docker Hub
  reg:5000/test/alpine  → registry reg:5000            ✓ верно

  Первая часть считается адресом registry, только если содержит
  точку, двоеточие или равна localhost.

  Практическое следствие для Compose: обращаться к сервису-registry
  нужно с портом — reg:5000/образ, а не reg/образ.

cd /tmp/localreg
mkdir -p certs

echo "═══ генерируем сертификат с SAN ═══"
openssl req -x509 -newkey rsa:2048 -nodes -days 30 \
    -keyout certs/key.pem -out certs/cert.pem \
    -subj "/CN=registry.local" \
    -addext "subjectAltName=DNS:registry.local,DNS:localhost,IP:127.0.0.1" \
    2>/dev/null
echo "  сертификат создан"

echo "═══ что в сертификате ═══"
openssl x509 -in certs/cert.pem -noout -subject -dates -ext subjectAltName 2>/dev/null \
    | sed 's/^/  /'

echo "═══ запуск registry с TLS ═══"
docker rm -f reg > /dev/null 2>&1
docker run -d --name reg-tls -p 5443:443 \
    -v reg-data:/var/lib/registry \
    -v "$PWD/certs:/certs:ro" \
    -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/cert.pem \
    -e REGISTRY_HTTP_TLS_KEY=/certs/key.pem \
    registry:2 > /dev/null
sleep 4

echo "═══ проверка соединения ═══"
printf '  без доверия к корню:  '
curl -s -o /dev/null -w 'HTTP %{http_code}\n' https://localhost:5443/v2/ 2>&1 \
    || echo "отказ проверки сертификата (ожидаемо)"
printf '  с указанием корня:    '
curl -s --cacert certs/cert.pem -o /dev/null -w 'HTTP %{http_code}\n' \
    https://localhost:5443/v2/ 2>&1 || echo "не удалось"

echo "═══ что проверяет клиент ═══"
cat <<'TXT'
  1. Подпись доверенным центром — или корень в
       /etc/docker/certs.d/<хост>:<порт>/ca.crt
  2. Срок действия
  3. Имя хоста в SAN (поле CN современные клиенты ИГНОРИРУЮТ)

  Каталог для корня называется ТОЧНО как имя в docker pull,
  включая порт:
    /etc/docker/certs.d/registry.local:5443/ca.crt

  Несовпадение имени каталога и имени в pull — самая частая
  причина «сертификат не подхватывается».
TXT

═══ генерируем сертификат с SAN ═══
  сертификат создан
═══ что в сертификате ═══
  subject=CN = registry.local
  notBefore=Jul 31 10:22:14 2026 GMT
  notAfter=Aug 30 10:22:14 2026 GMT
  X509v3 Subject Alternative Name: 
      DNS:registry.local, DNS:localhost, IP Address:127.0.0.1
═══ запуск registry с TLS ═══
═══ проверка соединения ═══
  без доверия к корню:  отказ проверки сертификата (ожидаемо)
  с указанием корня:    HTTP 200
═══ что проверяет клиент ═══
  1. Подпись доверенным центром — или корень в
       /etc/docker/certs.d/<хост>:<порт>/ca.crt
  2. Срок действия
  3. Имя хоста в SAN (поле CN современные клиенты ИГНОРИРУЮТ)
  ...

cd /tmp/localreg
cat > insecure-risk.py <<'PY'
"""Что защищено и что не защищено при работе с registry без TLS."""
from __future__ import annotations

ASPECTS = [
    ("Содержимое слоёв", True,
     "digest слоя проверяется клиентом: подменённый слой не пройдёт"),
    ("Конфиденциальность слоёв", False,
     "слои передаются открытым текстом и читаются в канале"),
    ("Подлинность сервера", False,
     "подмена адреса не обнаруживается: DNS, ARP, маршрут"),
    ("Целостность манифеста при запросе по тегу", False,
     "поддельный сервер вернёт СВОЙ манифест со СВОИМИ корректными digest"),
    ("Целостность при запросе по digest", True,
     "digest манифеста задан клиентом и проверяется"),
    ("Учётные данные", False,
     "docker login по HTTP передаёт пароль открытым текстом"),
]

CONDITIONS = [
    ("Изолированная сеть без выхода наружу", "нет пути для атакующего"),
    ("Только разработка и тесты", "артефакт не попадёт в эксплуатацию"),
    ("Аутентификация НЕ используется", "нет пароля для перехвата"),
    ("Образы не конфиденциальны", "открытая передача не создаёт утечки"),
]


def main() -> None:
    print(f"  {'аспект':<44} {'защищён':<9} пояснение")
    print("  " + "─" * 108)
    for name, protected, why in ASPECTS:
        mark = "да" if protected else "НЕТ"
        print(f"  {name:<44} {mark:<9} {why}")

    print()
    print("  Ключевой вывод строк 4 и 5:")
    print("    docker pull ОБРАЗ:тег        уязвим к подмене")
    print("    docker pull ОБРАЗ@sha256:... защищён даже без TLS")
    print()
    print("  Условия допустимости insecure registry — ВСЕ сразу:")
    for cond, why in CONDITIONS:
        print(f"    · {cond:<42} {why}")
    print()
    print("  Недопустимое сочетание: HTTP + docker login.")
    print("  Пароль уходит открытым текстом в каждом запросе.")


if __name__ == "__main__":
    main()
PY

echo "═══ разбор рисков ═══"
python3 insecure-risk.py

═══ разбор рисков ═══
  аспект                                       защищён   пояснение
  ────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Содержимое слоёв                             да        digest слоя проверяется клиентом: подменённый слой не пройдёт
  Конфиденциальность слоёв                     НЕТ       слои передаются открытым текстом и читаются в канале
  Подлинность сервера                          НЕТ       подмена адреса не обнаруживается: DNS, ARP, маршрут
  Целостность манифеста при запросе по тегу    НЕТ       поддельный сервер вернёт СВОЙ манифест со СВОИМИ корректными digest
  Целостность при запросе по digest            да        digest манифеста задан клиентом и проверяется

  Ключевой вывод строк 4 и 5:
    docker pull ОБРАЗ:тег        уязвим к подмене
    docker pull ОБРАЗ@sha256:... защищён даже без TLS

  Условия допустимости insecure registry — ВСЕ сразу:
    · Изолированная сеть без выхода наружу     нет пути для атакующего
    · Только разработка и тесты                артефакт не попадёт в эксплуатацию
    · Аутентификация НЕ используется           нет пароля для перехвата
    · Образы не конфиденциальны                открытая передача не создаёт утечки

  Недопустимое сочетание: HTTP + docker login.
  Пароль уходит открытым текстом в каждом запросе.

cd /tmp/localreg
echo "═══ запуск зеркала ═══"
docker run -d --name mirror -p 5100:5000 \
    -v mirror-data:/var/lib/registry \
    -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
    registry:2 > /dev/null
sleep 4
curl -s -o /dev/null -w '  зеркало отвечает: HTTP %{http_code}\n' http://localhost:5100/v2/

echo "═══ настройка клиента ═══"
cat <<'TXT'
  /etc/docker/daemon.json:
    {
      "registry-mirrors": ["http://mirror.local:5100"]
    }

  После перезапуска daemon любой docker pull публичного образа
  сначала обращается к зеркалу.
TXT

echo "═══ проверка: что кэшируется ═══"
curl -s http://localhost:5100/v2/_catalog | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(f\"  в кэше до обращений: {d.get('repositories') or 'пусто'}\")
"

echo "═══ попытка публикации в зеркало ═══"
docker tag alpine:3.21 localhost:5100/my/app:1.0 2>/dev/null
docker push localhost:5100/my/app:1.0 2>&1 | tail -2 | sed 's/^/  /'

echo "═══ вывод ═══"
cat <<'TXT'
  Зеркало работает ТОЛЬКО на чтение. Публикация в него невозможна.

  Значит, нужны ДВА экземпляра:
    зеркало           для публичных образов, режим proxy
    свой registry     для собственных образов, обычный режим

  Один container не может совмещать роли: REGISTRY_PROXY_REMOTEURL
  переводит весь экземпляр в режим кэша.

  Что даёт зеркало:
    один запрос к Docker Hub на организацию вместо одного на машину
    независимость от доступности внешнего registry для уже скачанного
    ускорение повторных сборок в CI
TXT

═══ запуск зеркала ═══
  зеркало отвечает: HTTP 200
═══ настройка клиента ═══
  /etc/docker/daemon.json:
    {
      "registry-mirrors": ["http://mirror.local:5100"]
    }

  После перезапуска daemon любой docker pull публичного образа
  сначала обращается к зеркалу.
═══ проверка: что кэшируется ═══
  в кэше до обращений: пусто
═══ попытка публикации в зеркало ═══
  unsupported: The operation is unsupported.
═══ вывод ═══
  Зеркало работает ТОЛЬКО на чтение. Публикация в него невозможна.
  ...

cd /tmp/localreg
cat > test_registry.py <<'PY'
"""Интеграционные тесты с настоящим registry.

Показывает три вещи, которые нельзя проверить без него:
публикацию, совпадение digest после получения и работу с API.
"""
from __future__ import annotations

import json
import subprocess
import time

import pytest

IMAGE_SOURCE = "alpine:3.21"


def run(*args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
    return subprocess.run(args, capture_output=True, text=True, check=check)


@pytest.fixture(scope="module")
def registry() -> str:
    """Поднимает registry на СЛУЧАЙНОМ порту — параллельные тесты не конфликтуют."""
    name = f"pytest-registry-{int(time.time())}"
    run("docker", "run", "-d", "--name", name,
        "-p", "0:5000",                     # 0 = любой свободный порт
        "-e", "REGISTRY_STORAGE_DELETE_ENABLED=true",
        "registry:2")
    try:
        # Узнаём фактический порт
        out = run("docker", "port", name, "5000/tcp").stdout.strip()
        port = out.splitlines()[0].rsplit(":", 1)[1]
        base = f"localhost:{port}"

        # Ждём готовности
        for _ in range(30):
            probe = run("curl", "-sf", f"http://{base}/v2/", check=False)
            if probe.returncode == 0:
                break
            time.sleep(0.5)
        else:
            pytest.fail("registry не поднялся")

        yield base
    finally:
        run("docker", "rm", "-f", name, check=False)


@pytest.fixture(scope="module")
def published(registry: str) -> str:
    ref = f"{registry}/testapp:1.0"
    run("docker", "pull", "-q", IMAGE_SOURCE)
    run("docker", "tag", IMAGE_SOURCE, ref)
    run("docker", "push", ref)
    yield ref
    run("docker", "rmi", "-f", ref, check=False)


def test_registry_отвечает(registry: str) -> None:
    out = run("curl", "-s", f"http://{registry}/v2/").stdout
    assert json.loads(out) == {}


def test_образ_появился_в_каталоге(registry: str, published: str) -> None:
    out = run("curl", "-s", f"http://{registry}/v2/_catalog").stdout
    assert "testapp" in json.loads(out)["repositories"]


def test_тег_виден_через_api(registry: str, published: str) -> None:
    out = run("curl", "-s", f"http://{registry}/v2/testapp/tags/list").stdout
    assert json.loads(out)["tags"] == ["1.0"]


def test_digest_совпадает_после_получения(registry: str, published: str) -> None:
    """Ключевая проверка: полученный образ идентичен опубликованному."""
    before = run("docker", "inspect", published, "--format", "{{.Id}}").stdout.strip()
    run("docker", "rmi", "-f", published, check=False)
    run("docker", "pull", "-q", published)
    after = run("docker", "inspect", published, "--format", "{{.Id}}").stdout.strip()
    assert before == after, "образ изменился при передаче через registry"


def test_получение_по_digest(registry: str, published: str) -> None:
    """Получение по digest — то, чем развёртывание отличается от pull по тегу."""
    repo_digest = run(
        "docker", "inspect", published,
        "--format", "{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}",
    ).stdout.strip()
    assert repo_digest, "RepoDigests пуст: образ не публиковался"
    assert "@sha256:" in repo_digest

    run("docker", "rmi", "-f", published, check=False)
    result = run("docker", "pull", "-q", repo_digest, check=False)
    assert result.returncode == 0, result.stderr


def test_несуществующий_тег_даёт_404(registry: str) -> None:
    code = run("curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
               f"http://{registry}/v2/testapp/manifests/несуществующий").stdout
    assert code == "404"
PY

echo "═══ запуск тестов ═══"
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v "$PWD:/w" -w /w \
    --network host \
    python:3.13-slim sh -c '
    apt-get update -qq > /dev/null 2>&1
    apt-get install -y -qq curl > /dev/null 2>&1
    pip install --quiet --no-cache-dir pytest==9.1.1 > /dev/null 2>&1
    pip install --quiet --no-cache-dir docker > /dev/null 2>&1
    command -v docker > /dev/null || {
        apt-get install -y -qq docker.io > /dev/null 2>&1
    }
    python -m pytest test_registry.py -v --tb=short 2>&1 | tail -18
' 2>/dev/null | sed 's/^/  /' \
    || echo "  (тесты требуют доступа к Docker socket из container'а)"

echo "═══ ключевые решения в этих тестах ═══"
cat <<'TXT'
  -p 0:5000               случайный порт: параллельные тесты не конфликтуют
  без volume              данные исчезают вместе с container'ом
  DELETE_ENABLED=true     нужен, если тест проверяет удаление
  scope="module"          registry поднимается один раз на файл тестов
  проверка готовности     цикл с curl вместо фиксированного sleep

  Последнее существенно: фиксированная пауза либо избыточна,
  либо недостаточна на медленной машине.
TXT

docker rm -f reg reg-tls mirror > /dev/null 2>&1
docker network rm reg-net > /dev/null 2>&1
docker volume rm reg-data mirror-data > /dev/null 2>&1
cd /tmp && rm -rf /tmp/localreg

═══ запуск тестов ═══
  test_registry.py::test_registry_отвечает PASSED                       [ 16%]
  test_registry.py::test_образ_появился_в_каталоге PASSED               [ 33%]
  test_registry.py::test_тег_виден_через_api PASSED                     [ 50%]
  test_registry.py::test_digest_совпадает_после_получения PASSED        [ 66%]
  test_registry.py::test_получение_по_digest PASSED                     [ 83%]
  test_registry.py::test_несуществующий_тег_даёт_404 PASSED             [100%]
  
  ============================ 6 passed in 24.31s ============================
═══ ключевые решения в этих тестах ═══
  -p 0:5000               случайный порт: параллельные тесты не конфликтуют
  без volume              данные исчезают вместе с container'ом
  DELETE_ENABLED=true     нужен, если тест проверяет удаление
  scope="module"          registry поднимается один раз на файл тестов
  проверка готовности     цикл с curl вместо фиксированного sleep

  Последнее существенно: фиксированная пауза либо избыточна,
  либо недостаточна на медленной машине.

curl -s http://localhost:5000/v2/
curl -s http://localhost:5000/v2/_catalog | python3 -m json.tool
docker inspect registry --format '{{json .Mounts}}' | python3 -m json.tool
openssl x509 -in certs/cert.pem -noout -ext subjectAltName
ls /etc/docker/certs.d/