Get Cloud Run Image Utility

Overview

The get-cloudrun-image.sh script retrieves Docker image URIs and deployment details from Cloud Run services using the gcloud CLI.

Script Location: cli/sdlc/utils/get-cloudrun-image.sh

Purpose

This utility provides detailed information about deployed Cloud Run services by:

• ✅ Retrieving Docker image URIs - Gets the exact image deployed
• ✅ Showing image digests - Provides SHA256 digests for immutable references
• ✅ Listing all services - Shows all Cloud Run services in an environment
• ✅ Service metadata - URLs, revisions, creation times
• ✅ Alternative to /version - Works even when /version endpoint is unavailable

Usage

Basic Syntax

./cli/sdlc/utils/get-cloudrun-image.sh <environment> [service-name]

Parameters:

• environment - Environment name: dev, demo, test, or prod
• service-name - (Optional) Specific Cloud Run service name

Examples

Get All Services in Dev Environment

./cli/sdlc/utils/get-cloudrun-image.sh dev

Output:

🔍 Fetching Cloud Run deployment information
📁 Project: construction-code-expert-dev
🌍 Region: us-central1
🚀 Services: All

📋 Listing all Cloud Run services...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Service: construction-code-expert-grpc
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Service URL:
    https://construction-code-expert-grpc-abc123-uc.a.run.app

  Current Revision:
    construction-code-expert-grpc-00042-xyz

  Created:
    2025-09-23T01:26:51.000000Z

  Docker Image:
    gcr.io/construction-code-expert-dev/construction-code-expert-grpc@sha256:1234567890abcdef...

  Image Details:
    Registry: gcr.io
    Project: construction-code-expert-dev
    Image Name: construction-code-expert-grpc
    Digest: sha256:1234567890abcdef...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Service: construction-code-expert-websocket
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Service URL:
    https://construction-code-expert-websocket-def456-uc.a.run.app

  Current Revision:
    construction-code-expert-websocket-00015-abc

  Created:
    2025-10-15T14:30:22.000000Z

  Docker Image:
    gcr.io/construction-code-expert-dev/construction-code-expert-websocket@sha256:abcdef123456...

  Image Details:
    Registry: gcr.io
    Project: construction-code-expert-dev
    Image Name: construction-code-expert-websocket
    Digest: sha256:abcdef123456...

✅ Fetch complete!

💡 Tips:
   - To check the /version endpoint, use:
     ./cli/sdlc/utils/check-deployment-version.sh dev
   - To view service logs, use:
     gcloud logging read 'resource.type=cloud_run_revision' --limit 50 --project=construction-code-expert-dev

Get Specific Service in Test Environment

./cli/sdlc/utils/get-cloudrun-image.sh test construction-code-expert-grpc

Output:

🔍 Fetching Cloud Run deployment information
📁 Project: construction-code-expert-test
🌍 Region: us-central1
🚀 Service: construction-code-expert-grpc

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Service: construction-code-expert-grpc
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Service URL:
    https://construction-code-expert-grpc-xyz789-uc.a.run.app

  Current Revision:
    construction-code-expert-grpc-00078-mno

  Created:
    2025-11-08T22:15:33.000000Z

  Docker Image:
    gcr.io/construction-code-expert-test/construction-code-expert-grpc@sha256:fedcba987654...

  Image Details:
    Registry: gcr.io
    Project: construction-code-expert-test
    Image Name: construction-code-expert-grpc
    Digest: sha256:fedcba987654...

✅ Fetch complete!

Check Demo Environment

./cli/sdlc/utils/get-cloudrun-image.sh demo

Output Explanation

Service Information

For each Cloud Run service, the script displays:

• Service URL - Public HTTPS endpoint
• Current Revision - Active revision name
• Created - When the current revision was created (ISO 8601 timestamp)
• Docker Image - Full image URI with digest

Image Details

The script parses the image URI and extracts:

• Registry - Container registry (usually gcr.io)
• Project - GCP project hosting the image
• Image Name - Name of the container image
• Digest - SHA256 digest (if using digest-based reference)
• Tag - Image tag (if using tag-based reference)

Understanding Image References

Digest-based reference (immutable, recommended):

gcr.io/project-id/image-name@sha256:1234567890abcdef...

Tag-based reference (mutable):

