Docker Hub is the best known registry for distributing and sharing container images. Docker Hub and other OCI-compliant registries can now do more than just container images, though. The ORAS (OCI Registry As Storage) project transforms 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 been standardized by the OCI. Docker is now one implementation of the OCI specifications, alongside other compatible container systems such as Podman and Kubernetes.
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 docker pull
and docker push
. While these have previously only worked with container images, now you can use the same mechanism to distribute your app’s other components.
Why Generic Artifacts Matter
This functionality is being developed under the ORAS banner. 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:
- Helm charts
- Precompiled binaries and installer packages
- SBOMs
- Recommended security policy configurations, such as OPA rules
- Release signatures, certificates, and metadata
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 oras pull example.com/my-app/sbom:v1.1.0
, 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 docker push my-image:latest
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 as Helm 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 as docker 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 version from the project’s GitHub releases page. Only macOS and Linux systems are currently 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/local/bin/ $ rm -rf oras_0.16.0_*.tar.gz oras-install/
Check your binary’s working by running the oras version
command:
$ oras version 0.16.0
Now you’re ready to start using ORAS.
Using ORAS With Docker Hub
ORAS is only compatible with registries that have implemented support for 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 the CNCF distribution.
We’ll use Docker Hub for this article as it’s the most popular registry solution. It added full support for OCI Artifacts in November 2022.
Login to Your Registry
ORAS automatically reuses registry credentials you’ve previously added to your ~/.docker/config.json
file. If you need to login to Docker Hub, you can run either docker login
or oras login
to do so:
$ oras login -u username -p password_or_personal_access_token $ 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 can upload anything that’ll be useful to your users or developers.
$ echo '{"app": "oras-demo", "version": "1.1.0"}' > artifact.json
Now you’re ready to push your file with the ORAS CLI.
Push Your Artifact
Run the following command to push your artifact, after replacing <username>
with your actual Docker Hub username:
$ oras push docker.io/<username>/oras-demo:1.1.0 \ 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 first argument defines the registry to push to and the tag to assign to the artifact. This is similar to pushing a container image tag.
- Unlike the
docker
CLI, ORAS requires you to specify the registry URL (docker.io
for Docker Hub). ORAS is a generic tool that can’t make assumptions about what or where you’re pushing. - The second argument specifies the path to the file you’re uploading in
filename:content-type
format. As the example file is JSON, theapplication/json
content type is selected. - The third argument specifies the ORAS artifact type (media type) to assign to your artifact. You should use a standard media type if you’re uploading a registered kind of artifact, like a Helm chart, but the “unknown” default is appropriate for this demo.
The upload progress is shown in your terminal, similarly to a regular docker push
. Try running the oras repo tags
command to confirm the push completed:
$ oras repo tags docker.io/<username>/oras-demo 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 see Contains: Other
to denote that the repository holds a generic artifact. Container image repositories are labelled as Contains: 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 can 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 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 files in the artifact will be deposited into your working directory:
$ ls 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 registry using its helm push
command, for example. This avoids having to manually export the chart so you can push it with oras 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.