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

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

Обзор

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

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

download — скачивает образы из исходного реестра и сохраняет их в локальные tar-архивы
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 среда

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

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

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

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

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

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

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