ORAS: реестр OCI как универсальное хранилище

Логотип проекта ORAS (OCI Registry As Storage)

Краткие ссылки

Docker Hub против реестров OCI
Почему универсальные артефакты важны
Влияет ли ORAS на контейнерные образы
Установка ORAS CLI
Использование ORAS с Docker Hub
Дополнительно: безопасность, миграция и контроль качества
Резюме

Введение

Docker Hub — самый известный реестр для распространения контейнерных образов. Но теперь реестры OCI могут хранить гораздо больше, чем просто образы. Проект ORAS (OCI Registry As Storage) расширяет реестры до универсальных хранилищ артефактов, позволяя публиковать любые файлы и метаданные, относящиеся к вашему приложению.

Краткое определение: артефакт — это любой файл или набор файлов, которые нужны пользователю для запуска, проверки или сопровождения приложения (чарты, SBOM, бинарники, подписи и т. п.).

В этой статье вы найдёте: что такое ORAS, какие проблемы оно решает, как начать использовать ORAS с Docker Hub, а также рекомендации по безопасности, тестированию и внедрению в CI/CD.

Docker Hub против реестров OCI

Контейнерная экосистема давно вышла за рамки одного поставщика: стандарты OCI сделали возможным совместную работу множества инструментов и провайдеров (Docker, Podman, Kubernetes и т. д.).

Docker Hub — это один из реализованных реестров, совместимых со спецификациями OCI. Традиционные команды работы с образами выглядят так:

docker pull

docker push

Ранее эти команды использовались только для контейнерных образов. ORAS позволяет использовать аналогичный механизм для других типов артефактов, сохраняя знакомые паттерны работы.

Почему универсальные артефакты важны

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

Решение ORAS: хранить всё в реестре OCI рядом с образом, при этом использовать единый набор инструментов и учётных данных. Примеры артефактов:

Helm charts
Предкомпилированные бинарники и пакеты инсталлятора
SBOM (Software Bill of Materials)
Конфигурации политики безопасности (например, правила OPA)
Подписи, сертификаты и метаданные релиза

Преимущества:

Единая точка доставки и доступа
Консистентная аутентификация и авторизация
Возможность версионирования и тегирования артефактов
Лёгкая интеграция в CI/CD-пайплайны

Пример получения SBOM для релиза v1.1.0:

oras pull example.com/my-app/sbom:v1.1.0

Влияет ли ORAS на контейнерные образы

Коротко: нет. ORAS не ломает существующие возможности реестров или способ работы с образами. Вы по‑прежнему можете использовать:

docker push my-image:latest

Однако меняется внутреннее представление контента: реестры перестают предполагать, что всё — это контейнерный образ. Для каждого загружаемого объекта реестр теперь должен фиксировать тип содержимого — «media type».

Инструменты типа Docker по‑умолчанию помечают содержимое как тип образа.
ORAS может применить «unknown» тип, если вы не укажете зарегистрированный media type.
Сообщества могут регистрировать собственные media types для распространённых артефактов (например, Helm).

Это даёт возможность провайдерам реестров отображать и обрабатывать артефакты более осмысленно.

Установка ORAS CLI

ORAS CLI нужен для push/pull артефактов произвольных типов. Скачайте релиз с GitHub проекта. На момент написания поддерживаются macOS и Linux.

Распакуйте архив и поместите бинарник в директорию, которая находится в PATH:

$ tar -zxf oras_0.16.0_*.tar.gz -C oras-install/

$ mv oras-install/oras /usr/local/bin/

$ rm -rf oras_0.16.0_*.tar.gz oras-install/

Проверьте работу:

$ oras version

Пример вывода:

0.16.0

Примечание: версии и имена архивов могут меняться — используйте релиз, соответствующий вашей ОС.

Использование ORAS с Docker Hub

Важно: ORAS совместим только с реестрами, которые реализовали спецификацию OCI Artifacts. Сейчас большинство крупных провайдеров (Amazon ECR, Azure, Google Artifact Registry, GitHub Packages) и CNCF-дистрибуции поддерживают её. Docker Hub добавил полную поддержку OCI Artifacts в ноябре 2022.

Авторизация в реестре

ORAS автоматически использует учётные данные, сохранённые в ~/.docker/config.json. Вы можете войти через docker login или через ORAS напрямую:

$ oras login -u username -p password_or_personal_access_token

или

$ docker login -u username -p password_or_personal_access_token

