Pulling Images Using the Docker CLI

Find out how to pull images from Container Registry using the Docker CLI.

You use the Docker CLI to pull images from Oracle Cloud Infrastructure Registry (also known as Container Registry).

Your permissions control the images you can pull from Container Registry (see Policies to Control Repository Access). You can pull images from repositories you've created, from public repositories, and from repositories that the groups to which you belong have been granted access by identity policies. If you belong to the Administrators group, you can pull images from any repository in the tenancy.

To pull an image from a pull-through cache repository, authenticate to Container Registry and use docker pull as you would for any other private repository.

If the requested image is not cached locally, Container Registry uses the repository's configured upstream credentials to retrieve the image from the upstream registry. Container Registry streams the image to the client and caches it in the region containing the pull-through cache repository for subsequent pulls.

When you pull an image by tag, Container Registry also checks the upstream registry for changes when tag refresh is due.

Note

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 topic assume you are storing Docker images and using the Docker CLI.

To pull images from Container Registry using the Docker CLI:

If you already have an auth token, go to the next step. Otherwise:
1. In the top-right corner of the Console, open the Profile menu , and then select User settings (or My Profile or your account name) to view the details.
2. On the Tokens and keys tab, go to the Auth tokens section and select Generate token.
3. Enter a friendly description for the auth token. Avoid entering confidential information.
4. Select Generate token. The new auth token is displayed.
5. 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.
6. Close the Generate token dialog.
In a terminal window on the client machine running Docker, log in to Container Registry by entering docker login <registry-domain>, where <registry-domain> includes a region key or region identifier for the Container Registry region you're using. For example, docker login ocir.us-ashburn-1.oci.oraclecloud.com. See Availability by Region.
When prompted for a username, 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 General Information page). For example, ansh81vru1zp/jdoe@acme.com.

If your tenancy is federated with Oracle Identity Cloud Service, use the format <tenancy-namespace>/<domain-name>/<username>. For federated users, the <domain-name>/<username> is displayed in the Profile menu in the Console. For example, if the namespace string of your tenancy is ansh81vru1zp, and your tenancy is federated with Oracle Identity Cloud Service, and your username is jdoe@acme.com, then enter ansh81vru1zp/oracleidentitycloudservice/jdoe@acme.com.
When prompted for a password, enter the auth token you copied earlier.
Pull the Docker image from Container Registry to the client machine by entering:
```
docker pull <registry-domain>/<tenancy-namespace>/<repo-name>:<version>
```
where:
- <registry-domain> includes the region key or region identifier for the Container Registry region you're using. For example, ocir.us-ashburn-1.oci.oraclecloud.com. See Terminology Summary.
- <tenancy-namespace> is the auto-generated Object storage namespace string of the tenancy that owns the repository from which you want to pull the image (as shown on the Tenancy General Information page). 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). Note also that your user must have access to the tenancy.
- <repo-name> is the name of a repository from which you want to pull the image (for example, project01/acme-web-app). Note that your user must have access to the repository (see Repositories). When the top-level capability is enabled on repository app, specify app to pull an image at the repository root, or app/backend to pull an image at child path backend. Both paths belong to repository app; app/backend is not a separate repository. The same image-reference format applies to standard and pull-through cache repositories.
- <version> is the version identifier of the image that you want to pull from Container Registry (for example, v2.0.test).
For example:
```
docker pull ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project01/acme-web-app:v2.0.test
```
For a repository named app with the top-level capability enabled, you can pull images at the repository root or a child path.
Pull an image at the repository root by tag:
```
docker pull ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/app:v2.0.test
```
Pull an image at child path backend by tag:
```
docker pull ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/app/backend:v2.0.test
```
Pull an image at child path backend by digest:
```
docker pull ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/app/backend@sha256:<digest>
```
Replace <digest> with the image's actual SHA-256 digest value. A digest reference uses @sha256:<digest> instead of :<version>.
If you specify neither a tag nor a digest in the docker pull command, Docker uses the latest tag.

Confirm that the image has been pulled from Container Registry by entering docker images and verifying that the list of images on the client machine now includes the image you just pulled.

For example:


$ docker images
REPOSITORY                                                                TAG                   IMAGE ID      CREATED       SIZE
ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project01/acme-web-app v2.0.test             8e0506e14874  1 minute ago  162.6 MB
acme-web-app                                                              latest                8e0506e14874  2 hours ago   162.6 MB
acme-web-app                                                              v1.0                  7d9495d03763  2 hours ago   162.6 MB
<none>                                                                    <none>                6ebd328f833d  5 hours ago   162.6 MB
hello-world                                                               latest                80b84820d442  5 weeks ago   890 B

Oracle Cloud Infrastructure Documentation

Pulling Images Using the Docker CLI