DEV Community

Kaushik Mitra
Kaushik Mitra

Posted on Fully Autonomous

Pushing Container Images to Google Cloud Artifact Registry (Step-by-Step)

#docker #gcp #devops #kubernetes

When running Kubernetes locally with Docker Desktop, you have a handy superpower: your local Kubernetes cluster shares your computer's local Docker daemon. Any image you build via docker build is immediately available to your local pods without needing to push it to the internet.

However, the moment you decide to deploy to a managed cloud cluster like Google Kubernetes Engine (GKE), that magic ends. GKE nodes run in Google Cloud's data centers and have no access to your laptop's disk. They need a secure, centralized container registry from which to pull your container images.

Google Container Registry (gcr.io) has now been deprecated in favor of Google Cloud Artifact Registry.

In this guide, we'll walk through setting up Google Cloud Artifact Registry, configuring Docker authentication, tagging our images, and pushing our microservices to Google Cloud.

Prerequisites

Before starting, make sure you have:

  1. A Google Cloud Platform (GCP) account with an active project (e.g., kkm-kube-practice) and billing enabled.
  2. The Google Cloud SDK (gcloud CLI) installed.
  3. Docker installed and running on your machine.
  4. The sample microservices and Dockerfiles from our GitHub repository: MitraKumar/kube-prac-calculator-app.

Step 1: Authenticate and Set Up Your GCP Project

First, let's log into GCP from our terminal and set our active project.

# Authenticate your Google account
gcloud auth login

# Set your active project ID
gcloud config set project kkm-kube-practice
Enter fullscreen mode Exit fullscreen mode

💡 Tip: Replace kkm-kube-practice with your own GCP Project ID throughout this tutorial!

Enable the Artifact Registry API

Before we can create a repository, we must enable the Artifact Registry API on our project:

gcloud services enable artifactregistry.googleapis.com
Enter fullscreen mode Exit fullscreen mode

Step 2: Create a Docker Repository in Artifact Registry

Google Cloud Artifact Registry supports multiple package types (Docker, npm, Maven, Python, etc.). We need a Docker repository.

We will create a repository named kkm-dock located in the asia-south1 region (Mumbai). You can choose any region closest to you or your future GKE cluster (e.g., us-central1, europe-west1):

gcloud artifacts repositories create kkm-dock \
    --repository-format=docker \
    --location=asia-south1 \
    --description="Docker repository for K8s practice microservices"
Enter fullscreen mode Exit fullscreen mode

Verify that the repository was created successfully:

gcloud artifacts repositories list
Enter fullscreen mode Exit fullscreen mode

Output:

REPOSITORY  FORMAT  MODE                 LOCATION     DESCRIPTION
kkm-dock    DOCKER  STANDARD_REPOSITORY  asia-south1  Docker repository for K8s practice microservices
Enter fullscreen mode Exit fullscreen mode

Step 3: Configure Docker Authentication

In order for your standard docker push and docker pull commands to securely authenticate against Google Cloud, Docker needs to know how to obtain GCP access tokens.

Google provides a credential helper integrated right into gcloud. Run this command:

gcloud auth configure-docker asia-south1-docker.pkg.dev
Enter fullscreen mode Exit fullscreen mode

When prompted, confirm with Y.

What did this command just do? It updated your local ~/.docker/config.json file so that any time Docker interacts with asia-south1-docker.pkg.dev, it automatically retrieves an authentication token using your active gcloud session. No hardcoded passwords or long-lived API keys on your machine!

Step 4: Understand the Artifact Registry Image Naming Structure

Google Cloud Artifact Registry requires a specific image naming format:

[REGION]-docker.pkg.dev/[PROJECT_ID]/[REPOSITORY_NAME]/[IMAGE_NAME]:[TAG]
Enter fullscreen mode Exit fullscreen mode

Let's break down our path:

  • Region Host: asia-south1-docker.pkg.dev
  • Project ID: kkm-kube-practice
  • Repository: kkm-dock
  • Image Name: add-service, multiply-service, and docs-service
  • Tag: 1.0

Putting it all together gives our fully qualified image URLs:

  • asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service:1.0
  • asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service:1.0
  • asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service:1.0

Step 5: Tag Your Local Images

Now, let's tag our existing local images with the Artifact Registry URL.

If you already built add-service:1.0, multiply-service:1.0, and docs-service:1.0 locally, you can tag them directly:

docker tag add-service:1.0 \
  asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service:1.0

docker tag multiply-service:1.0 \
  asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service:1.0

docker tag docs-service:1.0 \
  asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service:1.0
Enter fullscreen mode Exit fullscreen mode

Verify with docker images:

docker images | grep pkg.dev
Enter fullscreen mode Exit fullscreen mode

Output:

REPOSITORY                                                               TAG   IMAGE ID       SIZE
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service        1.0   420017c8b88f   49.9MB
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service       1.0   517e75577f70   60.4MB
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service   1.0   c91c40363892   49.9MB
Enter fullscreen mode Exit fullscreen mode

Step 6: Push the Images to Artifact Registry

Now comes the exciting moment—pushing your images to the cloud!

docker push asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service:1.0
docker push asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service:1.0
docker push asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service:1.0
Enter fullscreen mode Exit fullscreen mode

Step 7: Verify the Uploaded Images

You can list the images stored in your repository directly from the command line:

gcloud artifacts docker images list asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock
Enter fullscreen mode Exit fullscreen mode

Output:

IMAGE                                                                    TAGS  DIGEST        CREATE_TIME
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service        1.0   sha256:...   2026-10-03
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service       1.0   sha256:...   2026-10-03
asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service   1.0   sha256:...   2026-10-03
Enter fullscreen mode Exit fullscreen mode

You can also open the Google Cloud Console, navigate to Artifact Registry -> Repositories -> kkm-dock, and inspect your uploaded image layers, vulnerabilities, and tags visually.

Step 8: Update Your Kubernetes Manifests

Now that our images are hosted in Artifact Registry, we update the image: fields in our Kubernetes manifests so GKE knows where to pull them from.

In k8s/01-add-service-pod.yaml:

spec:
  containers:
  - name: add-service
    image: asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/add-service:1.0
Enter fullscreen mode Exit fullscreen mode

In k8s/03-multiply-service-pod.yaml:

spec:
  containers:
  - name: multiply-service
    image: asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/multiply-service:1.0
Enter fullscreen mode Exit fullscreen mode

And in k8s/06-docs-service-pod.yaml:

spec:
  containers:
  - name: docs-service
    image: asia-south1-docker.pkg.dev/kkm-kube-practice/kkm-dock/docs-service:1.0
Enter fullscreen mode Exit fullscreen mode

Note on Permissions: When running on GKE within the same GCP project, GKE default service accounts automatically have read/pull permissions to Artifact Registry repositories in the same project! No complex imagePullSecrets required.

Conclusion & Next Step

Our microservice container images are now safely built, tagged, and published to Google Cloud Artifact Registry.

In the final post of this series, we will:

  1. Spin up a managed Google Kubernetes Engine (GKE Autopilot) cluster.
  2. Install the NGINX Ingress controller on GKE.
  3. Deploy our calculator application to production and test it using a real public Cloud Load Balancer IP!

Stay tuned, and drop any questions in the comments below!

Top comments (0)