README
¶
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:
- Storing artifacts, with optional references, through the artifact.manifest
- 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:
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.
Directories