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

Docker Hub is the very best recognized registry for distributing and sharing container photos. Docker Hub and different OCI-compliant registries can now do extra than simply container photos, although. The ORAS (OCI Registry As Storage) venture transforms registries into generic artifact shops, able to publishing any asset related to your software.

On this article, you’ll study what ORAS is, the challenges it solves, and 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 suitable container techniques corresponding to Podman and Kubernetes.

Docker Hub is an OCI Registry-compatible platform for delivering container photos. OCI container instruments can eat content material from Docker Hub and different registries by way of instructions like docker pull and docker push. Whereas these have beforehand solely labored with container photos, now you should utilize 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} consumer would possibly have to efficiently run your software program. This may very well be a container picture, or one other kind of asset that is smart on your venture:

  • Helm charts
  • Precompiled binaries and installer packages
  • SBOMs
  • Advisable safety coverage configurations, corresponding to OPA guidelines
  • Launch signatures, certificates, and metadata

These very important property can usually be exhausting for customers to search out. They are typically scattered throughout completely different supply management platforms, bundle managers, and direct web site downloads. With ORAS, you’ll be able to deposit the whole lot into one centralized registry, then let customers retrieve content material utilizing a single set of instruments and credentials. Viewing the SBOM on your v1.1.0 launch is so simple as oras pull, for instance.

Is ORAS a Breaking Change for Container Photographs?

ORAS doesn’t break any present container registry options. You’ll be able to preserve working instructions corresponding to docker push my-image:newest to maneuver your photos round.

There are vital 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 varieties” inside ORAS.

Standard group initiatives can register their very own media varieties to establish generally used artifact classifications, corresponding to Helm charts. This enables registry suppliers to show related details about the artifacts you’ve saved.

The container picture media kind is robotically used while you push from present instruments corresponding to docker push. A default “unknown” kind is utilized while you add instantly from the ORAS CLI, until you specify a registered kind.

Putting in the ORAS CLI

You want the ORAS CLI to push and pull artifacts with arbitrary varieties. You’ll be able to obtain the newest model from the venture’s GitHub releases web page. Solely macOS and Linux techniques 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 working the oras model command:

$ oras model

Now you’re prepared to begin utilizing ORAS.

Utilizing ORAS With Docker Hub

ORAS is barely suitable with registries which have applied help for the OCI Artifacts specification. This record now options most main distributors, together with Amazon ECR, Azure, Google, and GitHub, in addition to self-hosted cases 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 have to login to Docker Hub, you’ll be able to 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 form of asset you push. This instance is a contrived JSON file that describes the venture’s standing, however you’ll be able to 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> along with your precise Docker Hub username:

$ oras push<username>/oras-demo:1.1.0 
    --artifact-type software/vnd.unknown.config.v1+json
Importing 7ac68d8d2a12 artifact.json
Uploaded  7ac68d8d2a12 artifact.json
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

There are a couple 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 ( for Docker Hub). ORAS is a generic instrument 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 software/json content material kind is chosen.
  • The third argument specifies the ORAS artifact kind (media kind) to assign to your artifact. It’s best to use a typical media kind in the event you’re importing a registered form of artifact, like a Helm chart, however the “unknown” default is acceptable for this demo.

The add progress is proven in your terminal, equally to an everyday docker push. Strive working the oras repo tags command to verify the push accomplished:

$ oras repo tags<username>/oras-demo

Managing Artifacts In Docker Hub’s UI

Your artifact may also seem on the Docker Hub web site. Within the Repositories record, you’ll see Comprises: Different to indicate that the repository holds a generic artifact. Container picture repositories are labelled as Comprises: Picture.

image showing a generic artifact in Docker Hub

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

image showing a generic artifact in Docker Hub

Pulling Your Artifact

Together with your artifact out there 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<username>/oras-demo:1.1.0
Downloading 7ac68d8d2a12 artifact.json
Downloaded  7ac68d8d2a12 artifact.json
Digest: sha256:41abfed0ab43a24933c5eafe3c363418264a59eee527821a39fe7c0abf25570b

The information within the artifact will probably be deposited into your working listing:

$ ls

$ cat artifact.json
{"app": "demo-oras", "model": "1.1.0"}

You’ve efficiently used ORAS to distribute your software’s artifacts, utilizing the present infrastructure out there out of your container registry supplier.


ORAS transforms container picture registries into generic distribution platforms. You’ll be able to push any artifact related to your software and customers can retrieve it utilizing one constant mechanism. This avoids having to keep up, publish to, and swap between a number of supply channels.

ORAS help is being added to widespread ecosystem instruments too. Helm permits 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’ll be able to push it with oras push. It additionally handles setting the proper ORAS media kind for you. You’ll be able to count on extra instruments to begin integrating ORAS, permitting you to push every kind of content material straight to your centralized registry.