Pushing and pulling images

Pushing (uploading) and pulling (downloading) images are two of the most common Container Registry tasks. This document focuses on pushing and pulling images with Docker.

Note: Starting with GKE node version 1.19, the default node image for Linux nodes is the Container-Optimized OS with Containerd (cos_containerd) variant instead of the Container-Optimized OS with Docker (cos) variant.

For troubleshooting and logging using GKE with Containerd, use crictl. For open source Kubernetes, refer to the containerd documentation.

If you are using Cloud Build, see the Cloud Build documentation for information about building and pushing containers to Container Registry.

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

Before you begin

Make sure that you have:

Enabled Container Registry in your project.
Installed and configured Docker.

Adding a registry

You can add the following Container Registry registries to a project:

Hostname	Storage location
`gcr.io`	Stores images in data centers in the United States
`asia.gcr.io`	Stores images in data centers in Asia
`eu.gcr.io`	Stores images in data centers within member states of the European Union
`us.gcr.io`	Stores images in data centers in the United States

The first image push to a hostname triggers creation of the registry in a project and the corresponding Cloud Storage storage bucket. This initial push requires project-wide permissions to create storage buckets.

Once a registry host exists in your project, you can configure permissions on the storage bucket to control access to images in the registry.

To add a registry and configure permissions:

Verify that you have the required permissions. You must have the Storage Admin role (roles/storage.admin), or a custom role or predefined role with the same permissions.

For instructions to grant the Storage Admin role at the project level, see the Cloud Storage documentation.
Push an initial image to the host. For example, the following commands:
- Pull the busybox image from Docker Hub
- Tag the image with its target path in Container Registry, including the gcr.io registry host and the project ID my-project
- Push the image to the registry
```
docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox
```

Container Registry adds the registry to your project, creates a storage bucket for the registry, and stores the image.

You can now configure access control on the registry storage bucket to grant registry access to other users.

Pushing an image to a registry

To push any local image to Container Registry using Docker or another third-party tool, you need to first tag it with the registry name and then push the image.

The following factors might impact uploads for large images:

Upload time: Any request sent to Container Registry has a 2 hour timeout limit. If you authenticate to Container Registry using an access token, the token expires after 60 minutes. If you expect your upload time to exceed 60 minutes, use a different authentication method.
Image size: Container Registry uses Cloud Storage for each registry's underlying storage. Cloud Storage quotas and limits apply to each registry, including the 5 TB maximum size for an object in storage.; Container Registry does not support Docker chunked uploads. Some tools support uploading large images with either chunked uploads or a single monolithic upload. You must use monolithic uploads to push images to Container Registry.

Required permissions

Pushing an image requires one of the following Cloud Storage roles, or a role with the same permissions:

Pushing the first image to a registry in your project: Role: Storage Admin (roles/storage.admin) at the Google Cloud project level. The predefined Owner role includes these permissions.; The first time you push an image to a registry host in your project (such as gcr.io), Container Registry creates a storage bucket for the registry. The Storage Admin role has the necessary permissions to create the storage bucket.
Pushing images to an existing registry in your project: Role: Storage Legacy Bucket Writer (roles/storage.objectAdmin) on the registry storage bucket.; This role has permissions to push and pull images for existing registry hosts in your project. For example, if your project only contains the gcr.io registry, a user with the Storage Legacy Bucket Writer role can push images to gcr.io but cannot push images to asia.gcr.io.

For information about granting permissions to a registry, see Configuring access control.

Tag the local image with the registry name

To tag an image:

Verify that you have configured authentication to Container Registry.
Determine the registry name:
1. Choose a hostname, which specifies location where you will store the image.
  - gcr.io hosts images in data centers in the United States, but the location may change in the future
  - us.gcr.io hosts images in data centers in the United States, in a separate storage bucket from images hosted by gcr.io
  - eu.gcr.io hosts the images in the European Union
  - asia.gcr.io hosts images in data centers in Asia
  These locations correspond to the multi-regions for Cloud Storage storage buckets. When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-region. This bucket is the underlying storage for the registry. Within a project, all registries with the same hostname share one storage bucket.
  
  In the console, the images' hostname will be listed under Location.
2. Choose an image name, which can be different from the image's name on your local machine.
3. Combine the hostname, your Google Cloud Console project ID, and image name:
```
HOSTNAME/PROJECT-ID/IMAGE
```
  If your project ID contains a colon (:), see Domain-scoped projects.
Tag the local image with the registry name by using the command:
```
docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE
```
where SOURCE_IMAGE is the local image name or image ID.

This command names the image with the registry name and applies the tag latest. If you want to apply a different tag, then use the command:
```
docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE:TAG
```

Push the tagged image to Container Registry

Verify that you have configured authentication to Container Registry.
Push the tagged image to Container Registry by using the command:
```
docker push HOSTNAME/PROJECT-ID/IMAGE
```
This command pushes the image that has the tag latest. If you want to push an image that has a different tag, use the command:
```
docker push HOSTNAME/PROJECT-ID/IMAGE:TAG
```
When you push an image to a registry that does not exist yet in your project, Container Registry creates a storage bucket.

To view the image you pushed:

Go to the Cloud Console to view the registry and image.
Run gcloud container images list-tags to view the image tag and the automatically-generated digest:
```
gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE
```
The command's output is similar to the following:
```
DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..
```

Pulling images from a registry

Pulling an image requires the Storage Object Viewer for the registry storage bucket, or a role with the same permissions.

To pull from Container Registry, use the command:

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

where:

HOSTNAME is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
PROJECT-ID is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
IMAGE is the image's name in Container Registry.
TAG is the tag applied to the image. In a registry, tags are unique to an image.
IMAGE_DIGEST is the sha256 hash value of the image contents. In Cloud Console, click on the specific image to see its metadata. The digest is listed as the Image digest.

To get the pull command for a specific image:

Click on the name of an image to go to the specific registry.
In the registry, check the box next to the version of the image that you want to pull.
Click SHOW PULL COMMAND on the top of the page.
Copy the pull command, which identifies the image using either the tag or the digest.

What's next

Learn about managing your images, including adding or removing tags and deleting images.
Learn about configuring access control.
Read more about Container Registry's components and features.
If you want to run containers on Compute Engine, learn about containers on Compute Engine.