Break New Ground

Working with Oracle Cloud Infrastructure Registry

Prasenjit Sarkar
Senior Principal Product Manager


Oracle Cloud Infrastructure Registry is an Oracle-managed registry that helps you simplify your development-to-production workflow. Registry makes it easy for you as a developer to store, share, and manage development artifacts like Docker images. And the highly available and scalable architecture of Oracle Cloud Infrastructure (OCI) ensures that you can reliably deploy your applications. You don’t have to worry about operational issues or scaling the underlying infrastructure.

You can use Registry as a private Docker registry for internal use, pushing and pulling Docker images to and from Registry by using the Docker V2 API and the standard Docker CLI. You can also use Registry as a public Docker registry, which lets any user who has internet access and the appropriate URL pull images from public repositories in Registry.

Registry supports private access from other OCI resources in a virtual cloud network (VCN) in the same region through a service gateway. Setting up and using a service gateway on a VCN lets resources (such as worker nodes in clusters managed by Container Engine for Kubernetes) access OCI services such as Registry without exposing them to the public internet. No internet gateway is required, and resources can be in a private subnet and use only private IP addresses.

The following diagram shows a logical representation of Registry.


Figure 1: Logical diagram of Registry


Prerequisites for OCIR

To use Oracle Cloud Infrastructure Registry, you must be part of the admin group or part of a group to which a policy grants the appropriate permissions. Let’s look at the policies, using some example group names.

The following policy lets anyone in the acme-viewers group see a list of all the repositories (repos) in Registry that belong to the tenancy:

allow group acme-viewers to inspect repos in tenancy

The following policy lets anyone in the acme-managers group perform any operation on any repo in Registry that belongs to the tenancy (for example, pull an image, push an image, or create or delete a repo):

allow group acme-managers to manage repos in tenancy

Note: Registry repos are tenancy-level resources. Policies that control access to them must go in the root compartment (that is, the tenancy).

To push or pull an image, users must have an OCI username and auth token.


Registry repos

Oracle Cloud Infrastructure Registry repos can be private or public. Any user who has internet access and the appropriate URL can pull images from a public repo in Registry.

A repo exists within a particular region and tenancy. When you refer to the tenancy that owns a repo, you specify the tenancy’s namespace. The namespace is an auto-generated, random string of alphanumeric characters. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp.

Note: For some older tenancies, the namespace string might be the same as the tenancy name in all lowercase letters (for example, acme-dev). To find out the namespace of the current tenancy, open the Profile menu in the OCI Console and click Tenancy.


If you push an image and include the name of a repo that doesn’t exist, a new private repo is automatically created. For example, if you enter the command docker push iad.ocir.io/ansh81vru1zp/project02/acme-web-app:7.5.2 and the project02 repo doesn’t exist, a private repo named project02 is created.

If you push an image and don’t include a repo name, the image’s name is used as the name of the repo. For example, if you enter the command like docker push iad.ocir.io/ansh81vru1zp/acme-web-app:7.5.2, which doesn’t contain a repo name, the image’s name (acme-web-app) is used as the name of a private repo.

Alternatively, you can use the Console to create an empty repo. If you belong to the tenancy’s Administrators group or have been granted the REPOSITORY_MANAGE permission, you can also specify whether the repo is private or public. Any images that you then push to Registry that include that repo in the image name are pushed to that repo.


Create a repo

To create a repo in Oracle Cloud Infrastructure Registry, follow these steps:

  1. In the Console’s navigation menu, go to Developer Services and click Container Registry.

  2. Choose the region in which to create the repo.

  3. Click Create Repository.

  4. In the Create Repository dialog box, enter a name for the repo and specify whether the repo will be public or private. You can make the repo public only if you belong to the tenancy’s Administrators group or have been granted the REPOSITORY_MANAGE permission.

    • If you make the repo public, any user who has internet access and the appropriate URL can pull images from the repo.

    • If you make the repo private, you (and users who belong to the tenancy’s Administrators group) can perform any operation on the repo.

  5. Click Submit. The following image shows an example of the steps in this task.


Figure 2: Creating a repo


Push and pull images from Registry

