cloud-run-basics — quality + safety report

---
name: cloud-run-basics
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).
source: google/skills (Apache 2.0)
---

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

## 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)
   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#testing-private).

### 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), 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)
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).

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).

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
    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 different ways to deploy your service from source:

*   Deploy from source with build (default): This option uses Google Cloud's
    buildpacks and Cloud Build to automatically build container images from your
    source code without having to install Docker on your machine or set up
    buildpacks or Cloud Build. By default, Cloud Run uses the default machine
    type provided by Cloud Build.

    *   To deploy from source with automatic base image updates enabled, run the
        following command:

         ```bash
         gcloud run deploy SERVICE_NAME --source . \
         --base-image BASE_IMAGE \
         --automatic-updates \
         --quiet
         ```

        Cloud Run only supports automatic base images that use [Google Cloud's
        buildpacks base
        images](https://docs.cloud.google.com/docs/buildpacks/base-images).

        *   To deploy from source using a Dockerfile, run the following command:

         ```bash
          gcloud run deploy SERVICE_NAME --source . --quiet
         ```
            When you provide a Dockerfile, Cloud Build runs it in the cloud, and
            deploys the service.

*   Deploy from source without build (Preview): This option deploys artifacts
    directly to Cloud Run, bypassing the Cloud Build step. This allows for rapid
    deployment times. To deploy from source without build, run the following
    command:

    ```bash
    gcloud beta run deploy SERVICE_NAME \
     --source APPLICATION_PATH \
     --no-build \
     --base-image=BASE_IMAGE \
     --command=COMMAND \
     --args=ARG \
     --quiet
    ```

    Replace the following:

    *   SERVICE_NAME: the name of your Cloud Run service.
    *   APPLICATION_PATH: the location of your application on the local file
        system.
    *   BASE_IMAGE: the [runtime base image](https://docs.cloud.google.com/run/docs/configuring/services/runtime-base-images#how_to_obtain_base_images)
    you want to use for your application. For example,
        `us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24`.
        You can also deploy a pre-compiled binary without configuring additional
        language-specific runtime components using the OS only base image, such
    as `osonly24`.
    *   COMMAND: the command that the container starts up with.
    *   ARG: an argument you send to the container command. If you use multiple
    arguments, specify each on its own line.

    For examples on deploying from source without build, see [Examples of
        deploying from source without
        build](https://docs.cloud.google.com/run/docs/deploying-source-code#examples-without-build).

## Create and execute a Cloud Run job

To create a new job, run the following command:

```bash
gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet
```

Alternatively, use the deploy command:

```bash
gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS --quiet
```

Replace the following:

*   JOB_NAME: the name of the job you want to create. If you omit this
    parameter, you will be prompted for the job name when you run the command.
*   IMAGE_URL: a reference to the container image—for example,
    `us-docker.pkg.dev/cloudrun/container/job:latest`.

*   Optionally, replace OPTIONS with any of the following flags:

    *   `--tasks`: Accepts integers greater or equal to 1. Defaults to 1;
        maximum is 10,000. Each task is provided the environment variables
        `CLOUD_RUN_TASK_INDEX` with a value between 0 and the number of tasks
        minus 1, along with `CLOUD_RUN_TASK_COUNT`, which is the number of
        tasks.
    *   `--max-retries`: The number of times a failed task is retried. Once any
        task fails beyond this limit, the entire job is marked as failed. For
        example, if set to 1, a failed task will be retried once, for a total of
        two attempts. The default is 3. Accepts integers from 0 to 10.
    *   `--task-timeout`: Accepts a duration like "2s". Defaults to 10 minutes;
        maximum is 168 hours (7 days). For tasks using GPUs, the maximum
        available timeout is 1 hour.
    *   `--parallelism`: The maximum number of tasks that can execute in
        parallel. By default, tasks will be started as quickly as possible in
        parallel.
    *   --execute-now: If set, immediately after the job is created, a job
        execution is started. Equivalent to calling `gcloud run jobs create`
        followed by `gcloud run jobs execute`.

    In addition to these preceding options, you also specify more configuration
    such as environment variables or memory limits.

For a full list of available options when creating a job, refer to the [`gcloud
run jobs
create`](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs/create)
command line documentation.

Wait for the job creation to finish. You'll see a success message upon a
successful completion.

To execute an existing job, run the following command:

```bash
gcloud run jobs execute JOB_NAME --quiet
```

If you want the command to wait until the execution completes, run the following
command:

```bash
gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet
```

Replace the following:

*   JOB_NAME: the name of the job.
*   REGION: the region in which the resource can be found. For example,
    `europe-west1`. Alternatively, set the `run/region` property.

## Deploy a worker pool

You can deploy a Cloud Run worker pool using container images or deploy directly
from the source.

### Deploy a container image

You can specify a container image with a tag (for example,
`us-docker.pkg.dev/my-project/container/my-image:latest`) or with an exact
digest (for example,
`us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...`).

### Supported container images

You can directly use container images stored in the [Artifact
Registry](https://docs.cloud.google.com/artifact-registry/docs/overview), 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)
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).

You should only consider [Docker Hub](https://hub.do

… (truncated)