Quick Links
Docker Hub is the best known registryfor distributing and sharing container images. Docker Hub and otherOCI-compliant registriescan now do more than just container images, though. TheORAS (OCI Registry As Storage) projecttransforms registries into generic artifact stores, capable of publishing any asset relevant to your application.
In this article, you’ll learn what ORAS is, the challenges it solves, and how to get started using it with Docker Hub.
Docker Hub vs OCI Registries
First, let’s get one detail clear: the container ecosystem is more than just Docker. The tools and processes which Docker pioneered have beenstandardized by the OCI. Docker is now one implementation of the OCI specifications, alongside other compatible container systems such asPodmanandKubernetes.
Docker Hub is an OCI Registry-compatible platform for delivering container images. OCI container tools can consume content from Docker Hub and other registries via commands like
anddocker push. While these have previously only worked with container images, now you’re able to use the same mechanism to distribute your app’s other components.
Why Generic Artifacts Matter
This functionality is being developed under theORASbanner. It remodels registries as “generic artifact stores” which you can interact with using the familiar push/pull workflow.
An artifact is anything that a user might need to successfully run your software. This could be a container image, or another type of asset that makes sense for your project:
These vital assets can often be hard for users to find. They tend to be scattered across different source control platforms, package managers, and direct website downloads. With ORAS, you can deposit everything into one centralized registry, then let users retrieve content using a single set of tools and credentials. Viewing the SBOM for your v1.1.0 release is as simple as
, for example.
Is ORAS a Breaking Change for Container Images?
ORAS doesn’t break any existing container registry features. You can keep running commands such as
to move your images around.
There are significant changes to content storage behind the scenes, however. ORAS removes the historical assumption that all registry content is an image. To support artifacts, registries have to track the type of each upload that’s completed. Different kinds of artifact are termed"media types"within ORAS.
Popular community projects can register their own media types to identify commonly used artifact classifications,such asHelm charts. This allows registry providers to display relevant information about the artifacts you’ve stored.
The container image media type is automatically used when you push from existing tools such asdocker push. A default “unknown” type is applied when you upload directly from the ORAS CLI, unless you specify a registered type.
Installing the ORAS CLI
You need the ORAS CLI to push and pull artifacts with arbitrary types. You can download the latest versionfrom the project’s GitHub releases page. Only macOS and Linux systems are currently supported.
Extract the downloaded archive, then copy the
$ mv oras-install/oras /usr/local/bin/
$ rm -rf oras_0.16.0_*.tar.gz oras-install/
0.16.0
Now you’re ready to start using ORAS.
Using ORAS With Docker Hub
ORAS is only compatible with registriesthat have implemented supportfor the OCI Artifacts specification. This list now features most major vendors, including Amazon ECR, Azure, Google, and GitHub, as well as self-hosted instances deployed using theCNCF distribution.
We’ll use Docker Hub for this article as it’s the most popular registry solution. Itadded full supportfor OCI Artifacts in November 2022.
Login to Your Registry
ORASautomatically reusesregistry credentials you’ve previously added to your~/.docker/config.jsonfile. If you need to login to Docker Hub, you’re able to run eitherdocker loginororas loginto do so:
$ docker login -u username -p password_or_personal_access_token
Next create a simple file to upload to the registry. Remember there’s no restrictions on the kind of asset you push. This example is a contrived JSON file that describes the project’s status, but you’re able to upload anything that’ll be useful to your users or developers.
Now you’re ready to push your file with the ORAS CLI.
Push Your Artifact
Run the following command to push your artifact, after replacingwith your actual Docker Hub username:
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
There are a few noteworthy details in this command:
The upload progress is shown in your terminal, similarly to a regulardocker push. Try running theoras repo tagscommand to confirm the push completed:
1.1.0
Managing Artifacts In Docker Hub’s UI
Your artifact will also appear on the Docker Hub website. In the Repositories list, you’ll seeContains: Otherto denote that the repository holds a generic artifact. Container image repositories are labelled asContains: Image.
Select the repository to view its details, add a description, and see all the available tags. It’s similar to working with container images.
Pulling Your Artifact
With your artifact available in the registry, you’re able to now switch to another machine and repeat the steps to install the ORAS CLI and login to your Docker Hub account. Once you’ve authenticated, use theoras pullcommand to retrieve your artifact:
Downloading 7ac68d8d2a12 artifact.json
Downloaded 7ac68d8d2a12 artifact.json
Pulled docker.io/ilmiont/oras-demo:1.1.0
The files in the artifact will be deposited into your working directory:
artifact.json
$ cat artifact.json
{“app”: “demo-oras”, “version”: “1.1.0”}
You’ve successfully used ORAS to distribute your application’s artifacts, using the existing infrastructure available from your container registry provider.
Summary
ORAS transforms container image registries into generic distribution platforms. You can push any artifact relevant to your application and users can retrieve it using one consistent mechanism. This avoids having to maintain, publish to, and switch between multiple delivery channels.
ORAS support is being added to popular ecosystem tools too. Helm lets you directly push charts to an ORAS registryusing itshelm pushcommand, for example. This avoids having to manually export the chart so you can push it withoras push. It also handles setting the correct ORAS media type for you. You can expect more tools to start integrating ORAS, allowing you to push all kinds of content straight to your centralized registry.
