Working with Oracle Cloud Infrastructure Registry

December 15, 2020 | 7 minute read
Prasenjit Sarkar
Senior Principal Product Manager
Text Size 100%:


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 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, 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
  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>, where region-key corresponds to the key for the Registry region that you’re using. For example, docker login 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/ 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

  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

  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

For example:

docker pull

  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

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.




Oracle Cloud Infrastructure provides Enterprise features for developers to build modern cloud applications. Try the Oracle Cloud Free Tier with 300$ credits for a 30 Day Free Trial. Free Tier also includes a number of “Always Free” services that are available for an unlimited period of time even after your free credits expire.

Prasenjit Sarkar

Senior Principal Product Manager

Prasenjit Sarkar is a Senior Principal Product Manager & Cloud Native App/Dev Lead at Oracle for their Cloud Native Services on Oracle Cloud Infrastructure with the primary focus on Cloud Native Applications and Micro Services. His primary focus is driving Oracle’s Cloud Computing business with Startups & Key Enterprise customers; helping to shape and deliver on a strategy to build broad use of Oracle’s Cloud Native Services. He is also responsible for developing public/private cloud integration strategies, customer’s Cloud Computing architecture vision, future state architectures, and implementable architecture roadmaps in the context of the Cloud Native Services that Oracle offers.

He has 12 Granted Patent in US PTO and authored numerous research articles. 

He is also an author of Virtualization blog and also authored six industry-leading books on Virtualization, SDN, Physical Compute etc.

Previous Post

Podcast #388: Combatting COVID-19 with Oracle APEX and Cloud (OCI)

Javed Mohammed | 2 min read

Next Post

Launching Your Own Free Private VPN In The Oracle Cloud

Todd Sharp | 12 min read