Understanding References in the Open Container Initiative (OCI) Standard
One of the core concepts when dealing with container images or OCI artifacts is the notion of a reference. Let's dive deep into this concept, especially within the context of the Open Container Initiative (OCI) standard.
Image or Artifact References: Breaking Down the Components
An image reference is essentially the 'address' or 'identifier' you use to pull or manage a specific container image or OCI artifact.
There are primarily two contexts in which you'll encounter references:
- Interacting with a registry to pull or push images.
- Interacting with a local OCI Layout store to manage local content.
Let's take a look at the components of an reference in these 2 scenarios.
What a Reference Means in the Registry
When you pull or push an artifact or image from a registry, you need to specify the reference. This reference is a combination of three parts:
- Registry: This is akin to the home or the server where your images or artifacts are stored. Think of it as the overarching domain. Examples include Docker Hub (docker.io), GitHub Container Registry (ghcr.io), or your own private registry.
- Repository: This is a segment of the reference, after the registry where a particular
application or service's images are stored.
The repository doesn't necessarily follow a hierarchy within the registry, meaning
a/b/c/dare both valid and distinct repositories, with no implied hierarchy between them.
- Tag or Digest: This is the last part indicating the version of the image or artifact you want to pull or push.
References by Tag
- Tag: Tags are user-friendly references to specific image or artifact versions.
Common tags include
v1.0, or any other description that makes sense for versioning or identiying and resolve to a digest. These are typically human readable and easy to remember.
Tags are mutable. This means that the same tag can point to different digests over time.
References by Digest
Reference by a digest is a unique, immutable identifier for a specific image or artifact. Typically represented as a SHA256 hash of the image's content, the digest guarantees you're pulling or referencing the exact version of the image and artifact and is immutable.
The digest is the most precise way to reference an image. However, it's not very user-friendly. This is why tags are more commonly used. A tag always resolves to a digest.
References by Tag and Digest
Putting it all together, a reference includes a registry, a repository, and a tag or a digest in the context of a registry.
What a Reference Means in OCI Layout
In the OCI Layout specification, a reference can be a tag or a digest. The OCI Layout defines how image data should be stored on disk. This layout facilitates image distribution, making it easier for tools to push and pull images. The references in the OCI Layout help in uniquely identifying an image and its components.
The layout directory contains a file called
index.json that contains the references to the image's components.
index.json file contains a reference to a manifest file and it can be accessed as
v1 or the digest
For a detailed understanding, refer to the OCI Layout Specification.
How OCI Uses Image References
In the OCI standard, when a client (like docker) needs to pull an image, it uses the combined image reference to precisely identify and retrieve the right image or artifact from a registry.
However, it's worth noting that certain implementations, such as docker, provide
defaults or shortcuts. For instance, if you were to use docker to pull an image
using the reference
nginx, docker would automatically resolve this to
docker.io is the default registry and
library/nginx is the repository with a 'library' prefix for official images and
latest is the
Understanding the components of an
reference is vital when working with containers or OCI artifacts.
These references ensure that clients are addressing the desired version of the image or artifact.
Having a solid grasp of foundational concepts like image references becomes even more essential
as you start to use image and artifacts across your cloud native environments.