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.
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.
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 Union1 |
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, these commands pull the
busybox
image from Docker Hub, tag it with the a path to thegcr.io
registry in the projectmy-project
, and then push the image.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 Object Admin (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 Object Admin role can push images togcr.io
but cannot push images toasia.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:
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 futureus.gcr.io
hosts images in data centers in the United States, in a separate storage bucket from images hosted bygcr.io
eu.gcr.io
hosts the images in the European Unionasia.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.
Choose an image name, which can be different from the image's name on your local machine.
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
Pushing 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
or
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
, orasia.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.