You use the Docker CLI to push images to and pull images from Oracle Cloud Infrastructure Registry.

To push an image, you first use the docker tag command to create a copy of the local source image as a new image (the new image is just a reference to the existing source image). As a name for the new image, you specify the fully qualified path to the target location in Registry where you want to push the image, optionally including the name of a repo.


Create an auth token

First, create the auth token that you need to push a Docker image to the repo.

  1. In the top-right corner of the Console, open the Profile menu and then click User Settings.
  2. Under Resources, click Auth Tokens, and then click Generate Token.
  3. Enter a description for the auth token, and then click Generate Token.

    Figure 3: Creating an auth token
  4. Copy the auth token immediately to a secure location from where you can retrieve it later, because you won’t see the auth token again in the Console.
  5. Close the dialog box.


Build and push a Docker image

Now, let’s build a Docker image by using a sample Python Flask application and then push it to Registry. We use Oracle Cloud Infrastructure Cloud Shell to do this.

  1. In the top-right corner of the Console, click the Cloud Shell icon.
  2. Run the following command:

    git clone https://github.com/stretchcloud/flask-rate-limiter-cors-auth
  3. Go inside the cloned directory:

    cd flask-rate-limiter-cors-auth/

This directory contains a Dockerfile.

  1. Build the docker image:

    docker build -t flaskapp:latest .
  2. After the image is built, check it:

    docker images
  3. Copy the Docker image ID.
  4. Log in to Oracle Cloud Infrastructure Registry by entering docker login <region-key>.ocir.io, where region-key corresponds to the key for the Registry region that you’re using. For example, docker login iad.ocir.io. See Availability by Region.
  5. When prompted, enter your username in the format <tenancy-namespace>/<username>, where <tenancy-namespace> is the auto-generated Object Storage namespace string of your tenancy (as shown on the Tenancy Information page). For example, ansh81vru1zp/jdoe@acme.com. If your tenancy is federated with Oracle Identity Cloud Service, use the format <tenancy-namespace>/oracleidentitycloudservice/<username>.
  6. When prompted, enter the auth token that you copied earlier.
  7. Give a tag to the image that you’re going to push to Registry:

docker tag image-id target-tag

For example, you might enter:

docker tag 35255459d043 phx.ocir.io/intprasenjits/demoproject/flaskapp:latest

  1. To confirm that the Docker image has been correctly tagged, run docker images. Verify that the list of images includes an image with the tag that you specified. The following screenshot shows an example.

    Figure 4: Image tag
  2. Push the Docker image from the client machine to Registry:

docker push target-tag

For example:

docker push phx.ocir.io/intprasenjits/demoproject/flaskapp:latest

  1. From the Console navigation menu, go to Developer Services and click Container Registry.
  2. Select the image that you pushed, and click the tag. You see the image layers, the size of the image, how many times it has been pulled, and so on.

    Figure 5: Docker image layer

Pull an image

To pull the image, you use the same Docker CLI.

  1. Pull the Docker image from Registry to your client machine:

docker pull region-key.ocir.io/tenancy-namespace/repo-name/image-name:tag

For example:

docker pull phx.ocir.io/intprasenjits/demoproject/flaskapp:latest

  1. After you pull the image, verify that you can run the container and > access the application endpoint.

Run the container:

docker run -d -p 5000:5000 phx.ocir.io/intprasenjits/demoproject/flaskapp

Access the application endpoint:

curl -X GET -H "Content-type: application/json"

That’s how easy it is to use Registry to store your private container images securely and then run them anywhere you want. You can even use the same repo and image to deploy the application on top of Container Engine for Kubernetes. For that, you need to create a secret within Kubernetes by using the auth token, and go from there. To learn more about that, see the documentation.



This post gave you an overview of Oracle Cloud Infrastructure Registry, which is a free service. That means you don’t need to pay for the images that you store in Registry. This post also described how you can create a Docker container image and push and pull that image from Registry securely.



Every use case is different. The only way to know if Oracle Cloud Infrastructure is right for you is to try it. You can select either the Oracle Cloud Free Tier or a 30-day free trial, which includes US$300 in credit to get you started with a range of services, including compute, storage, and networking.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.