Deploy Your First Cloud Run Service on Google Cloud

What you will do

By the end of this walkthrough you will have:

• A running Cloud Run service with a stable HTTPS URL
• A container image stored in Artifact Registry
• The ability to deploy updates and roll back to earlier revisions
• Live logs flowing into Cloud Logging automatically

What Cloud Run actually is

Cloud Run is Google Cloud’s serverless container platform. You give it a container image and it handles everything else: provisioning servers, routing HTTPS traffic, scaling up under load, and scaling back down to zero when nobody is using the service.

Cloud Run is popular for beginners because there are no virtual machines to configure, no load balancers to wire up, and no Kubernetes clusters to manage. It is also popular for production teams because it scales down to zero, meaning you pay nothing when the service is not handling requests.

The only real constraint: your application must be stateless and must listen on the port Cloud Run tells it to use via the PORT environment variable. More on that in Step 3.

To understand how containers work in GCP before you continue, see Container Images in GCP.

Before you start

You need the following before running any commands:

• A GCP project with billing enabled. Cloud Run and Artifact Registry are paid services (both have free tiers, but billing must be active).

• The gcloud CLI installed and authenticated. Run gcloud auth login and gcloud config set project YOUR_PROJECT_ID.

• Docker installed locally if you want to build images on your machine. You can skip this entirely by using Cloud Build instead. The commands below cover both options.

• Required APIs enabled. The first step in the walkthrough enables them for you. If the project already has them enabled, the command is a no-op.

How Cloud Run deployment works

Before jumping into commands, here is what happens at each stage:

1. You write or already have an app. The only Cloud Run requirement is that it reads the PORT environment variable and listens on it.

2. You package it into a container image. A Dockerfile describes how to build that image. If you would rather skip the Dockerfile entirely, the —source flag does this step automatically using Buildpacks.

3. You push the image to Artifact Registry. This is the image storage service inside your GCP project. It keeps images private, applies IAM controls, and lets Cloud Run pull them securely without needing separate credentials.

4. You deploy to Cloud Run. The gcloud run deploy command tells Cloud Run which image to use, which region to run in, and how much memory and CPU to allocate.

5. Cloud Run creates a revision and gives you a URL. The URL is stable. Future deployments create new revisions but do not change the URL.

6. You can split traffic between revisions. This enables canary releases and zero-downtime rollbacks. See Cloud Run Scaling Behaviour for how Cloud Run manages instances behind that URL.

Step-by-step: deploy your first Cloud Run service

Step 1: Enable the required APIs

Run this once per project. Cloud Run, Artifact Registry, and Cloud Build all need to be active. If they are already enabled, these commands do nothing.

gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com
gcloud services enable cloudbuild.googleapis.com

Step 2: Create an Artifact Registry repository

Artifact Registry is where your container images will be stored. Think of a repository as a named folder for images inside your project — one repository can hold many images across many versions.

gcloud artifacts repositories create my-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="Container images"

# Allow Docker to authenticate with this registry location
gcloud auth configure-docker us-central1-docker.pkg.dev

The configure-docker command adds credentials to your local Docker config so docker push commands to this registry authenticate automatically.

Step 3: Write a minimal app

This Python example is intentionally minimal. The only thing that matters for Cloud Run is that the app reads the PORT environment variable and listens on it.

# app.py
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"Hello from Cloud Run!\n")

if __name__ == "__main__":
    port = int(os.environ.get("PORT", 8080))
    server = HTTPServer(("", port), Handler)
    print(f"Listening on port {port}")
    server.serve_forever()

Step 4: Write the Dockerfile

The Dockerfile describes how to package your app into a container image. Use a slim base image. Smaller images mean faster cold starts and lower storage costs in Artifact Registry.

# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]

Step 5: Build and push the image

Set variables first so the image path is consistent across all commands. Use a version tag like :v1 rather than only :latest. This matters for rollbacks later.

# Set these once; they are reused in every command below
export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export IMAGE=$REGION-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:v1

# Option A: build and push locally (requires Docker installed)
docker build -t $IMAGE .
docker push $IMAGE

# Option B: build in the cloud with Cloud Build (no local Docker needed)
gcloud builds submit --tag $IMAGE

Cloud Build runs the build on Google infrastructure and pushes the image directly to Artifact Registry. It is a good option when working from a machine without Docker or when you want reproducible builds across a team. For more detail, see Building Docker Images with Cloud Build.

Step 6: Deploy to Cloud Run

This command deploys the image as a Cloud Run service. —allow-unauthenticated makes it publicly accessible. Remove it for private services.

