Container Registry Concepts

Container Registry is an Open Container Initiative-compliant registry. As a result, you can store any artifacts that conform to Open Container Initiative specifications, such as Docker images, manifest lists (sometimes known as multi-architecture images), and Helm charts. The instructions in this documentation assume you are storing and retrieving Docker container images using the Docker CLI. Docker container images are commonly referred to as Docker images, or simply as images.

A Docker image is a read-only template with instructions for creating a Docker container. A Docker image holds the application that you want Docker to run as a container, along with any dependencies. To create a Docker image, you first create a Dockerfile to describe that application. You then build the Docker image from the Dockerfile. Having created a Docker image, you store it in a Docker registry such as Container Registry.

An image can be referenced by its image path and a version identifier, also called an image tag.

When the top-level capability is disabled, an image in repository project01/acme-web-app with tag 4.6.3 can be referenced as project01/acme-web-app:4.6.3.

When the top-level capability is enabled on repository app, images can be stored at the repository's root path or at child paths beneath it:

• An image at the root path of repository app, with tag v1, can be referenced as app:v1.

• An image at the child path backend beneath repository app, with tag v1, can be referenced as app/backend:v1.

• An image at the child path frontend beneath repository app, with tag v1, can be referenced as app/frontend:v1.

All these images belong to repository app. The child paths do not represent separate repository resources.

Tags are scoped to each image path. For example, app/backend:latest and app/frontend:latest can reference different images.

For more information about how images are grouped into repository resources, see Repositories.

A Docker image can also be uniquely identified by its image digest, which is a hash created from the image’s content and metadata. Unlike a version identifier, which can point to different images over time, the digest always refers to the exact same image and ensures consistent deployments.

A repository is a named collection of container images in Container Registry. Container Registry supports two repository types:

• Standard: Stores images pushed by clients. Standard repositories can be private or public. Any user with internet access and knowledge of the appropriate image URL can pull images from a public repository.

• Pull-through cache: Retrieves and caches requested images from a configured path in a supported upstream registry. Pull-through cache repositories are private and do not accept client image pushes.

The top-level capability can be enabled when creating either repository type.

When the top-level capability is disabled, each complete repository name identifies a separate repository resource, even when names share a prefix. For example, project01/acme-web-app and project01/my-test-app are separate repositories. Their shared project01/ prefix does not make them part of one repository.

When the top-level capability is enabled on repository app, that repository can contain images at its root path and at child paths beneath it. For example:

• app:v1 belongs to repository app and identifies an image at its root path.

• app/backend:v1 belongs to repository app and identifies an image at the child path backend.

• app/frontend:v1 belongs to repository app and identifies an image at the child path frontend.

These image paths belong to the same repository resource. You do not create separate repositories named app/backend or app/frontend.

When the top-level capability is enabled, the repository name must contain a single path segment and cannot contain a slash (/). Within the selected regional registry, the repository name and the prefix formed by that name followed by / are reserved across all compartments in the tenancy namespace.

For example:

• After creating repository app with the top-level capability enabled, you cannot create a separate repository named app/backend within the same tenancy namespace and region, regardless of compartment.

• If a repository named app or app/backend already exists, you cannot create a new repository named app with the top-level capability enabled. Creating a repository does not convert or adopt existing repositories.

• Names such as app2 and application do not conflict with app because they do not use the reserved name or the app/ prefix.

Repository-level permissions, visibility, and settings apply to the repository and all images it owns. For repository app with the top-level capability enabled, the same repository-level rules apply to images at app, app/backend, and app/frontend. Child image paths cannot have independent repository-level permissions, visibility, or settings.

You choose whether to enable the top-level capability when creating the repository. You cannot enable or disable it after the repository has been created.

A pull-through cache repository is private. Clients can pull images from it but cannot push images to it. When a client pulls an image that is not already cached in the repository's region, Container Registry retrieves the image from the configured upstream registry using the upstream credentials configured for the repository. Container Registry streams the image to the client while caching it in the repository's region for subsequent pulls.

For pulls by image tag, Container Registry checks the upstream registry when tag refresh is due and updates the cached tag if it has changed. Refresh checks are triggered by requests; Container Registry does not refresh tags in the background. See Tag and Digest Behavior for refresh intervals and failure handling.

Authorized users can perform supported management operations, including updating upstream credentials, deleting cached images, and creating signatures for locally cached images. Deleting a cached image does not delete the image from the upstream registry. Signatures created for cached images are stored locally and are not added to the upstream registry.

