GCP Zero to Hero: Day 12 — Google Artifact Registry Deep Dive

Google Artifact Registry (GAR) is the single, centralized enterprise storage solution on Google Cloud Platform for managing both container images and non-container language packages (e.g., Maven, NPM, Python). Replacing the deprecated Google Container Registry (GCR), Artifact Registry seamlessly integrates with Google Cloud Identity and Access Management (IAM), Cloud KMS encryption, and automated lifecycle policies to support secure software supply chain workflows across distributed engineering teams.

1. The Evolution & Need for Centralized Artifact Storage

When developing software locally, developers often build container images or application binaries using local tooling (e.g., docker build). However, enterprise software delivery requires these artifacts to be shared across multiple environments and organizational stakeholders.

Why Local Storage Fails at Scale

• Single Point of Failure (SPOF): Storing builds exclusively on developer machines creates severe operational risk. If a developer's workstation fails, critical release artifacts are lost.
• Combinatorial Version Explosion: In a microservices architecture, a single service (e.g., a payments service) undergoes dozens or hundreds of release iterations ($v1, v2, \dots, v100$). Across hundreds of microservices, an enterprise manages thousands of discrete container images and package versions.
• Environment Consistency: Staging, QA, and Production environments require an immutable, single source of truth to pull verified builds.

Industry Evolution: GCR to Artifact Registry

Note: Google Container Registry (gcr.io) was officially deprecated in March 2025. Google Cloud migrated all container registry capabilities strictly to Google Artifact Registry (GAR). GAR serves as a unified superset for both container and non-container dependencies.

2. Container vs. Non-Container Artifacts in GAR

Unlike traditional container registries that only store Docker images, Google Artifact Registry supports two primary categories of software dependencies within a unified infrastructure:

Logical Organization: Repositories

Within GAR, artifacts are isolated into Repositories. Repositories act as logical boundaries (similar to source control repositories) for distinct microservices or package types:

• payments-repo: Container images for the Payments microservice.
• shipments-repo: Container images for the Shipments microservice.
• shared-java-libs: Maven JAR files utilized across internal backend teams.

Organizing artifacts into separate repositories allows cloud engineers to grant fine-grained, repository-level access controls via IAM policies.

3. Registry Landscape: Public vs. Self-Hosted vs. Managed

When selecting an artifact management strategy, enterprises evaluate trade-offs between public registries, self-hosted infrastructure, and managed cloud solutions.

4. Key Enterprise Architectural Benefits of GAR

Managed cloud registries like Google Artifact Registry offer distinct advantages over self-hosted setups:

1. Zero Infrastructure Maintenance: Google manages OS security patching, underlying storage scaling, and uptime guarantees without manual administrative intervention.
2. Global Availability & Latency Reduction: Repositories can be deployed in specific GCP regions or multi-regions. Teams operating across North America, Asia, and Europe pull artifacts from geographically proximate storage endpoints, eliminating cross-continental network latency.
3. In-Flight & At-Rest Security:
   • Supports default Google-managed encryption or Customer-Managed Encryption Keys (CMEK) via Cloud KMS.
   • Integrated vulnerability scanning checks pushed images for known Common Vulnerabilities and Exposures (CVEs) automatically.
4. Native Cloud IAM Integration:
   • Eliminates the need to manage separate database credentials or standalone authentication systems for build servers.
   • Permissions are governed directly by GCP IAM roles (e.g., roles/artifactregistry.writer for build workers, roles/artifactregistry.reader for deployment targets).

5. Architectural End-to-End Workflow

The following diagram illustrates the complete workflow demonstrated in this guide: configuring a Compute Engine VM with a dedicated Service Account to build, authenticate, tag, and push container images directly to Google Artifact Registry.

6. Step-by-Step Hands-on Implementation

Follow these steps using the Google Cloud CLI (gcloud) and Cloud Shell to automate the repository setup, provisioning, authentication, and image deployment.

Step 1: Initialize Environment Variables

Define consistent environment variables across your shell session to minimize typos and streamline execution.

# Export standard deployment variables
export PROJECT_ID=$(gcloud config get-value project)
export REGION="asia-south1"
export ZONE="asia-south1-a"
export REPO_NAME="ecommerce-payments-dev"
export IMAGE_NAME="payments-demo"
export TAG="v1"

# Derived Artifact Registry variables
export AR_HOST="${REGION}-docker.pkg.dev"
export IMG_PATH="${AR_HOST}/${PROJECT_ID}/${REPO_NAME}/${IMAGE_NAME}"

Step 2: Enable Required GCP Service APIs

Enable the necessary APIs for Artifact Registry, Compute Engine, and Identity and Access Management (IAM).

gcloud services enable \
    artifactregistry.googleapis.com \
    compute.googleapis.com \
    iam.googleapis.com

Step 3: Create the Artifact Registry Repository

Create a Docker-formatted artifact repository in the designated regional location.

gcloud artifacts repositories create ${REPO_NAME} \
    --repository-format=docker \
    --location=${REGION} \
    --description="Docker repository for payments microservice development environment"

Step 4: Provision Service Account & Assign IAM Roles

Create a dedicated Service Account for build operations and bind the roles/artifactregistry.writer role scoped directly to the newly created repository.

# Create the Service Account
gcloud iam service-accounts create ar-demo-sa \
    --display-name="Artifact Registry Demo Service Account"

