How to Standardize Software Delivery With OCI Artifacts, ORAS, and Docker Hub

Docker Hub is the very best identified registry for distributing and sharing container pictures. Docker Hub and different OCI-compliant registries can now do extra than simply container pictures, although. The ORAS (OCI Registry As Storage) undertaking transforms registries into generic artifact shops, able to publishing any asset related to your utility.
On this article, you’ll be taught what ORAS is, the challenges it solves, and tips on how to get began utilizing it with Docker Hub.
Docker Hub vs OCI Registries
First, let’s get one element clear: the container ecosystem is extra than simply Docker. The instruments and processes which Docker pioneered have been standardized by the OCI. Docker is now one implementation of the OCI specs, alongside different appropriate container programs resembling Podman and Kubernetes.
Docker Hub is an OCI Registry-compatible platform for delivering container pictures. OCI container instruments can eat content material from Docker Hub and different registries through instructions like docker pull and docker push. Whereas these have beforehand solely labored with container pictures, now you need to use the identical mechanism to distribute your app’s different parts.
Why Generic Artifacts Matter
This performance is being developed beneath the ORAS banner. It remodels registries as “generic artifact shops” which you’ll work together with utilizing the acquainted push/pull workflow.
An artifact is something {that a} person may must efficiently run your software program. This might be a container picture, or one other kind of asset that is sensible in your undertaking:

Helm charts
Precompiled binaries and installer packages
SBOMs
Beneficial safety coverage configurations, resembling OPA guidelines
Launch signatures, certificates, and metadata

These very important property can typically be laborious for customers to search out. They are usually scattered throughout completely different supply management platforms, package deal managers, and direct web site downloads. With ORAS, you possibly can deposit every thing into one centralized registry, then let customers retrieve content material utilizing a single set of instruments and credentials. Viewing the SBOM in your v1.1.0 launch is so simple as oras pull instance.com/my-app/sbom:v1.1.0, for instance.
Is ORAS a Breaking Change for Container Photographs?
ORAS doesn’t break any current container registry options. You possibly can maintain operating instructions resembling docker push my-image:newest to maneuver your pictures round.
There are important adjustments to content material storage behind the scenes, nonetheless. ORAS removes the historic assumption that each one registry content material is a picture. To help artifacts, registries have to trace the kind of every add that’s accomplished. Completely different sorts of artifact are termed “media sorts” inside ORAS.
Widespread group tasks can register their very own media sorts to establish generally used artifact classifications, resembling Helm charts. This permits registry suppliers to show related details about the artifacts you’ve saved.
The container picture media kind is robotically used whenever you push from current instruments resembling docker push. A default “unknown” kind is utilized whenever you add instantly from the ORAS CLI, except you specify a registered kind.
Putting in the ORAS CLI
You want the ORAS CLI to push and pull artifacts with arbitrary sorts. You possibly can obtain the most recent model from the undertaking’s GitHub releases web page. Solely macOS and Linux programs are at the moment supported.
Extract the downloaded archive, then copy the oras binary to a location that’s in your path:
$ tar -zxf oras_0.16.0_*.tar.gz -C oras-install/
$ mv oras-install/oras /usr/native/bin/
$ rm -rf oras_0.16.0_*.tar.gz oras-install/
Test your binary’s working by operating the oras model command:
$ oras model
0.16.0
Now you’re prepared to begin utilizing ORAS.
Utilizing ORAS With Docker Hub
ORAS is just appropriate with registries which have carried out help for the OCI Artifacts specification. This listing now options most main distributors, together with Amazon ECR, Azure, Google, and GitHub, in addition to self-hosted situations deployed utilizing the CNCF distribution.
We’ll use Docker Hub for this text because it’s the preferred registry answer. It added full help for OCI Artifacts in November 2022.

Login to Your Registry
ORAS robotically reuses registry credentials you’ve beforehand added to your ~/.docker/config.json file. If you might want to login to Docker Hub, you possibly can run both docker login or oras login to take action:
$ oras login -u username -p password_or_personal_access_token

$ docker login -u username -p password_or_personal_access_token
Subsequent create a easy file to add to the registry. Bear in mind there’s no restrictions on the type of asset you push. This instance is a contrived JSON file that describes the undertaking’s standing, however you possibly can add something that’ll be helpful to your customers or builders.
$ echo ‘{“app”: “oras-demo”, “model”: “1.1.0”}’ > artifact.json
Now you’re able to push your file with the ORAS CLI.
Push Your Artifact
Run the next command to push your artifact, after changing <username> together with your precise Docker Hub username:
$ oras push docker.io/<username>/oras-demo:1.1.0
artifact.json:utility/json
–artifact-type utility/vnd.unknown.config.v1+json
Importing 7ac68d8d2a12 artifact.json
Uploaded 7ac68d8d2a12 artifact.json
Pushed docker.io/ilmiont/oras-demo:1.1.0
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b
There are a number of noteworthy particulars on this command:

The primary argument defines the registry to push to and the tag to assign to the artifact. That is much like pushing a container picture tag.
In contrast to the docker CLI, ORAS requires you to specify the registry URL (docker.io for Docker Hub). ORAS is a generic device that may’t make assumptions about what or the place you’re pushing.
The second argument specifies the trail to the file you’re importing in filename:content-type format. As the instance file is JSON, the appliance/json content material kind is chosen.
The third argument specifies the ORAS artifact kind (media kind) to assign to your artifact. You need to use an ordinary media kind if you happen to’re importing a registered type of artifact, like a Helm chart, however the “unknown” default is suitable for this demo.

The add progress is proven in your terminal, equally to an everyday docker push. Attempt operating the oras repo tags command to verify the push accomplished:
$ oras repo tags docker.io/<username>/oras-demo
1.1.0
Managing Artifacts In Docker Hub’s UI
Your artifact will even seem on the Docker Hub web site. Within the Repositories listing, you’ll see Comprises: Different to indicate that the repository holds a generic artifact. Container picture repositories are labelled as Comprises: Picture.

Choose the repository to view its particulars, add an outline, and see all of the obtainable tags. It’s much like working with container pictures.

Pulling Your Artifact
Along with your artifact obtainable within the registry, now you can swap to a different machine and repeat the steps to put in the ORAS CLI and login to your Docker Hub account. When you’ve authenticated, use the oras pull command to retrieve your artifact:
$ oras pull docker.io/<username>/oras-demo:1.1.0
Downloading 7ac68d8d2a12 artifact.json
Downloaded 7ac68d8d2a12 artifact.json
Pulled docker.io/ilmiont/oras-demo:1.1.0
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b
The information within the artifact can be deposited into your working listing:
$ ls
artifact.json

$ cat artifact.json
{“app”: “demo-oras”, “model”: “1.1.0”}
You’ve efficiently used ORAS to distribute your utility’s artifacts, utilizing the prevailing infrastructure obtainable out of your container registry supplier.
Abstract
ORAS transforms container picture registries into generic distribution platforms. You possibly can push any artifact related to your utility and customers can retrieve it utilizing one constant mechanism. This avoids having to take care of, publish to, and swap between a number of supply channels.
ORAS help is being added to widespread ecosystem instruments too. Helm enables you to instantly push charts to an ORAS registry utilizing its helm push command, for instance. This avoids having to manually export the chart so you possibly can push it with oras push. It additionally handles setting the right ORAS media kind for you. You possibly can anticipate extra instruments to begin integrating ORAS, permitting you to push every kind of content material straight to your centralized registry.