A repository exists within a particular tenancy, region, and compartment. When referring to the tenancy that owns a repository, you specify the tenancy's namespace. The tenancy namespace is an auto-generated random string of alphanumeric characters. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp. Note that for some older tenancies, the namespace string might be the same as the tenancy name in all lower-case letters (for example, acme-dev). To find out the tenancy namespace of the current tenancy, open the Profile menu and select Tenancy.

You must belong to the tenancy's Administrators group or have been granted the REPOSITORY_MANAGE permission to:

• create a new public repository
• change an existing repository into a public repository
• change an existing public repository into a private repository

Access to a private repository is controlled by IAM policies. Users can perform the supported operations for which they are currently authorized. Use IAM policies to grant other users the required access to the repository.

For a standard repository, you'll usually create an empty repository in a compartment and give the repository a name before pushing any images (for example, project01/acme-web-app). If you belong to the tenancy's Administrators group or have been granted the REPOSITORY_MANAGE permission, you can also specify whether the repository is to be private or public (see Policies to Control Repository Access). Having created the repository, images you subsequently push to Container Registry that include the repository name are pushed to that repository.

For example, for convenience you might want to group together multiple versions of an image in the acme-dev tenancy in the Ashburn region into the repository called project01/acme-web-app. First, you create the project01/acme-web-app repository. Then, you include the name of the repository when you push the image, in the format <registry-domain>/<tenancy-namespace>/<repo-name>:<version>. For example, ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project01/acme-web-app:4.6.3.

Note that creating an empty repository in advance of pushing an image is almost certainly going to be your normal workflow. And if you're only authorized to manage repositories in compartments and not in the tenancy's root compartment, you'll always have to create a repository before pushing an image. However, if you're in the unusual position of mostly intending to push images to the root compartment, creating an empty repository in advance is not strictly necessary. For more information, see Creating a Repository.

When working with repositories in Container Registry, you'll find it helpful to have a clear understanding of the following terms and how they relate to each other.

repository path

A repository path (sometimes referred to as <repo-path> in this documentation) is the fully-qualified path to a repository in Container Registry. A repository path has the format <registry-domain>/<tenancy-namespace>/<repo-name>.

For example:

• ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project01/acme-web-app
• iad.ocir.io/ansh81vru1zp/project01/acme-web-app
• us-phoenix-1.ocir.io/cbujx0t3wa3r/my-hello-app

registry domain

A Container Registry registry domain includes a Container Registry region key or region identifier. A Container Registry registry domain has one of the following formats:

• (recommended) ocir.<region-identifier>.oci.oraclecloud.com
• <region-key>.ocir.io (OC1 realms only)
• <region-identifier>.ocir.io (OC1 realms only)

For example:

• ocir.us-ashburn-1.oci.oraclecloud.com
• iad.ocir.io
• us-phoenix-1.ocir.io

For the list of region identifiers and region keys, see Availability by Region.

region identifier

A region identifier (sometimes referred to as <region-identifier> in this documentation) identifies the Container Registry region you're using.

For example:

• us-ashburn-1
• us-phoenix-1

For the list of region identifiers, see Availability by Region.

region key

A region key (sometimes referred to as <region-key> in this documentation) identifies the Container Registry region you're using.

For example:

• iad
• phx

For the list of region keys, see Availability by Region.

tenancy namespace

A tenancy namespace (sometimes referred to as <tenancy-namespace> in this documentation) is an auto-generated, random, and immutable string of alphanumeric characters. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp.

Note that for some older tenancies, the namespace string might be the same as the tenancy name in all lower-case letters (for example, acme-dev). To find out the tenancy namespace of the current tenancy, open the Profile menu and select Tenancy. The tenancy namespace is shown in the Object storage namespace field.

repository name

A repository name (sometimes referred to as <repo-name> in this documentation) is the name that identifies a repository in Container Registry. Repository names are unique across compartments within a tenancy's regional registry. A name can contain slash characters when the top-level capability is disabled. When the top-level capability is enabled, the name must contain a single path segment.

For example:

• project01/acme-web-app
• project01/my-test-app
• my-hello-app
• project01/acme-web-app/component1
• project01/acme-web-app/component2
• project01/acme-web-app/component1/subcomponent1

When the top-level capability is disabled, a repository name can include slash characters (/), and each complete name identifies a separate repository. For example, project01/acme-web-app and project01/my-test-app are separate repositories. Their shared project01/ prefix does not group them into one repository.

When the top-level capability is enabled on repository app, images can be stored at its root path or at child paths beneath it. An image with tag v1 at the root is referenced as app:v1. Images with the same tag at child paths backend and frontend are referenced as app/backend:v1 and app/frontend:v1. All three images belong to repository app; backend and frontend are child image paths, not separate repositories.