# Bind Artifact Registry Writer role to the Service Account
gcloud artifacts repositories add-iam-policy-binding ${REPO_NAME} \
    --location=${REGION} \
    --member="serviceAccount:ar-demo-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/artifactregistry.writer"

Step 5: Provision a Compute Engine Instance with Attached Service Account

Spin up a lightweight Linux VM instance (e2-micro) attached to the identity of the created Service Account.

gcloud compute instances create ar-pay-build-vm \
    --zone=${ZONE} \
    --machine-type=e2-micro \
    --service-account="ar-demo-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
    --scopes="https://www.googleapis.com/auth/cloud-platform"

Step 6: Connect to the Instance & Install Docker Engine

SSH into the newly created VM instance, update system packages, install the Docker runtime, and set up user group privileges.

# SSH into the VM
gcloud compute ssh ar-pay-build-vm --zone=${ZONE}

Once connected inside the VM terminal:

# Re-export environment variables inside VM session
export PROJECT_ID="your-project-id-here"
export REGION="asia-south1"
export REPO_NAME="ecommerce-payments-dev"
export IMAGE_NAME="payments-demo"
export TAG="v1"
export AR_HOST="${REGION}-docker.pkg.dev"
export IMG_PATH="${AR_HOST}/${PROJECT_ID}/${REPO_NAME}/${IMAGE_NAME}"

# Update OS packages and install Docker
sudo apt-get update
sudo apt-get install -y docker.io

# Grant current user rights to execute Docker without root/sudo
sudo usermod -aG docker $USER
newgrp docker

Step 7: Configure Docker Host Authentication

Configure Docker to automatically pass GCP identity tokens when communicating with the Artifact Registry regional host endpoint.

# Register gcloud as a Docker credential helper for the regional registry endpoint
gcloud auth configure-docker ${AR_HOST} --quiet

Step 8: Build, Tag, and Push the Container Image

Construct a simple application container image using Nginx, tag it with the target Artifact Registry path, and push it to Google Cloud.

# Create a simple Dockerfile
cat <<EOF > Dockerfile
FROM nginx:alpine
RUN echo "<h1>Hello from Google Artifact Registry</h1>" > /usr/share/nginx/html/index.html
EOF

# Build local docker image
docker build -t ${IMAGE_NAME}:local .

# Tag image with the Artifact Registry fully qualified repository path
docker tag ${IMAGE_NAME}:local ${IMG_PATH}:${TAG}

# Push image to GAR
docker push ${IMG_PATH}:${TAG}

7. Troubleshooting Real-World Authentication & Permission Errors

During CI/CD integration or VM build setups, engineers frequently encounter permission errors when interacting with GAR.

Error Scenario:
$ docker push asia-south1-docker.pkg.dev/my-project/my-repo/payments-demo:v1
denied: Unauthenticated request / PermissionDenied

Diagnostic Decision Tree

Common Pitfalls & Solutions

1. Incorrect Service Account Attached:
   • Issue: The Compute Engine VM is running under the default Compute Engine Service Account, which lacks writer permissions on the target repository.
   • Fix: Ensure the VM is attached to the specific Service Account granted roles/artifactregistry.writer.
2. Missing Credential Helper:
   • Issue: Docker attempts to authenticate against Docker Hub standard endpoints instead of GCP.
   • Fix: Execute gcloud auth configure-docker <region>-docker.pkg.dev on the host building the images.
3. Scope Mismatches:
   • Issue: VM instance was created with restricted API access scopes.
   • Fix: Provision VMs with the broad https://www.googleapis.com/auth/cloud-platform scope and rely on IAM roles to enforce granular access restrictions.

8. Enterprise Lifecycle & Cleanup Policies

Over time, automated CI/CD pipelines generate thousands of intermediate build artifacts, driving up cloud storage costs. GAR supports automated repository lifecycle policies to prune stale images.

Cleanup Policy Configuration

In the GCP Console or via CLI, cloud engineers can define JSON policy rules to target untagged images or images older than a specified threshold:

{
  "name": "delete-untagged-builds",
  "action": "DELETE",
  "condition": {
    "tagState": "UNTAGGED",
    "olderThan": "14d"
  }
}

Key capabilities:

• Dry-Run Mode: Test policy logic against existing artifacts to verify what would be deleted before applying destructive changes.
• Tag Protection: Exclude specific operational tags (e.g., prod, latest, stable) from automated deletion rules regardless of age.

9. Summary and Key Takeaways

• Deprecation Notice: Google Container Registry (gcr.io) was deprecated in March 2025; Google Artifact Registry (GAR) is the mandatory standard on GCP.
• Dual Format Support: GAR serves as a unified registry storing both OCI/Docker container images and package dependencies (Maven, NPM, PyPI, RPM/Debian).
• Enterprise Granularity: Repositories act as isolation boundaries created per microservice, facilitating scoped IAM permissions (roles/artifactregistry.writer, roles/artifactregistry.reader).
• Managed Overhead Elimination: GAR removes the operational maintenance, cluster scaling, and OS patching required by self-hosted registries.
• Global Latency Reduction: Hosting repositories regionally or multi-regionally ensures high availability and fast image pulls across distributed global teams.
• Integrated IAM Authentication: Build nodes authenticate natively using GCP Service Accounts and the gcloud auth configure-docker credential helper.
• Native Security Features: Offers automated container image vulnerability scanning alongside customer-managed encryption key support via Cloud KMS.
• Cost Optimization: Automated retention and cleanup policies allow administrators to delete temporary or untagged CI/CD artifacts automatically.