Quickstart for Container Registry

This quickstart describes how to configure Docker for Container Registry and then push and pull an image.

Google Cloud has two services for storing and managing container images:

Artifact Registry (Recommended)

A service for storing and managing artifacts in private repositories, including container images, Helm charts, and language packages. It is the recommended container image registry for Google Cloud.

Try the Docker quickstart to get familiar with Artifact Registry.

Container Registry

A private container image registry that supports Docker Image Manifest V2 and OCI image formats. It provides a subset of Artifact Registry features.

If you aren't currently using Container Registry, use Artifact Registry instead. For a comparison between Container Registry and Artifact Registry and information about transitioning from Container Registry to Artifact Registry, see Transitioning from Container Registry.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. Enable the Container Registry API.

   Enable the API

5. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

7. Enable the Container Registry API.

   Enable the API

Choose a shell

To complete this quickstart, use either Cloud Shell or your local shell.

Cloud Shell

Cloud Shell is a shell environment for managing resources hosted on Google Cloud. It comes preinstalled with Docker and the gcloud command-line tool, the primary command-line interface for Google Cloud.

Local shell

If you prefer using your local shell, you must install Docker and Cloud SDK in your environment.

Starting Cloud Shell

To launch Cloud Shell, perform the following steps:

1. Go to Google Cloud Console.

   Google Cloud Console

2. On the menu bar, click the Activate Cloud Shell button: .

A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

Setting up a local shell

To install gcloud and Docker, perform the following steps:

1. Install the Cloud SDK, which includes the gcloud command-line tool. To update an existing installation, run the command gcloud components update.

   Note: On Ubuntu, use the Debian package to install Cloud SDK. The Cloud SDK snap package does not include kubectl or extensions to authenticate with Container Registry using the gcloud tool.

2. Install Docker if it is not already installed.

3. Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on MacOS since Docker Desktop runs on a virtual machine as the root user.

   Linux

   The Docker security group is called docker. To add your username, run the following command:

   sudo usermod -a -G docker ${USER}
   

   Windows

   The Docker security group is called docker-users. To add a user from the Administrator command prompt, run the following command:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Where

   • DOMAIN is your Windows domain.
   • USERNAME is your user name.
   Note: The Docker security group has access equivalent to the root or Administrator user. Only add trusted users who require access to Docker. For details about security impacts, see Docker daemon security.

4. Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.

5. To ensure that Docker is running, run the following Docker command, which returns the current time and date:

docker run busybox date

Configure authentication

Before you can push or pull images, you must configure Docker to use the gcloud command-line tool to authenticate requests to Container Registry.

Run the following command:

gcloud auth configure-docker

The command updates your Docker configuration. You can now connect with Container Registry in your Google Cloud project to push and pull images.

Note: If you used a package manager to install Cloud SDK, you must use the standalone Docker credential helper or another authentication method. See Authentication methods for details.

Obtain an image to push

For this quickstart, you will push a sample image named hello-app.

1. Change to a directory where you want to save the image

2. Run the following command to pull version 1.0 of the image.

   docker pull gcr.io/google-samples/hello-app:1.0
   

Add the image to Container Registry

To add an image to Container Registry, you tag it and then push it to the registry.

Tag the image with a registry name

Tagging the Docker image with a registry name configures the docker push command to push the image to a specific location. For this quickstart, the host location is gcr.io.

Run the following command to tag the image as quickstart-image:tag1:

docker tag gcr.io/google-samples/hello-app:1.0 gcr.io/PROJECT_ID/quickstart-image:tag1

Replace the following:

• PROJECT-ID is your Google Cloud Console project ID, which you need to add to your command. If your project ID contains a colon (:), see Domain-scoped projects.
• gcr.io is the hostname
• quickstart-image is the name of the Docker image
• tag1 is a tag you're adding to the Docker image. If you didn't specify a tag, Docker will apply the default tag latest.

You are now ready to push the image to Container Registry.

Push the image to Container Registry

After you have configured authentication and tagged the local image, you can push the image to the repository that you created.

To push the Docker image, run the following command:

docker push gcr.io/PROJECT_ID/quickstart-image:tag1

where PROJECT_ID is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

When you push an image to a new host location, the service creates the underlying storage bucket unique to your project. You can view images hosted by Container Registry via the Cloud Console, or by visiting the image's registry name in your web browser: http://gcr.io/PROJECT_ID/quickstart-image.

Pull the image from Container Registry

To pull the image from Container Registry onto your local machine, run the following command:

docker pull gcr.io/PROJECT_ID/quickstart-image:tag1

Replace PROJECT_ID with your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

You should see output similar to the following:

latest: Pulling from my-project/quickstart-image:tag1
Digest: sha256:70c42...
Status: Image is up to date for gcr.io/my-project/quickstart-image:tag1

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

Run the following command to delete the Docker image from Container Registry.

gcloud container images delete gcr.io/PROJECT_ID/quickstart-image:tag1 --force-delete-tags

Replace PROJECT_ID with your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

What's next

• Learn more about pushing and pulling Docker images with Container Registry.
• Learn more about managing Docker images in Container Registry.
• Learn about using Container Registry with other Google Cloud services.
• Learn more about Container Registry's features.
• Learn more about Docker.
• Read our resources about DevOps and explore our research program.