Pushing and Pulling Images

Pushing and pulling Docker images is one of the most common tasks completed with Container Registry. Before pushing an image, you must choose a registry name, then tag the image appropriately.

This guide assumes that you have the Cloud SDK installed, which includes the gcloud command-line tool, and have set up a Docker credential helper for Container Registry. See also the Container Registry quickstart, which explains how to get up and running with the product.

For instructions on listing, tagging, and deleting images, see Managing Images.

Choosing a registry name

Before you can push a Docker image to any private registry, you need to tag the image with a registry name.

Your private registry name is a string combining your Google Cloud Platform project ID with a gcr.io hostname, your image's name, and (optionally) its tag.

The following is the list of available gcr.io hostnames:

us.gcr.io hosts your images in the United States
eu.gcr.io hosts your images in the European Union
asia.gcr.io hosts your images in Asia
gcr.io without a prefix hosts your images in the United States, but this behavior may change in a future release

Registry name format

The registry name format is:

[HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG|@DIGEST]

where:

[HOSTNAME] is the gcr.io hostname
[PROJECT-ID] is your Google Cloud Platform Console project ID
[IMAGE] is your image's name
Optionally, [:TAG|@DIGEST] is the image's tag or digest (if omitted, the default value is latest)

For example, example-image from my-project, served in the United States, has the following registry name with the tag test:

us.gcr.io/my-project/example-image:test

If you don't know your project ID, run the following command:

gcloud projects list

Domain-scoped projects

If your project is scoped to your domain, such as example.com:my-project, use:

[HOSTNAME]/example.com/my-project/[IMAGE]

Pushing images to the registry

To push a local image to Container Registry, perform the steps below:

Tag your image by running the following Docker command:
```
docker tag [SOURCE_IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
```
where:
- [SOURCE_IMAGE] is the image you are pushing to the registry, which must exist locally on the same machine where you're executing the docker command.
- [HOSTNAME] is one of the gcr.io hostnames.
- [PROJECT-ID] is the ID of your project.
- [IMAGE] is the desired image name. This name can be different from the source name.
- [:TAG] is optional. If omitted, the tag latest is automatically applied.
Configure Docker to use gcloud as a Container Registry credential helper (you are only required to do this once):
```
gcloud auth configure-docker
```

Then, push the image to Container Registry:

docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE]

Or, using a tag:

docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]

For example:

docker tag my-image gcr.io/my-project/my-image:test
docker push gcr.io/my-project/my-image

After pushing your image, you can run gcloud container images list-tags to view its tag and automatically-generated digest:

gcloud container images list-tags gcr.io/my-project/my-image

The command's output is similar to the following:

DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

Pulling images from the registry

To pull from Container Registry, configure Docker to use gcloud as a credential helper (you are only required to do this once):

gcloud auth configure-docker

Then, run the following command:

docker pull [HOSTNAME]/[PROJECT-ID]/[IMAGE]