Distributing OCI artifacts using ORAS

To distribute OCI artifacts, we need to understand OCI registries. These registries store container images and other artifacts for easy access. Distributing OCI artifacts means pushing them to these registries so others can pull them for use.

We will be using zot registry in this guide. Zot registry is an OCI-native container registry for distributing container images and OCI artifacts. This guide uses Zot as a local registry on your computer. There is another guide for distributing artifacts with a remote registry.

In order to follow the steps given, you would be required to install the ORAS CLI. You can follow the installation guide to do so.

Install zot registry

We will be running zot using docker. However, you can refer to their installation guide to find more ways to install the registry.

Prerequisites

• Docker

docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/project-zot/zot-linux-amd64:latest

Distribution of OCI artifacts

Let's push an OCI artifact to the registry using the ORAS CLI.

Step 1: Create a sample file

echo "hello world" > artifact.txt

Step 2: Push an artifact

oras push --plain-http localhost:5000/hello-artifact:v1 \
    --artifact-type application/vnd.acme.rocket.config \
    artifact.txt:text/plain

Uploading a948904f2f0f artifact.txt
Uploaded  a948904f2f0f artifact.txt
Pushed [registry] localhost:5000/hello-artifact:v1
Digest: sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee

After pushing the artifact, it can be seen in the zot user interface at http://localhost:5000/

Step 3: Pull the artifact

Let's now pull the artifact we have pushed in the pervious step.

oras pull localhost:5000/hello-artifact:v1

Downloading a948904f2f0f artifact.txt
Downloaded  a948904f2f0f artifact.txt
Pulled [registry] localhost:5000/hello-artifact:v1
Digest: sha256:19e1b5170646a1500a1ac56bad28675ab72dc49038e69ba56eb7556ec478859f

Attach an artifact

First, let's create another sample file to attach to the previously uploaded artifact.

Step 1: Create a sample file

echo "hello world" > hi.txt

Step 2: Attach the file

You can use the command below to attach hi.txt to the artifact we pushed above:

oras attach --artifact-type doc/example localhost:5000/hello-artifact:v1 hi.txt

Exists    a948904f2f0f hi.txt
Attached to [registry] localhost:5000/hello-artifact@sha256:327db68f73d0ed53d528d927a6703c00739d7c1076e50762c3f6641b51b76fdc
Digest: sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee

Step 3: View referrers

oras discover localhost:5000/hello-artifact:v1

Discovered 1 artifact referencing v1
Digest: sha256:327db68f73d0ed53d528d927a6703c00739d7c1076e50762c3f6641b51b76fdc

Artifact Type   Digest
doc/example     sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee

Note: For settings up a registry with TLS follow these steps.

Clean up

Stop and remove the running quick start registry and the uploaded content.

docker rm $(docker stop oras-quickstart)

Conclusion

You can now successfully push OCI artifacts to your zot registry!

As OCI registries are used to securely store and share container images, they greatly help with collaboration and code sharing. They enable teams to acquire and use images and artifacts through a standardized artifact interface. This is why it is considered to play a crucial role in maintaining consistency among teams.