gcr.io/project-id/image-name:v1.2.3

Cloud Run typically uses digest-based references to ensure immutability.

Use Cases

1. Determine Deployment Version (When /version Unavailable)

When older deployments don't have the /version endpoint:

# Check if /version is available
./cli/sdlc/utils/check-deployment-version.sh demo

# If 404, use Cloud Run image inspection
./cli/sdlc/utils/get-cloudrun-image.sh demo

2. Pre-Deployment Comparison

Compare what's deployed vs. what will be deployed:

# Check current deployment
./cli/sdlc/utils/get-cloudrun-image.sh dev construction-code-expert-grpc

# Build new image
mvn clean package
docker build -t gcr.io/construction-code-expert-dev/construction-code-expert-grpc:latest .

# Deploy new image
./cli/sdlc/cloud-run-grpc/deploy.sh dev

3. Cross-Environment Verification

Verify that environments are running different or same images:

echo "=== Dev Images ==="
./cli/sdlc/utils/get-cloudrun-image.sh dev | grep "Digest:"

echo ""
echo "=== Test Images ==="
./cli/sdlc/utils/get-cloudrun-image.sh test | grep "Digest:"

echo ""
echo "=== Prod Images ==="
./cli/sdlc/utils/get-cloudrun-image.sh prod | grep "Digest:"

4. Rollback Investigation

When you need to rollback, identify previous image digests:

# Get current image
./cli/sdlc/utils/get-cloudrun-image.sh prod construction-code-expert-grpc

# List revision history
gcloud run revisions list \
  --service=construction-code-expert-grpc \
  --region=us-central1 \
  --project=construction-code-expert-prod \
  --format="table(metadata.name,spec.containers[0].image,metadata.creationTimestamp)"

5. Audit and Compliance

Track what's deployed for security audits:

#!/bin/bash
# audit-deployments.sh

echo "Deployment Audit - $(date)"
echo "================================"

for env in dev test demo prod; do
  echo ""
  echo "Environment: $env"
  ./cli/sdlc/utils/get-cloudrun-image.sh $env | grep -A 1 "Docker Image:"
done

Prerequisites

• gcloud CLI - Google Cloud SDK
• Authentication - Must be authenticated with appropriate permissions
• IAM Permissions - Cloud Run Viewer or higher

Installation

# Install gcloud CLI
# macOS
brew install google-cloud-sdk

# Ubuntu/Debian
curl https://sdk.cloud.google.com | bash

# Authenticate
gcloud auth login

# Configure default project (optional)
gcloud config set project construction-code-expert-test

Required Permissions

The authenticated user must have at least:

• run.services.get - View Cloud Run services
• run.revisions.get - View Cloud Run revisions

Common roles that include these permissions:

• Cloud Run Viewer (roles/run.viewer)
• Cloud Run Developer (roles/run.developer)
• Cloud Run Admin (roles/run.admin)

Environment Mapping

The script automatically maps environments to GCP projects:

Environment	GCP Project	Region
dev	construction-code-expert-dev	us-central1
demo	construction-code-expert-demo	us-central1
test	construction-code-expert-test	us-central1
prod	construction-code-expert-prod	us-central1

Integration with Other Tools

With check-deployment-version.sh

Use both tools for comprehensive deployment verification:

# Try /version endpoint first
./cli/sdlc/utils/check-deployment-version.sh demo

# Get detailed Cloud Run metadata
./cli/sdlc/utils/get-cloudrun-image.sh demo

With Docker Commands

Inspect the deployed image locally:

# Get image URI
IMAGE=$(./cli/sdlc/utils/get-cloudrun-image.sh test construction-code-expert-grpc | grep "Docker Image:" | awk '{print $3}')

# Pull the image
docker pull $IMAGE

# Inspect the image
docker inspect $IMAGE

With Cloud Build

Correlate Cloud Run deployments with Cloud Build history:

# Get image digest
DIGEST=$(./cli/sdlc/utils/get-cloudrun-image.sh prod construction-code-expert-grpc | grep "Digest:" | awk '{print $2}')

# Find the build that created this image
gcloud builds list \
  --filter="images:*$DIGEST" \
  --project=construction-code-expert-prod

With Git

Map image digests to Git commits:

