Mirror Registry — Скачивание и загрузка образов

Команда bootsmanctl mirror registry предназначена для зеркалирования образов контейнеров из исходного реестра в целевой через промежуточные tar-архивы. Это позволяет работать в air-gapped средах (без прямого доступа между реестрами) и переносить образы между машинами.

Обзор

Рабочий процесс состоит из двух этапов:

Исходный реестр ──[download]──> Tar-архивы ──[upload]──> Целевой реестр

1. download — скачивает образы из исходного реестра и сохраняет их в локальные tar-архивы
2. upload — загружает образы из локальных архивов в целевой реестр

Архивы хранятся в указанной директории и содержат манифест (mirror-manifest.json) с метаданными: список образов, контрольные суммы SHA-256 и информацию о фрагментации.

---

Команда download

Скачивает образы указанной версии релиза из исходного реестра в локальные архивы.

Синтаксис

bootsmanctl mirror registry download \
  --release=v3.3.0 \
  [--archive-dir=./mirror-archives] \
  [--max-archive-size=100M] \
  [--encryption-password=secret] \
  [--insecure] \
  [--src-url] \
  [--src-username] \
  [--src-password]

Параметры

Параметр	Обязательный	Описание
--release, -r	Да	Версия релиза для зеркалирования (например, v3.3.0)
--archive-dir	Нет	Директория для сохранения архивов. По умолчанию: ./mirror-archives
--max-archive-size	Нет	Максимальный размер одного архива (например, 1G, 500M). По умолчанию: 0 (без ограничений)
--encryption-password	Нет	Пароль для шифрования архивов (PGP symmetric). Если не указан — архивы не шифруются
--insecure, -i	Нет	Разрешить небезопасное подключение к реестру (без проверки TLS)
--src-url	Нет	Адрес исходного реестра
--src-username	Нет	Имя пользователя исходного реестра
--src-password	Нет	Пароль пользователя исходного реестра

Примечание 1

Исходный реестр и учётные данные автоматически определяются из файла лицензии.
Реестр и учётные данные можно задать в ручную, используя параметры --src-url, --src-username, --src-password.
В частности, с помощью этих параметров можно задать адрес и учётные данные к прокси.

Примечание 2

Параметр --src-url не должен содержать схему. Может содержать порт. И должен содержать путь.
Пример: registry.internal.com:31002/images

Примеры

Базовое скачивание (без ограничений):

bootsmanctl mirror registry download --release=v3.3.0

Архивы будут сохранены в ./mirror-archives/v3.3.0/.

С ограничением размера архива:

bootsmanctl mirror registry download \
  --release=v3.3.0 \
  --max-archive-size=100M

Если образы превышают указанный размер, они автоматически разбиваются на части.

С шифрованием архивов:

bootsmanctl mirror registry download \
  --release=v3.3.0 \
  --max-archive-size=100M \
  --encryption-password=my-secret-password

Архивы будут зашифрованы с помощью PGP symmetric encryption. Файлы получат расширение .enc.

---

Команда upload

Загружает образы из локальных архивов в целевой реестр.

Синтаксис

bootsmanctl mirror registry upload \
  --release=v3.3.0 \
  --url=registry.target.com \
  --username=admin \
  --password=secret \
  [--archive-dir=./mirror-archives] \
  [--encryption-password=secret] \
  [--force-push] \
  [--insecure]

Параметры

Параметр	Обязательный	Описание
--release, -r	Да	Версия релиза для зеркалирования (например, v3.3.0)
--url, -U	Да	URL целевого реестра
--username, -u	Да	Имя пользователя целевого реестра
--password, -p	Да	Пароль пользователя целевого реестра
--archive-dir	Нет	Директория со скаченными релизами
--encryption-password	Нет	Пароль для расшифровки архивов (обязателен, если архивы зашифрованы)
--force-push, -f	Нет	Заменять существующие образы с тем же именем
--insecure, -i	Нет	Разрешить небезопасное подключение к реестру (без проверки TLS)

Примеры

Базовая загрузка:

bootsmanctl mirror registry upload \
  --release=v3.3.0 \
  --url=registry.internal.com \
  --username=admin \
  --password=secret

Загрузка зашифрованных архивов:

