cloud-run-basics

Files (9)

• SKILL.md
• attribution.md · references/
• cli-usage.md · references/
• client-library-usage.md · references/
• core-concepts.md · references/
• iac-usage.md · references/
• iam-security.md · references/
• mcp-usage.md · references/
• networking.md · references/

SKILL.md (first lines)

# 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:

    ```bash
    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:

```bash
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:

```bash
    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

From google/skills, Apache-2.0.

More from google/skills