Distributing OCI Layouts
The directory structure for OCI content-addressable blobs and location-addressable references (refs) is called the OCI Image Layout. An OCI Image needs to include:
blobsdirectory: Each hash algorithm's directory and its children, which make up the object names in the blobs subdirectories, will hold the real content.
oci-layoutfile: This JSON object indicates the base of an Open Container Image Layout and provides information about the current image-layout version.
index.jsonfile: The image index is a multi-descriptor entry point.
Creating an OCI Image
Step 1: Writing in the Dockerfile
Put the following commands in the
Dockerfile in order to run an image of Alpine Linux.
CMD echo 'hello world!'
Our image is based on alpine and runs the command
echo hello world!.
Step 2: Building the image using docker
docker buildx create —use
This command is used to create a new instance of a builder with a single node based on the current configuration.
docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1
[+] Building 7.0s (7/7) FINISHED docker-container:hungry_wilson
=> [internal] booting buildkit 3.0s
=> => pulling image moby/buildkit:buildx-stable-1 2.5s
=> => creating container buildx_buildkit_hungry_wilson0 0.5s
=> => exporting manifest sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd17 0.0s
=> => exporting config sha256:5e9872dc690060c52e4ea6e9357aaebb9d9187b44a 0.0s
=> => sending tarball 0.0s
This command has multiple parts to break down:
build is needed to build the OCI Image based on the Dockerfile we provide.
hello-world:v1 is the name and tag associated with the image built.
|file or -f||Name of the Dockerfile (default: PATH/Dockerfile)|
|output or -o||Output destination (format: type=local,dest=path)|
Step 3: View the OCI Image
If you would like to view the image, you will need to extract the
.tar file first.
tar -xf ./hello-world.tar -C hello-world
Push the OCI Image to a Repository
You may use
oras copy to push the OCI Image from your local disk to a repository.
In the following example, we are pushing the image to a local registry like zot:
oras cp --from-oci-layout ./hello-world.tar:v1 localhost:5000/hello-artifact:v1
Copied [oci-layout] ./hello-world.tar:v1 => [registry] localhost:5000/hello-artifact:v1
Pull the OCI Image from a Repository
You can pull the OCI image using the
oras pull command.
oras pull localhost:5000/hello-artifact:v1
Downloaded empty artifact
Pulled [registry] localhost:5000/hello-artifact:v1
If you would like to access the artifact files from the OCI layout archive, you may run:
oras pull --oci-layout hello-world.tar:v1
Downloaded empty artifact
Pulled [oci-layout] hello-world.tar:v1