Skip to content

docs: update ORAS intro #518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FeynmanZhou wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: update ORAS intro #518

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
68f0f0d
update ORAS intro
FeynmanZhou Oct 24, 2025
eaa3a17
Update versioned_docs/version-1.3/index.mdx
FeynmanZhou Oct 28, 2025
955bb48
Update versioned_docs/version-1.3/index.mdx
FeynmanZhou Nov 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 39 additions & 26 deletions versioned_docs/version-1.3/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,39 +14,35 @@
Users seeking a generic registry client can benefit from the [ORAS CLI](./installation.mdx), while
developers can build their own clients on top of one of the [ORAS client libraries](./client_libraries/overview.mdx).

## What are OCI Registries?
## Use cases

The [Open Container Initiative](https://opencontainers.org/) (OCI)
defines the specifications and standards for container technologies.
This includes the API for working with container registries, known
formally as the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md).
(a.k.a. the "distribution-spec").
It is not just managing container images that ORAS can do, it can treat OCI registries as a generic artifact store. Some of the most common use cases include:

The distribution-spec was written based on an open-source registry server originally
released by the company [Docker](http://docker.com/), which lives on
GitHub at [distribution/distribution](https://github.com/distribution/distribution)
(now a [CNCF](https://www.cncf.io/) project).
### Artifact Distribution

There are now a number of other open-source and commercial distribution-spec
implementations, a list of which can be found [here](https://github.com/opencontainers/oci-conformance/tree/main/distribution-spec).
Registries that implement the distribution-spec are referred to herein as **OCI Registries**.
- Push and pull non-container artifacts (e.g., Helm charts, WASM modules, policy bundles, AI/ML models) using the same infrastructure as container images.
- Simplify artifact versioning, discovery, and retrieval across environments (dev, test, prod) using standard image tags.

## What are OCI Artifacts?
### Manage ML/AI Models as OCI Artifacts

For a long time (pretty much since the beginning), people have been using/abusing OCI Registries
to store non-container things. For example, you could upload a video to Docker Hub
by just stuffing the video file into a layer in a Docker image (don't do this).
Package and distribute machine learning models, datasets, or inference pipelines alongside your containers across local filesystem (via OCI layout) and OCI registries.

The [OCI Artifacts](https://github.com/opencontainers/artifacts) project is an attempt to
define an opinionated way to leverage OCI Registries for arbitrary artifacts without masquerading
them as container images.
### Supply Chain Security

Specifically, [OCI Image Manifests](https://github.com/opencontainers/image-spec/blob/main/manifest.md)
have a required field known as `config.mediaType`. According to the
[guidelines](https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md)
provided by OCI Artifacts, this field provides the ability to differentiate between various types of artifacts.
- Attach security metadata (e.g., SBOMs, signatures, attestations) to container images using oras attach, following the OCI Reference Types.
- Enable secure CI/CD pipelines by distributing and verifying trusted artifacts across OCI-compliant registries.

Artifacts stored in an OCI Registry using this method are referred to herein as **OCI Artifacts**.
### Backup & Restore of repositories and artifacts

- **Air-Gapped Environments**: Organizations operating in isolated or high-security environments can use `oras backup` to export artifacts from a registry to local filesystem, and use `oras restore` to import them into an internal registry with restricted access.
- **Disaster Recovery and Audit Archival**: Take periodic snapshots of repositories and store them off-site. In case of accidental deletions, outages, and long-term storage to support regulatory audits, `oras restore` can be used to quickly recover full registry content.
- **Registry Migration**: When moving from one container registry provider to another, the pair of commands enables a full repository export, preserving tags, manifests, layers, and referrers.
- **Compliance and supply chain security guarantee**: Backup and restore the images along with their supply chain artifacts, such as SBOMs, signatures, vulnerability scanning reports.
- **Repository Duplication or Promotion**: Move artifacts from dev to staging to prod registries reliably using an intermediate backup file.

### Multi-platform Image and Artifact Management

Assemble, update, distribute, and annotate multi-architecture images and artifacts across local environments and registries.

## How ORAS works

Expand All @@ -69,4 +65,21 @@

If you wish to start publishing OCI Artifacts right away, take a look at the [ORAS CLI](./installation.mdx).
Developers who wish to provide their own user experience should use one of the
[ORAS client libraries](./client_libraries/overview.mdx).
[ORAS client libraries](./client_libraries/overview.mdx).

## ORAS works with any OCI Registries

Here’s the list of OCI Registries that support ORAS:

* CNCF Distribution
* Amazon Elastic Container Registry (ECR)
* Azure Container Registry (ACR)
* Google Artifact Registry
* GitHub Packages Container Registry
* GitLab Container Registry
* JFrog Artifactory

Check failure on line 80 in versioned_docs/version-1.3/index.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'JFrog'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'JFrog'?", "location": {"path": "versioned_docs/version-1.3/index.mdx", "range": {"start": {"line": 80, "column": 3}}}, "severity": "ERROR"}
* Docker Hub
* Zot Registry
* Harbor
* Red Hat Quay
* OVHcloud Managed Private Registry (MPR)

Check failure on line 85 in versioned_docs/version-1.3/index.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'OVHcloud'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'OVHcloud'?", "location": {"path": "versioned_docs/version-1.3/index.mdx", "range": {"start": {"line": 85, "column": 3}}}, "severity": "ERROR"}
Loading