После успешного логина создайте простой файл для загрузки. Это может быть любой полезный артефакт; в примере — JSON с метаданными релиза:

$ echo '{"app": "oras-demo", "version": "1.1.0"}' > artifact.json

Отправка артефакта

Запустите команду push (замените на ваше имя в Docker Hub):

$ oras push docker.io//oras-demo:1.1.0 \

artifact.json:application/json \

--artifact-type application/vnd.unknown.config.v1+json

Типичный вывод:

Uploading 7ac68d8d2a12 artifact.json

Uploaded 7ac68d8d2a12 artifact.json

Pushed docker.io/ilmiont/oras-demo:1.1.0

Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

Ключевые моменты:

Первый аргумент — адрес реестра и тег, аналогично тегированию образов.
ORAS требует явного указания URL реестра (docker.io для Docker Hub).
Второй аргумент — filename:content-type (например, artifact.json:application/json).
Третий аргумент — ORAS artifact type (media type). Для нестандартных файлов можно использовать application/vnd.unknown.*.

Для проверки выполните:

$ oras repo tags docker.io//oras-demo

Ожидаемый вывод:

1.1.0

Просмотр и управление в интерфейсе Docker Hub

Ваш артефакт появится в Docker Hub. В списке репозиториев будет пометка “Contains: Other” для универсальных артефактов; обычные репозитории образов помечены как “Contains: Image”.

Скриншот: репозиторий с общим артефактом в Docker Hub

Откройте репозиторий, чтобы добавить описание, увидеть теги и загрузить файлы — интерфейс очень похож на работу с образами.

Получение артефакта

На другой машине установите ORAS и выполните вход в Docker Hub, затем выполните:

$ oras pull docker.io//oras-demo:1.1.0

Пример вывода:

Downloading 7ac68d8d2a12 artifact.json

Downloaded 7ac68d8d2a12 artifact.json

Pulled docker.io/ilmiont/oras-demo:1.1.0

Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

Файлы попадут в рабочую директорию:

$ ls

artifact.json

$ cat artifact.json

{"app": "demo-oras", "version": "1.1.0"}

Вы успешно распространили артефакт через реестр.

Практические рекомендации и паттерны интеграции

Группируйте артефакты по репозиторию. Если артефакты логически связаны с образом, размещайте их рядом (один репозиторий — один набор связанных артефактов).
Используйте семантические теги и версии, чтобы облегчить откат и совместимость.
Стандартизируйте media types в вашей организации: заведите внутренний документ с перечнем используемых типов для SBOM, политик, подписей и т. п.
Автоматизируйте push в CI: после сборки создавайте артефакты (SBOM, подписи, релизные ноты) и пушьте их в тот же реестр, где хранится образ.
Контролируйте доступ через уже настроенные механизмы реестра (т.е. не вводите ещё один набор прав).

Безопасность и соответствие

Важно учитывать безопасность и целостность артефактов:

Подписывайте артефакты (например, с помощью Cosign) для обеспечения целостности и аутентичности.
Храните секреты отдельно — в ORAS должен попадать только публичный для потребителя артефакт или артефакт с приложенными подписью/сертификатом.
Настройте политики сканирования (SCA) и мониторинга для обнаружения уязвимостей в бинарниках и зависимостях.
Придерживайтесь требований соответствия, сохраняя SBOM рядом с релизом.

Замечание: реестр — точка контроля доступа. Убедитесь, что ваш процесс CI имеет минимально достаточные права для push.

Когда ORAS не подходит или ограничения

Если вам нужно хранить огромные двоичные объёмы (несколько терабайт) и реестр не оптимизирован для таких объёмов — лучше использовать специализированное хранилище (S3, Artifactory с оптимизациями, CDN).
Если ваша инфраструктура полностью оффлайн и нет возможности поднять совместимый реестр — ORAS не даст преимуществ.
Если нужно сложное управление версиями и артефактов много типов с зависимостями — вероятно, потребуется дополнительный уровень метаданных и индексирования поверх реестра.

Альтернативные подходы

Использование менеджеров пакетов (npm, Maven, PyPI) для специфичных экосистемных артефактов.
Сборка артефактного репозитория на базе S3/HTTP с собственными индексами.
Комбо: хранить крупные бинарники в S3, метаданные и SBOM — в реестре.

Модель принятия решений (Mermaid)

