OCI image spec: index, manifest, config и слои как Merkle DAG из дескрипторов

Четыре типа документов, связанных дескрипторами

Зачем разбираться в спеке? Потому что когда что-то ломается на уровне реестра или цепочки поставки, сообщение об ошибке всегда на языке спеки — media-типы, дескрипторы, дайджесты, — и без словаря ты отлаживаешь с одной связанной рукой. OCI Image Spec достиг v1.0 в 2017, через два года после того, как проект сформировался в 2015, чтобы вынуть Docker schema2 манифест из одного вендора в нейтральный стандарт. Он определяет четыре типа JSON-документов и один примитив, который их склеивает, — дескриптор. Дескриптор — единственный способ, которым один OCI-документ ссылается на другой, и это всего три поля:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:7f0a3c…",
  "size": 2089
}

Это весь механизм связывания. mediaType говорит, какого рода вещь на том конце, digest — это sha256, который контентно-адресует её, а size — её длина в байтах, чтобы клиент мог выделить память и проверить ещё до того, как начнёт качать. Каждая ссылка в OCI-образе — index на манифест, манифест на config, манифест на каждый слой — это дескриптор. Четыре типа документов, которые он связывает:

• Image index — application/vnd.oci.image.index.v1+json. Мультиархитектурный разворот: список дескрипторов, по одному на платформу, каждый ссылается на манифест. Примерно 1–3 КБ для горстки платформ.
• Image manifest — application/vnd.oci.image.manifest.v1+json. Рецепт одной платформы: дескриптор config и упорядоченный массив layers из дескрипторов. Обычно около 2 КБ.
• Image config — application/vnd.oci.image.config.v1+json. Тот JSON, что ты встретил в прошлом уроке: Env, Entrypoint, rootfs.diff_ids, history. Его digest — это image ID.
• Layer blobs — application/vnd.oci.image.layer.v1.tar+gzip. Gzip-tar-архивы файловой системы, основная масса байтов.

Pull разрешает тег в верхний дескриптор, качает тот документ, читает дескрипторы внутри него, качает их и рекурсивно спускается вниз, пока не получит config и каждый слой.

Почему это Merkle DAG

Поскольку каждая связь — это digest того, на что она указывает, ссылки складываются в Merkle DAG — ту же структуру, что и граф git-коммитов. Digest config вычисляется из байтов config. Манифест встраивает тот digest config плюс digest каждого слоя, поэтому собственный digest манифеста вычисляется из байтов, которые включают все эти дочерние digest. Index встраивает digest манифестов, поэтому digest index покрывает всё ниже него. Следствие — это свойство, на которое опирается вся цепочка поставки: измени любой блоб, и каждый digest над ним изменится. Переверни один байт в базовом слое — и digest того слоя изменится, что изменит манифест, который его перечисляет, что изменит index, который перечисляет манифест. Нельзя изменить содержимое где-либо в графе так, чтобы верхний digest тега не сдвинулся. Именно поэтому docker pull image@sha256:… — это жёсткая гарантия: пин верхнего digest пинит весь транзитивный набор байтов, так же как хеш git-коммита пинит целое дерево.

Война media-типов: OCI против schema2

Дескрипторы работают, лишь если оба конца согласны насчёт словаря, а в дикой природе два словаря. Оригинал Docker — это schema2: application/vnd.docker.distribution.manifest.v2+json для манифеста и application/vnd.docker.image.rootfs.diff.tar.gzip для слоёв. У OCI — семейство application/vnd.oci.image.* выше. Байты, которые несёт слой, в обоих случаях те же gzip-tar; различается лишь строка типа. Но старые реестры и старые клиенты диспетчеризуют по этой строке, поэтому образ, помеченный OCI media-типами и запушенный в реестр, который кодит только под schema2, падает с manifest unknown или ошибкой pull — не потому, что что-то повреждено, а потому, что у получателя нет обработчика под этот mediaType. Поэтому сборочный тулинг выставляет флаги формата: --output type=image,oci-mediatypes=true|false у BuildKit и --provenance=false у buildx (provenance-аттестации форсят OCI index, который некоторые реестры отвергают). Современный Docker OCI-совместим и с хранилищем образов на snapshotter containerd демон по умолчанию эмитит OCI media-типы — что и есть та перемена, которая удивила команду в начале. Когда упираешься в manifest unknown против старого реестра, первый ход — перепушить со schema2 media-типами и посмотреть, уйдёт ли ошибка.

На том же дескрипторном водопроводе едет и пятая вещь — механизм referrers / subject. Манифест может нести дескриптор subject, указывающий на манифест другого образа по digest, что прикрепляет артефакт — подпись, SBOM, provenance-аттестацию — к тому образу, не меняя его digest. Referrers API реестра позволяет спросить «что прикреплено к sha256:…?» и получить обратно дескрипторы каждой подписи и SBOM. Прикрепление по digest, поэтому оно наследует ту же доказуемость подмены: артефакт называет ровно те байты образа, за которые ручается.