DockerHow-ToBeginner · 4 min read

How to Use Google Container Registry with Docker

To use Google Container Registry (GCR), first authenticate with gcloud auth configure-docker, then tag your Docker image with the GCR hostname and your project ID, and finally push or pull images using docker push or docker pull commands.

📐

Syntax

Google Container Registry uses Docker commands with a special image name format. The general syntax to tag an image is:

docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE:TAG
docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

Where:

SOURCE_IMAGE: Your local Docker image name.
HOSTNAME: The GCR region hostname like gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
PROJECT-ID: Your Google Cloud project ID.
IMAGE: The name you want to give your image in GCR.
TAG: The version tag, e.g., latest.

bash

docker tag my-app gcr.io/my-project/my-app:latest
docker push gcr.io/my-project/my-app:latest

💻

Example

This example shows how to authenticate, tag, and push a Docker image to Google Container Registry.

bash

gcloud auth configure-docker

docker build -t my-app .
docker tag my-app gcr.io/my-project/my-app:latest
docker push gcr.io/my-project/my-app:latest

Output

WARNING: Docker configuration file updated. Sending build context to Docker daemon 8.192kB Step 1/3 : FROM alpine ---> a24bb4013296 Step 2/3 : CMD ["echo", "Hello from my-app"] ---> Running in 123abc456def Removing intermediate container 123abc456def ---> 789xyz123uvw Successfully built 789xyz123uvw Successfully tagged my-app:latest The push refers to repository [gcr.io/my-project/my-app] ... latest: digest: sha256:abcdef1234567890 size: 1234

⚠️

Common Pitfalls

Common mistakes when using Google Container Registry include:

Not authenticating with gcloud auth configure-docker before pushing or pulling images.
Using the wrong hostname or project ID in the image tag.
Forgetting to enable the Container Registry API in Google Cloud Console.
Not having proper IAM permissions to push or pull images.

Always verify your project ID and hostname, and ensure you have permission to access the registry.

bash

docker tag my-app wrong-hostname/my-project/my-app:latest
# Wrong hostname causes push failure

gcloud auth configure-docker
# Correct authentication

docker tag my-app gcr.io/my-project/my-app:latest
# Correct tag

docker push gcr.io/my-project/my-app:latest
# Successful push

📊

Quick Reference

Command	Purpose
gcloud auth configure-docker	Set up Docker to authenticate with GCR
docker build -t IMAGE .	Build a Docker image locally
docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE:TAG	Tag image for GCR
docker push HOSTNAME/PROJECT-ID/IMAGE:TAG	Push image to GCR
docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG	Pull image from GCR

✅

Key Takeaways

Authenticate Docker with GCR using 'gcloud auth configure-docker' before pushing or pulling images.

Tag images with the correct GCR hostname and your Google Cloud project ID.

Enable Container Registry API and have proper permissions in your Google Cloud project.

Use 'docker push' and 'docker pull' commands with GCR-tagged images to upload or download containers.

Double-check your project ID and hostname to avoid common tagging mistakes.