# Get image creation time
CREATED=$(./cli/sdlc/utils/get-cloudrun-image.sh prod construction-code-expert-grpc | grep "Created:" | awk '{print $2}')

# Find commits around that time
git log --since="$(date -d "$CREATED - 1 hour" --iso-8601)" --until="$(date -d "$CREATED + 1 hour" --iso-8601)" --oneline

Troubleshooting

gcloud Not Installed

❌ Error: gcloud CLI is not installed
💡 Install gcloud CLI: https://cloud.google.com/sdk/docs/install

Solution: Install the Google Cloud SDK.

Permission Denied

❌ Error: Cannot access project 'construction-code-expert-demo'
💡 Possible causes:
   - You don't have access to this project
   - You need to authenticate: gcloud auth login
   - Project doesn't exist

Possible Causes:

1. Not authenticated
2. Insufficient IAM permissions
3. Project doesn't exist

Solutions:

1. Authenticate: gcloud auth login
2. Request access from project admin
3. Verify project ID

No Services Found

⚠️  No Cloud Run services found in construction-code-expert-demo

Possible Causes:

1. No services deployed yet
2. Services in different region
3. Incorrect project

Solution: Verify the environment and region.

Service Not Found

❌ Failed to get details for service: my-service

Solution: List all services first to verify the exact name:

./cli/sdlc/utils/get-cloudrun-image.sh dev

Advanced Usage

Export to CSV

#!/bin/bash
# export-cloudrun-images.sh

echo "Environment,Service,Image,Digest,Created"

for env in dev test demo prod; do
  ./cli/sdlc/utils/get-cloudrun-image.sh $env 2>/dev/null | \
    awk -v env="$env" '
      /^📦 Service:/ { service=$3 }
      /Docker Image:/ { image=$3 }
      /Digest:/ { digest=$2 }
      /Created:/ { created=$2; print env","service","image","digest","created }
    '
done > cloudrun-images.csv

Monitor Image Updates

#!/bin/bash
# monitor-image-updates.sh

SERVICE="construction-code-expert-grpc"
ENV="prod"

CURRENT_DIGEST=""

while true; do
  NEW_DIGEST=$(./cli/sdlc/utils/get-cloudrun-image.sh $ENV $SERVICE | grep "Digest:" | awk '{print $2}')
  
  if [ "$NEW_DIGEST" != "$CURRENT_DIGEST" ] && [ -n "$CURRENT_DIGEST" ]; then
    echo "🚨 Image updated!"
    echo "  Old: $CURRENT_DIGEST"
    echo "  New: $NEW_DIGEST"
    
    # Send notification (Slack, email, etc.)
  fi
  
  CURRENT_DIGEST=$NEW_DIGEST
  sleep 300  # Check every 5 minutes
done

Compare Across Environments

#!/bin/bash
# compare-images.sh

SERVICE="construction-code-expert-grpc"

echo "Image Comparison for $SERVICE"
echo "=============================="

for env in dev test prod; do
  DIGEST=$(./cli/sdlc/utils/get-cloudrun-image.sh $env $SERVICE 2>/dev/null | grep "Digest:" | awk '{print $2}')
  echo "$env: $DIGEST"
done | sort -k2

Best Practices

1. Always Use Digest-Based References

When deploying, prefer digest-based references over tags:

# Good - immutable reference
IMAGE="gcr.io/project/image@sha256:abc123..."

# Less reliable - tags can be moved
IMAGE="gcr.io/project/image:latest"

2. Document Deployments

Keep a record of what was deployed:

# Save deployment record
./cli/sdlc/utils/get-cloudrun-image.sh prod > "deployment-$(date +%Y%m%d-%H%M%S).txt"

3. Verify After Deployment

Always check that the deployment succeeded:

# Deploy
./cli/sdlc/cloud-run-grpc/deploy.sh prod

# Verify
./cli/sdlc/utils/get-cloudrun-image.sh prod construction-code-expert-grpc

4. Use for Rollback Planning

Before deploying, save the current state for potential rollback:

# Before deployment
./cli/sdlc/utils/get-cloudrun-image.sh prod > rollback-state.txt

# If deployment fails, reference this file for rollback

See Also

• Check Deployment Version Utility - Check version via /version endpoint
• Developer Playbook
• Cloud Run Deployment
• Environment Provisioning
• Google Cloud Run Documentation