gcloud run deploy my-app \
  --image=$IMAGE \
  --region=$REGION \
  --platform=managed \
  --allow-unauthenticated \
  --memory=256Mi \
  --cpu=1

The first deployment takes 30 to 60 seconds. Subsequent deployments of the same service are faster because the infrastructure already exists. When the command finishes, it prints the service URL.

Step 7: Test the service URL

Retrieve the stable HTTPS URL and send a request to confirm it is working.

# Get the service URL
SERVICE_URL=$(gcloud run services describe my-app \
  --region=$REGION \
  --format="value(status.url)")

echo $SERVICE_URL

# Send a test request
curl $SERVICE_URL

You should see Hello from Cloud Run!. The URL is stable. It does not change between revisions, canary releases, or rollbacks.

Step 8: Deploy an update

Modify the app (change the response message, for example), build a new image with a new version tag, and deploy again.

export IMAGE_V2=$REGION-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:v2

# Build the updated image
docker build -t $IMAGE_V2 .
docker push $IMAGE_V2

# Deploy the new version
# Cloud Run creates a new revision and shifts traffic to it automatically
gcloud run deploy my-app \
  --image=$IMAGE_V2 \
  --region=$REGION

Cloud Run performs a zero-downtime deployment. The old revision continues handling traffic until the new one passes health checks, then traffic switches over.

Step 9: View logs

Cloud Run sends container stdout and stderr to Cloud Logging automatically. No logging SDK or agent is needed. Just print to stdout.

# Stream live logs as requests come in
gcloud run services logs tail my-app --region=$REGION

# Read the last 50 entries
gcloud logging read \
  'resource.type="cloud_run_revision" AND resource.labels.service_name="my-app"' \
  --limit=50 \
  --format="value(timestamp,textPayload)"

Step 10: Roll back if needed

Cloud Run keeps all previous revisions. To roll back, redirect traffic to an older revision by name.

# List all revisions for this service
gcloud run revisions list --service=my-app --region=$REGION

# Canary: send 10% to the new revision, 90% to the previous one
# Useful when validating a new version before fully committing
gcloud run services update-traffic my-app \
  --region=$REGION \
  --to-revisions=my-app-00002-xyz=10,my-app-00001-abc=90

# Full rollback: send all traffic back to the previous revision
gcloud run services update-traffic my-app \
  --region=$REGION \
  --to-revisions=my-app-00001-abc=100

For advanced deployment patterns like blue-green or progressive canary releases, see Canary Deployments on GCP.

When to use Cloud Run

Cloud Run is a strong fit for:

• HTTP APIs and REST services. Stateless request/response workloads that benefit from automatic scaling and scale-to-zero billing.

• Internal microservices. Services consumed only by other GCP workloads, secured with IAM authentication rather than API keys.

• Lightweight web apps. Low-traffic tools and dashboards that should cost nothing at idle.

• Event-driven workloads. Cloud Run integrates natively with Pub/Sub, Eventarc, and Cloud Tasks to process events as they arrive.

• Containerised workloads without server management. Anything that runs in a container where you do not want to manage infrastructure.

• Side projects and prototypes. The free tier is generous and there is no idle cost when nobody is using the service.

When Cloud Run may not be the right fit

Cloud Run works well for most HTTP-driven workloads, but it is not the right tool for everything:

• Long-running background processes. Cloud Run has a maximum request timeout of 3600 seconds. Persistent daemons or indefinite workers need Compute Engine or GKE.

• Stateful services. Cloud Run instances do not have persistent local storage. If your app needs to write files that survive across requests, use Cloud Storage, a database, or a persistent disk on GKE or Compute Engine.

• GPU workloads. Cloud Run does not support GPU instances. Use Compute Engine or GKE for ML inference and training.

• Services that need very low or consistent latency. Cold starts add latency when traffic is sparse. Minimum instances eliminate this but add cost. For strict latency requirements, evaluate GKE or a VM-based approach.

• Hundreds of microservices with complex networking. At large scale, GKE gives you more control over service mesh, networking policies, and cluster-level configuration.

See Choosing Between Cloud Run, GKE, and Compute Engine for a full comparison.

Cloud Run vs Cloud Functions

These two services look similar from the outside but serve different purposes:

The practical rule: if your workload is a self-contained function that reacts to an event, Cloud Functions is simpler. If it is an HTTP service, needs a custom runtime, or involves any complexity beyond a single handler, Cloud Run is the better fit. For a full breakdown, see Cloud Run vs Cloud Functions.