/cloud-run-basics

name: cloud-run-basics
metadata:
  version: "1.0.1"
  category: Serverless
description: >-
  Manages Cloud Run services, jobs, and worker pools. Use when you need to deploy applications
  responding to HTTP requests (services), run event-triggered or scheduled tasks (jobs),
  or handle always-on pull-based background processing (worker pools).

Cloud Run Basics

Cloud Run is a fully managed application platform for running your code, function, or container on top of Google's highly scalable infrastructure. It abstracts away infrastructure management, providing three primary resource types:

1. **Services:** Responds to HTTP requests sent to a unique and stable endpoint, using stateless instances that autoscale based on a variety of key metrics, also responds to events and functions. 2. **Jobs:** Executes parallelizable tasks that are executed manually, or on a schedule, and run to completion. 3. **Worker pools:** Handles always-on background workloads such as pull-based workloads, for example, Kafka consumers, Pub/Sub pull queues, or RabbitMQ consumers.

Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-run-basics)"` and append `agent-skills/1.0 (skill:cloud-run-basics)` to `User-Agent` headers.

Prerequisites

1. Enable the Cloud Run Admin API and Cloud Build APIs:

    gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet

1. If you are under a domain restriction organization policy [restricting](https://docs.cloud.google.com/organization-policy/restrict-domains.md.txt) unauthenticated invocations for your project, you will need to access your deployed service as described under [Testing private services](https://docs.cloud.google.com/run/docs/triggering/https-request.md.txt).

Required roles

You need the following roles to deploy your Cloud Run resource:

• Cloud Run Admin (`roles/run.admin`) on the project
• Cloud Run Source Developer (`roles/run.sourceDeveloper`) on the project
• Service Account User (`roles/iam.serviceAccountUser`) on the service

identity

• Logs Viewer (`roles/logging.viewer`) on the project

Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior.

For Cloud Build to build your sources, grant the Cloud Build service account the Cloud Run Builder (`roles/run.builder`) role on your project:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder \
    --quiet

Replace `PROJECT_ID` with your Google Cloud project ID and `SERVICE_ACCOUNT_EMAIL_ADDRESS` with the email address of the Cloud Build service account.

Deploy a Cloud Run service

You can deploy your service to Cloud Run by using a container image or deploy directly from source code using a single Google Cloud CLI command.

> **CRITICAL RULE:** Any deployed code MUST listen on 0.0.0.0 (not 127.0.0.1) > and use the injected $PORT environment variable (defaults to 8080), or it will > crash on boot.

Deploy a container image to Cloud Run

Cloud Run imports your container image during deployment. Cloud Run keeps this copy of the container image as long as it is used by a serving revision. Container images are not pulled from their container repository when a new Cloud Run instance is started.

Supported container images

You can directly use container images stored in the [Artifact Registry](https://docs.cloud.google.com/artifact-registry/docs/overview.md.txt), or [Docker Hub](https://hub.docker.com/). Google recommends the use of Artifact Registry since Docker Hub images are [cached](https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images.md.txt) for up to one hour.

You can use container images from other public or private registries (like JFrog Artifactory, Nexus, or GitHub Container Registry), by setting up an [Artifact Registry remote repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo.md.txt).

You should only consider [Docker Hub](https://hub.docker.com/) for deploying popular container images such as [Docker Official Images](https://docs.docker.com/docker-hub/official_images/) or [Docker Sponsored OSS images](https://docs.docker.com/docker-hub/dsos-program/). For higher availability, Google recommends deploying these Docker Hub images using an [Artifact Registry remote repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo.md.txt).

To deploy a container image, run the following command:

    gcloud run deploy SERVICE_NAME \
        --image IMAGE_URL \
        --region us-central1 \
        --allow-unauthenticated \
        --quiet

Replace the following:

• SERVICE_NAME: the name of the service you want to deploy to. Service names

must be 49 characters or less and must be unique per region and project. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.

• IMAGE_URL: a reference to the container image, for example,

`us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG`. Note that if you don't supply the `--image` flag, the deploy command will attempt to deploy from source code.

Deploy from source code

There are two