bootsmanctl mirror registry upload \
  --release=v3.3.0 \
  --url=registry.internal.com \
  --username=admin \
  --password=secret \
  --encryption-password=my-secret-password

---

Формат архивов

Структура файлов

mirror-archives/v3.3.0/
├── mirror-manifest.json      # Манифест с метаданными
├── mirror.tar.1              # Часть архива (без шифрования)
├── mirror.tar.2              # Часть архива (без шифрования)

Или с шифрованием:

mirror-archives/v3.3.0/
├── mirror-manifest.json      # Манифест с метаданными и тестовым шифротекстом
├── mirror.tar.1.enc          # Зашифрованная часть архива
├── mirror.tar.2.enc          # Зашифрованная часть архива

Манифест

Файл mirror-manifest.json содержит:

{
  "createdAt": "2025-01-15T10:30:00Z",
  "maxArchiveSize": 104857600,
  "encryption": {
    "testCiphertext": "base64-encoded-pgp-encrypted-test-message"
  },
  "parts": [
    {
      "file": "mirror.tar.1.enc",
      "checksum": "sha256:def456...",
      "size": 104857600,
      "images": [
        {
          "source": "registry.src.com/nginx:1.25",
          "target": "nginx:1.25",
          "totalSize": 50000000
        }
      ]
    }
  ]
}

Поле encryption присутствует только для зашифрованных архивов.

---

Автоматическое разбиение на части

При указании --max-archive-size работает автоматическая логика разбиения:

Значение --max-archive-size	Поведение
Не указан или 0	Без ограничений, все образы записываются как единые файлы
Указан (например, 100M)	Умное разбиение: образы, помещающиеся в оставшееся место, записываются целиком; остальные разбиваются на фрагменты

При разбиении фрагменты получают имена вида <base64url(sourceRef)>.chunk.0, <base64url(sourceRef)>.chunk.1 и т.д. При загрузке (upload) фрагменты автоматически собираются обратно в единый поток.

---

Шифрование

• Алгоритм: PGP symmetric encryption (RFC 4880 OpenPGP)
• Библиотека: github.com/ProtonMail/gopenpgp/v3
• Проверка пароля: При скачивании создаётся тестовое сообщение, зашифрованное тем же паролем. При загрузке пароль проверяется попыткой расшифровки этого сообщения.
• Целостность: MDC (Modification Detection Code) для обнаружения изменений в данных
• Контрольные суммы: SHA-256 для каждой части архива проверяется перед обработкой

---

Обработка ошибок

Ситуация	Поведение
Неправильный пароль	Ошибка: password verification failed: incorrect password
Повреждённый архив	Ошибка контрольной суммы перед обработкой
Отсутствует часть архива	Ошибка: failed to open archive file
Зашифрованный архив без пароля	Ошибка: archive is encrypted but no password provided
Незашифрованный архив с паролем	Пароль игнорируется
Образ уже существует в реестре	Без --force-push — пропускается с сообщением в логе

---

Типичные сценарии использования

Сценарий 1: Air-gapped среда

1. На машине с доступом к интернету скачайте образы:

   bootsmanctl mirror registry download --release-=v3.3.0 --encryption-password=secret

2. Перенесите директорию mirror-archives/v3.3.0 на изолированную машину (USB, SCP и т.д.)

3. Загрузите образы во внутренний реестр:

   bootsmanctl mirror registry upload \
     --release=v3.3.0 \
     --url=registry.internal.com \
     --username=admin \
     --password=secret \
     --encryption-password=secret

Сценарий 2: Ограничение размера для FAT32

Для переноса на носителях с ограничением размера файла (например, FAT32 — 4 ГБ):

bootsmanctl mirror registry download \
  --release=v3.3.0 \
  --max-archive-size=3G

Сценарий 3: Без шифрования (доверенная сеть)

# Скачивание
bootsmanctl mirror registry download \
  --release=v3.3.0 \
  --max-archive-size=100M

# Загрузка
bootsmanctl mirror registry upload \
  --release=v3.3.0 \
  --url=registry.internal.com \
  --username=admin \
  --password=secret

Сценарий 4: С использованием прокси

bootsmanctl mirror registry download \
  --release=v3.3.0 \
  --src-url=registry.internal.com \
  --src-username=admin \
  --src-password=secret

Связанные страницы

• Проксирование реестра образов