top-level capability

The top-level capability allows a standard or pull-through cache repository to contain images at its root path and at child paths beneath its name.

For repository app with the top-level capability enabled, app:v1 references an image at the root; app/backend:v1 and app/frontend:v1 reference images at child paths. All belong to repository app and share its repository-level permissions, visibility, and settings. Child paths are not separate repositories.

When the top-level capability is enabled, the repository name must contain a single path segment without a slash (/). Its name and corresponding prefix, such as app and app/, are reserved within the same tenancy namespace and region, regardless of compartment.

The capability is disabled by default. You can enable it only when creating the repository and cannot change the setting afterward.

repository type

The repository type determines how images are added to the repository:

• Standard: Stores images pushed by clients. Standard repositories can be private or public.

• Pull-through cache: Retrieves images from a configured upstream registry when clients pull them and caches those images in the repository's region. Pull-through cache repositories are private and do not accept client image pushes.

upstream registry

The upstream registry is the source registry that Container Registry contacts to retrieve images for a pull-through cache repository or check cached tags for updates.

Supported upstream registries are Container Registry endpoints in a different OCI region within the same OCI realm as the pull-through cache repository.

The Upstream URL configured for the pull-through cache repository identifies the source registry and the path within that registry:

• When the top-level capability is disabled, the URL identifies one exact upstream image path.

• When the top-level capability is enabled, the URL identifies an upstream path prefix. Container Registry appends the requested child path to that prefix to locate the upstream image.

registry identifier

A registry identifier includes a Container Registry registry domain and a tenancy namespace, in the format <registry-domain>/<tenancy-namespace>

For example:

• ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp
• iad.ocir.io/ansh81vru1zp
• us-phoenix-1.ocir.io/cbujx0t3wa3r

image path

A fully qualified Container Registry image reference includes the registry domain, tenancy namespace, and image path. You can select an image using a tag (:v1) or a digest (@sha256:<digest>).

When the top-level capability is disabled, the image path is the repository name. When the top-level capability is enabled, it can be the repository name followed by child segments, such as app/backend.

For example:

• ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project01/acme-web-app:v2.0.test
• iad.ocir.io/ansh81vru1zp/project01/acme-web-app:v2.0.test
• us-phoenix-1.ocir.io/cbujx0t3wa3r/my-hello-app:latest
• ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/app/backend:v1
• ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/app/backend@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

image URI

In OCI image-management APIs, an image URI includes the tenancy namespace, image path, and a tag or digest. It does not include the registry domain.

Image at the repository root

• By tag: <tenancy-namespace>/<repo-name>:<version>

• By digest: <tenancy-namespace>/<repo-name>@sha256:<digest>

Image at a child image path

When the top-level capability is enabled, include the child image path after the repository name:

• By tag: <tenancy-namespace>/<repo-name>/<child-path>:<version>

• By digest: <tenancy-namespace>/<repo-name>/<child-path>@sha256:<digest>

<child-path> is the path beneath the repository name, such as backend or backend/api. <digest> is the 64-character hexadecimal SHA-256 digest value.

For example, for repository app with the top-level capability enabled:

• Root image, by tag: ansh81vru1zp/app:v1

• Child image, by tag: ansh81vru1zp/app/backend:v1

• Child image, by digest: ansh81vru1zp/app/backend@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The namespace and digest in these examples are illustrative. Replace them with the values for the image.

version identifier

A version identifier (sometimes referred to as <version> in this documentation) is a string used to refer to a particular image version in a known repository. For example:

• 4.6.3
• 4.6.4
• v2.0.test

image name

The term 'image name' is sometimes used as a short-hand way to refer to a particular image in a particular repository.

When the top-level capability is disabled, an image name has the structure <repo-name>:<version>. For example:

• project01/acme-web-app:4.6.3
• project01/acme-web-app:4.6.4
• my-hello-app:latest

When the top-level capability is enabled, an image name can identify an image at the repository's root path or at a child path beneath it:

• Image at the repository root: <repo-name>:<version>

• Image at a child image path: <repo-name>/<child-path>:<version>

For example, when the top-level capability is enabled on repository app:

• app:v1 references an image with tag v1 at the repository's root path.

• app/backend:v1 references an image with tag v1 at the child path backend.

• app/frontend:v1 references an image with tag v1 at the child path frontend.

The child path can contain multiple segments, such as backend/api in app/backend/api:v1. These image names all refer to images in repository app; the child paths are not separate repositories. This naming structure applies to both standard and pull-through cache repositories with the top-level capability enabled.