Container Registry is deprecated and scheduled for shutdown. Effective May 15, 2024, Artifact Registry hosts images for the gcr.io domain in projects without previous Container Registry usage. After March 18, 2025, Container Registry will be shut down.

To get started with managing containers on Google Cloud, use Artifact Registry. If you use Container Registry, learn how to transition to Artifact Registry to manage your containers on Google Cloud.

For more information on the deprecation and shutdown, see the deprecations page and release notes.

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 IAM 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.legacyBucketWriter) 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 name for the image in Container Registry:
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 a target image name, which can be different from the image's name on your local machine. For example, the local image might be called web-image, but you want to store it in Container Registry as web-site
3. Combine the hostname, your Google Cloud console project ID, and target image name:
```
HOSTNAME/PROJECT-ID/TARGET-IMAGE
```
  Consider the following example:
  - Hostname: gcr.io
  - Google Cloud project: my-project
  - Target image name: web-site
  Combining the hostname, project, and target image name gives you the full image path to use for tagging:
  
  gcr.io/my-project/web-site
  
  If your project ID contains a colon (:), see Domain-scoped projects.
Tag the local image with name from the previous step. If you want to label this version of the image with a tag, include the tag name.
```
docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG
```
Replace the following:
- SOURCE_IMAGE is the local image name or image ID.
- HOSTNAME is the registry host you chose in step 2.
- PROJECT is the Google Cloud project ID.
- TARGET-IMAGE is the name for the image when it's stored in Container Registry.
- TAG is the tag you want to associate with this image version.
For example, this command tags the local image web-image as gcr.io/my-project/web-site in Container Registry with the tag v1.5
```
docker tag web-image gcr.io/my-project/web-site:v1.5
```
If you don't specify a tag, Docker adds the default latest tag. Since latest is a default tag, it represents the image version most recently tagged with the latest tag, and not necessarily the newest version of an image.

Docker tags your image with the image name and tag you specified in the command.

Push the tagged image to Container Registry

Verify that you have configured authentication to Container Registry.
Push the tagged image to Container Registry:

Run the following command to push an image with a specific tag:
```
docker push HOSTNAME/PROJECT-ID/IMAGE:TAG
```
If you omit :TAG, Docker pushes the version of the image tagged with latest.

For example, this command pushes the image gcr.io/my-project/web-site with with the tag v1.5:
```
docker push gcr.io/my-project/web-site:v1.5
```

When you push an image to a registry host that does not exist yet in your project, Container Registry creates a storage bucket for the registry host.

To view the image you pushed:

Go to the Google 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 Google 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.