flowchart TD
  A[Начать: нужно ли централизованное хранилище артефактов?] --> B{Артефакты малого/среднего размера?}
  B -- Да --> C[Использовать реестр OCI + ORAS]
  B -- Нет --> D{Можно ли разделить артефакты?}
  D -- Да --> E[Мелкие в реестр, крупные в S3]
  D -- Нет --> F[Использовать специализированное хранилище]
  C --> G[Интегрировать в CI/CD и подписывать артефакты]
  E --> G
  F --> H[Рассмотреть альтернативы и миграцию]

Чеклист внедрения по ролям

Разработчик:

Создать артефакт (SBOM, бинарник, chart)
Указать content-type и media type
Добавить тесты на целостность

DevOps/Инженер релизов:

Настроить CI для автоматического push
Обеспечить доступы и роли в реестре
Настроить сканирование и подписи

Безопасность:

Внедрить подписание (Cosign/Notary)
Настроить мониторинг целостности и уведомления

Критерии приёмки

Артефакт пушится и доступен по тегу в реестре
Артефакт загружается oras pull без ошибок
Для критичных релизов присутствует подпись и SBOM
CI автоматически пушит связанные артефакты при каждом релизе

Тестовые случаи и приемка

Позитивный сценарий: push JSON-артефакта и pull на другой машине.
Отказ при отсутствии авторизации: попытка pull с неверными учётными данными должна возвращать ошибку авторизации.
Интеграция CI: при создании тега в репозитории CI должен собрать артефакты и запушить их.
Подпись: после push подпись должна верифицироваться с помощью выбранного инструмента.

Миграция и совместимость

При миграции репозиториев убедитесь, что целевой реестр поддерживает OCI Artifacts.
Экспортирация больших наборов артефактов возможна через oras pull в скриптах, затем — перенос в новый реестр.
Для унификации типов медиа заведите в организации схему именования media types и карту соответствий.

Примеры конфигураций и сниппеты

Пример CI-шага (псевдокод):

steps:
  - build: build-artifact.sh
  - generate_sbom: syft . -o spdx-json=sbom.json
  - oras_push:
      run: |
        oras login -u $DOCKER_USER -p $DOCKER_TOKEN
        oras push docker.io/$DOCKER_ORG/my-app:$TAG sbom.json:application/spdx+json --artifact-type application/vnd.spdx.document

Сниппет проверки подписи (Cosign):

cosign verify --key cosign.pub docker.io/$DOCKER_ORG/my-app:$TAG

Отладка и распространённые ошибки

Ошибка 401/403 при push/pull: проверьте ~/.docker/config.json и токены доступа.
Несоответствие digest: убедитесь, что вы не модифицируете файлы после создания артефакта и подписания.
Неподдерживаемый media type: регистрируйте media types в вашей организации или используйте общепринятые.

Важное: если реестр возвращает ошибки формата или распознавания, проверьте, реализована ли в нём поддержка OCI Artifacts и какие media types он ожидает.

Совместимость и заметки по локализации

Docker Hub, GitHub Packages, Amazon ECR, Google Artifact Registry и Azure поддерживают OCI Artifacts.
Локальные или устаревшие реестры могут не поддерживать расширенные возможности; проверьте документацию поставщика.

Часто задаваемые вопросы

Что такое media type и зачем он нужен?

Media type — это идентификатор типа содержимого, позволяющий реестру и клиентам понимать, что хранится в артефакте (чарт Helm, SBOM, бинарник и т. п.).

Требуется ли менять процессы CI/CD?

Частично: обычно достаточно добавить шаг генерации и push связанных артефактов. Механика авторизации и хостинга остаётся прежней.

Как обеспечить доверие к артефакту?

Используйте цифровые подписи (Cosign/Notary) и храните SBOM рядом с артефактом.

Резюме

ORAS делает реестры OCI универсальным местом хранения всех артефактов, связанных с релизом. Это упрощает доставку, централизует доступ и интегрируется с существующими инструментами и CI/CD. Прежде чем внедрять, оцените объём и размер артефактов, требования безопасности и совместимость реестров.

Важно: начните с пилота для одного проекта, стандартизируйте media types и автоматизируйте push в CI.

Ключевые действия на старте:

Установите ORAS CLI и протестируйте push/pull локально.
Настройте автоматический push артефактов в CI.
Внедрите подпись артефактов и хранение SBOM.

ORAS: реестр OCI как универсальное хранилище артефактов