Working with Local Docker Images and Google Container Registry

Introduction

Google Container Registry (GCR) is a service that stores and manages Docker container images in the cloud. This guide will show you how to push (upload) and pull (download) Docker images to and from Google Container Registry.

Think of GCR as a cloud storage space for your Docker images. Instead of keeping images only on your computer, you can upload them to GCR and access them from anywhere.

What You Need Before Starting

Before you begin, make sure you have:

1. Google Cloud Account - An active account with proper permissions
2. Docker Installed - Docker running on your computer
3. Google Cloud SDK - The gcloud command-line tool installed
4. GCP Project - A Google Cloud project created and ready

Step 1: Set Up Google Cloud SDK

The Google Cloud SDK provides tools to interact with Google Cloud services. You need to configure it first.

Initialize gcloud

Open your terminal and run:

$ gcloud init

This command will:

• Ask you to log in to your Google Cloud account
• Let you choose which project to use
• Set up default settings for your commands

Important: Make sure you select the correct project because your images will be stored in that project.

Check Your Configuration

After setup, verify your settings:

$ gcloud config list

This shows your current account, project, and other settings.

Step 2: Connect Docker to Google Cloud

For Docker to communicate with Google Container Registry, you need to set up authentication.

Configure Docker Authentication

Run this command:

$ gcloud auth configure-docker

When asked for confirmation, type Y and press Enter.

What This Does

This command tells Docker to use your Google Cloud credentials when connecting to GCR. It creates or modifies a file at ~/.docker/config.json that stores this authentication information.

Verify the Setup

Check if the configuration file was created:

$ cat ~/.docker/config.json

You should see Google Container Registry endpoints listed in the file.

Step 3: View Your Container Images

Once authenticated, you can see what images are stored in your registry.

List All Images

To see all images in your project:

$ gcloud container images list

This displays images in the format: HOSTNAME/PROJECT-ID/IMAGE-NAME

View Image Tags

To see all versions (tags) of a specific image:

$ gcloud container images list-tags gcr.io/YOUR_PROJECT_ID/IMAGE_NAME

Tags help you track different versions of the same image (like v1.0, v2.0, latest).

Step 4: Pull Images from GCR

Pulling means downloading an image from GCR to your local computer.

Basic Pull Command

The syntax is:

$ docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

Let's break this down:

• HOSTNAME: The registry location (like gcr.io)
• PROJECT-ID: Your Google Cloud project ID
• IMAGE: The name of your image
• TAG: The version you want (like latest or v1.0)

Example

To pull an nginx image:

$ docker pull gcr.io/myproject/nginx:latest

Registry Locations

GCR offers different locations for better performance:

• gcr.io - Global (multi-region)
• us.gcr.io - United States
• eu.gcr.io - European Union
• asia.gcr.io - Asia

Choose the one closest to you for faster downloads.

Verify the Download

After pulling, check if the image is on your computer:

$ docker images

You should see your downloaded image in the list.

Step 5: Push Images to GCR

Pushing means uploading an image from your computer to GCR.

Build Your Image First

If you haven't built your Docker image yet:

$ docker build -t myimage:tag .

This creates an image from your Dockerfile.

Tag Your Image for GCR

Before pushing, you need to tag your image with the GCR format:

$ docker image tag SOURCE_IMAGE:TAG HOSTNAME/PROJECT-ID/IMAGE:TAG

Example

Let's say you have a local image called nginxlocal:latest:

$ docker image tag nginxlocal:latest gcr.io/myproject/nginx:latest

What this does:

• Takes your local image nginxlocal:latest
• Creates a new tag gcr.io/myproject/nginx:latest
• Both tags point to the same image (no copying)

Check Your Tags

Verify the tag was created:

$ docker images

You'll see both:

• nginxlocal:latest (your original)
• gcr.io/myproject/nginx:latest (the new tag)

They have the same IMAGE ID because they're the same image.

Upload to GCR

Now push the image to Google Container Registry:

$ docker image push --all-tags gcr.io/myproject/nginx

The --all-tags flag uploads all versions of the image at once.

What Happens During Push

You'll see:

• Progress bars showing upload status
• Which image layers are being uploaded
• Confirmation when the upload is complete

Docker is smart - if a layer already exists in GCR, it won't upload it again.

Verify the Upload

Check if your image is now in GCR:

$ gcloud container images list

Or check specific tags:

$ gcloud container images list-tags gcr.io/myproject/nginx

Quick Reference Commands

Setup

# Initialize gcloud
$ gcloud init

# Configure Docker authentication
$ gcloud auth configure-docker

Viewing Images

# List all images
$ gcloud container images list

# List tags for an image
$ gcloud container images list-tags gcr.io/PROJECT-ID/IMAGE

Pulling Images

# Pull from GCR
$ docker pull gcr.io/PROJECT-ID/IMAGE:TAG

# View local images
$ docker images

Pushing Images

# Build image
$ docker build -t myimage:tag .

# Tag for GCR
$ docker image tag myimage:tag gcr.io/PROJECT-ID/IMAGE:TAG

# Push to GCR
$ docker image push --all-tags gcr.io/PROJECT-ID/IMAGE

Common Problems and Solutions

Problem: Authentication Error

Solution: Refresh your login

$ gcloud auth login
$ gcloud auth configure-docker

Problem: Permission Denied

Solution: Check your account has the right permissions in Google Cloud Console. You need roles like Storage Admin or Storage Object Creator.

Problem: Wrong Project

Solution: Set the correct project

$ gcloud config set project YOUR_PROJECT_ID

Problem: Slow Upload/Download

Solution:

• Check your internet connection
• Use a regional registry closer to your location
• Try again during off-peak hours

Best Practices

Naming Your Images

Use clear, descriptive names:

• Good: gcr.io/myproject/web-api:v1.0.0
• Bad: gcr.io/myproject/img1:latest

Tagging Strategy

• Use version numbers: v1.0.0, v1.0.1
• Use environment tags: dev, staging, prod
• Always tag specific versions, don't rely only on latest

Keep Images Clean

• Regularly delete old, unused images
• Use smaller base images when possible
• Remove unnecessary files from your images

Security Tips

• Don't store passwords or secrets in images
• Scan images for security vulnerabilities
• Use private repositories for sensitive applications
• Set proper access controls in Google Cloud

Google Container Registry makes it easy to store and share Docker images in the cloud. With these basic commands, you can now manage your container images effectively.

Now you're ready to work with Docker images in Google Container Registry!