wwwsylvia / artifacts-spec

ORAS Artifacts Specification

OCI Artifacts generalized the ability to persist artifacts within an OCI Distribution conformant registry enabling a wide range of individual artifacts. The majority of cloud registries, products and projects support pushing and pulling OCI Artifacts to a registry, enabling users to benefit from the performance, security, reliability capabilities. These common registry capabilities avoid the need to run, manage or care for Yet Another Storage Service (YASS).

A focus on storing secure supply chain artifacts, including Software Bill of Materials (SBoM), security scan results and signatures has prompted a new set of capabilities. Building on OCI Artifacts, the ORAS artifact.manifest generalizes the use cases of OCI image manifest by removing constraints defined on the image.manifest, while adding support for references between artifacts.

The ORAS Artifacts specification includes:

1. Storing artifacts, with optional references, through the artifact.manifest
2. Discovering referenced artifacts, through the referrers API

Table of Contents:

• Overview
• Comparing the ORAS Artifact Manifest and OCI Image Manifest
• How does ORAS Artifacts relate to OCI Artifacts?
• Scenarios
• Artifact Manifest Spec
• Referrers API
• Project status
• Community
• Code of Conduct

Overview

As the distribution of secure supply chain artifacts becomes a primary focus, users and registry operators are looking to extend the capabilities for storing artifacts including artifact signing, SBoMs and security scan results. To provide these capabilities, the ORAS Artifacts Spec will provide a specification for storing and discovering a broad range of types, including the ability to store references between types, enabling a graph of objects that registry operators and client can logically reason about.

The ORAS Artifacts specs will build upon the OCI distribution-spec assuring registry operators can opt-into the behavior, ensuring users and clients have well understood expectations for the lifecycle management capabilities for storing artifacts and the references between artifacts.

The approach to reference types is based on a new artifact.manifest, enabling registries and clients to opt-into the behavior, with clear and consistent expectations.

Quick Start

Getting Started with ORAS Artifacts and Supply Chain Reference Types

Comparing the ORAS Artifact Manifest and OCI Image Manifest

OCI Artifacts defines how to implement stand-alone artifacts that can fit within the constraints of the image-spec. ORAS Artifacts uses the manifest.config.mediaType to identify the artifact is something other than a container image. While this validated the ability to generalize the Content Addressable Storage (CAS) capabilities of OCI Distribution, a new set of artifacts require additional capabilities that aren't constrained to the image-spec. ORAS Artifacts provide a more generic means to store a wider range of artifact types, including references between artifacts.

The addition of a new manifest does not change, nor impact the image.manifest. By defining the artifact.manifest and the referrers/ api, registries and clients opt-into new capabilities, without breaking existing registry and client behavior.

The high-level differences between the oci.image.manifest and the oras.artifact.manifest:

OCI Image Manifest	ORAS Artifacts Manifest
config REQUIRED	config OPTIONAL as it's just another entry in the blobs collection with a config mediaType
layers REQUIRED	blobs are OPTIONAL, which were renamed from layers to reflect general usage
layers ORDINAL	blobs are defined by the specific artifact spec. For example, Helm utilizes two independent, non-ordinal blobs, while other artifact types like container images may require blobs to be ordinal
manifest.config.mediaType used to uniquely identify artifact types.	manifest.artifactType added to lift the workaround for using manifest.config.mediaType on a REQUIRED, but not always used config property. Decoupling config.mediaType from artifactType enables artifacts to OPTIONALLY share config schemas.
	subject OPTIONAL, enabling an artifact to extend another artifact (SBOM, Signatures, Nydus, Scan Results)
	/referrers api for discovering referenced artifacts, with the ability to filter by artifactType
	Lifecycle management defined, starting to provide standard expectations for how users can manage their content

For more info, see:

• Proposal: Decoupling Registries from Specific Artifact Specs #91
• Discussion of a new manifest #41

Project Status

The ORAS artifacts-spec has released rc1

ORAS Artifacts are supported by:

• Azure ACR
• CNCF Distribution Work in progress reference implementation, (fork from distribution)
• ORAS CLI for pushing, discovering, pulling OCI & ORAS Artifacts
• Notary - notation CLI, enabling signing of all OCI Artifacts
• The ZOT Project

ORAS and OCI

ORAS Artifacts are additive capabilities to the OCI distribution-spec.

Community

To engage with the project:

• Slack: #oras-artifacts-spec
  • To participate in this channel, join CNCF slack at https://slack.cncf.io/
• Weekly meetings can be found on the CNCF Calendar: CNCF oras-artifacts-spec

Code of Conduct

This project has adopted the CNCF Code of Conduct.