cloud-run-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Run Basics

Cloud Run 基础知识

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:

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.
Jobs: Executes parallelizable tasks that are executed manually, or on a schedule, and run to completion.
Worker pools: Handles always-on background workloads such as pull-based workloads, for example, Kafka consumers, Pub/Sub pull queues, or RabbitMQ consumers.

Cloud Run是一个完全托管的应用平台，可在Google高度可扩展的基础设施上运行您的代码、函数或容器。它抽象了基础设施管理，提供三种主要资源类型：

Services：响应发送至唯一且稳定端点的HTTP请求，使用基于多种关键指标自动扩缩容的无状态实例，同时也可响应事件和函数。
Jobs：执行可并行化的任务，可手动触发或按计划执行，且会运行至完成。
Worker pools：处理持续运行的后台工作负载，例如基于拉取的工作负载，如Kafka消费者、Pub/Sub拉取队列或RabbitMQ消费者。

Prerequisites

前提条件

Enable the Cloud Run Admin API and Cloud Build APIs:

bash

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

If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

启用Cloud Run Admin API和Cloud Build API：

bash

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

如果您的项目处于限制未认证调用的域限制组织策略下，您需要按照测试私有服务中的描述访问已部署的服务。

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

Replace

PROJECT_ID

with your Google Cloud project ID and

SERVICE_ACCOUNT_EMAIL_ADDRESS

with the email address of the Cloud Build service account.

部署Cloud Run资源需要以下角色：

项目级别的Cloud Run Admin（
```
roles/run.admin
```
）
项目级别的Cloud Run Source Developer（
```
roles/run.sourceDeveloper
```
）
服务身份级别的Service Account User（
```
roles/iam.serviceAccountUser
```
）
项目级别的Logs Viewer（
```
roles/logging.viewer
```
）

Cloud Build默认使用Compute Engine默认服务账号作为Cloud Build服务账号来构建您的源代码和Cloud Run资源，除非您覆盖此行为。

为了让Cloud Build能够构建您的源代码，请为Cloud Build服务账号授予项目级别的Cloud Run Builder（

roles/run.builder

）角色：

bash

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

将

PROJECT_ID

替换为您的Google Cloud项目ID，

SERVICE_ACCOUNT_EMAIL_ADDRESS

替换为Cloud Build服务账号的邮箱地址。

Deploy a Cloud Run service

部署Cloud Run服务

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.

您可以通过容器镜像部署服务到Cloud Run，也可以使用单个Google Cloud CLI命令直接从源代码部署。

重要规则：任何部署的代码必须监听0.0.0.0（而非127.0.0.1），并使用注入的$PORT环境变量（默认值为8080），否则启动时会崩溃。

Deploy a container image to Cloud Run

将容器镜像部署到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.

Cloud Run在部署期间导入您的容器镜像。只要该镜像被某个服务版本使用，Cloud Run就会保留这份副本。启动新的Cloud Run实例时，不会从容器仓库拉取容器镜像。

Supported container images

支持的容器镜像

You can directly use container images stored in the Artifact Registry, or Docker Hub. Google recommends the use of Artifact Registry since Docker Hub images are cached 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.

You should only consider Docker Hub for deploying popular container images such as Docker Official Images or Docker Sponsored OSS images. For higher availability, Google recommends deploying these Docker Hub images using an Artifact Registry remote repository.

To deploy a container image, run the following command:

bash

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

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.

您可以直接使用存储在Artifact Registry或Docker Hub中的容器镜像。Google推荐使用Artifact Registry，因为Docker Hub镜像的缓存时长最长为一小时。

您也可以通过设置Artifact Registry远程仓库，使用来自其他公共或私有仓库（如JFrog Artifactory、Nexus或GitHub Container Registry）的容器镜像。

仅建议将Docker Hub用于部署热门容器镜像，如Docker官方镜像或Docker赞助的OSS镜像。为了获得更高的可用性，Google建议通过Artifact Registry远程仓库部署这些Docker Hub镜像。

要部署容器镜像，请运行以下命令：

bash

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

替换以下内容：

SERVICE_NAME：您要部署的服务名称。服务名称长度必须不超过49个字符，且在每个区域和项目中必须唯一。如果服务尚不存在，此命令会在部署期间创建该服务。您可以完全省略此参数，但省略后会提示您输入服务名称。
IMAGE_URL：容器镜像的引用，例如
```
us-docker.pkg.dev/cloudrun/container/hello:latest
```
。如果使用Artifact Registry，仓库REPO_NAME必须已创建。URL格式为
```
LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
```
。请注意，如果您不提供
```
--image
```
标志，部署命令会尝试从源代码部署。

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
```
  Cloud Run only supports automatic base images that use Google Cloud's buildpacks base images.
  - To deploy from source using a Dockerfile, run the following command:
  bash
```
 gcloud run deploy SERVICE_NAME --source .
```
```
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
```
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 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.

有两种从源代码部署服务的方式：

带构建的源代码部署（默认）：此选项使用Google Cloud的buildpacks和Cloud Build自动从源代码构建容器镜像，无需在本地安装Docker或设置buildpacks或Cloud Build。默认情况下，Cloud Run使用Cloud Build提供的默认机器类型。
- 要启用自动基础镜像更新并从源代码部署，请运行以下命令：
  bash
```
gcloud run deploy SERVICE_NAME --source . \
--base-image BASE_IMAGE \
--automatic-updates
```
  Cloud Run仅支持使用Google Cloud buildpacks基础镜像的自动基础镜像。
  - 要使用Dockerfile从源代码部署，请运行以下命令：
  bash
```
 gcloud run deploy SERVICE_NAME --source .
```
```
当您提供Dockerfile时，Cloud Build会在云端运行它，并部署服务。
```
不带构建的源代码部署（预览版）：此选项直接将工件部署到Cloud Run，跳过Cloud Build步骤，可实现快速部署。要进行不带构建的源代码部署，请运行以下命令：
bash
```
gcloud beta run deploy SERVICE_NAME \
 --source APPLICATION_PATH \
 --no-build \
 --base-image=BASE_IMAGE \
 --command=COMMAND \
 --args=ARG
```
替换以下内容：
- SERVICE_NAME：您的Cloud Run服务名称。
- APPLICATION_PATH：本地文件系统中应用的位置。
- BASE_IMAGE：您要为应用使用的运行时基础镜像。例如
```
us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24
```
  。您也可以仅使用操作系统基础镜像（如
```
osonly24
```
  ）部署预编译的二进制文件，无需配置额外的语言特定运行时组件。
- COMMAND：容器启动时执行的命令。
- ARG：发送给容器命令的参数。如果使用多个参数，请每行指定一个。
有关不带构建的源代码部署示例，请参阅不带构建的源代码部署示例。

Create and execute a Cloud Run job

创建并执行Cloud Run作业

To create a new job, run the following command:

bash

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

Alternatively, use the deploy command:

bash

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS

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

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

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

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.

要创建新作业，请运行以下命令：

bash

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS

或者，使用部署命令：

bash

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS

替换以下内容：

JOB_NAME：您要创建的作业名称。如果省略此参数，运行命令时会提示您输入作业名称。

IMAGE_URL：容器镜像的引用，例如

us-docker.pkg.dev/cloudrun/container/job:latest

。

可选地，将OPTIONS替换为以下任意标志：
- ```
--tasks
```
  ：接受大于或等于1的整数。默认值为1；最大值为10,000。每个任务会被提供环境变量
```
CLOUD_RUN_TASK_INDEX
```
  （值介于0和任务数减1之间）以及
```
CLOUD_RUN_TASK_COUNT
```
  （任务总数）。
- ```
--max-retries
```
  ：失败任务的重试次数。一旦任何任务超出此限制失败，整个作业会被标记为失败。例如，如果设置为1，失败任务会被重试一次，总共尝试两次。默认值为3。接受0到10之间的整数。
- ```
--task-timeout
```
  ：接受类似"2s"的时长。默认值为10分钟；最大值为168小时（7天）。对于使用GPU的任务，最大可用超时为1小时。
- ```
--parallelism
```
  ：可并行执行的最大任务数。默认情况下，任务会尽快并行启动。
- --execute-now：如果设置，作业创建完成后会立即启动一次作业执行。等效于先调用
```
gcloud run jobs create
```
  ，再调用
```
gcloud run jobs execute
```
  。
除上述选项外，您还可以指定更多配置，如环境变量或内存限制。

有关创建作业的完整可用选项列表，请参阅

gcloud run jobs create

命令行文档。

等待作业创建完成。成功完成后，您会看到成功消息。

要执行现有作业，请运行以下命令：

bash

gcloud run jobs execute JOB_NAME

如果希望命令等待执行完成，请运行以下命令：

bash

gcloud run jobs execute JOB_NAME --wait --region=REGION

替换以下内容：

JOB_NAME：作业名称。
REGION：资源所在的区域。例如
```
europe-west1
```
。或者，设置
```
run/region
```
属性。

Deploy a worker pool

部署工作池

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

您可以使用容器镜像部署Cloud Run工作池，也可以直接从源代码部署。

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

您可以指定带标签的容器镜像（例如

us-docker.pkg.dev/my-project/container/my-image:latest

）或带精确摘要的容器镜像（例如

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, or Docker Hub. Google recommends the use of Artifact Registry since Docker Hub images are cached 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.

To deploy a container image, run the following command:

bash

gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL

Replace the following:

WORKER_POOL_NAME: the name of the worker pool you want to deploy to. If the worker pool does not exist yet, this command creates the worker pool during the deployment. You can omit this parameter entirely, but you will be prompted for the worker pool name if you omit it.
IMAGE_URL: a reference to the container image that contains the worker pool, such as
```
us-docker.pkg.dev/cloudrun/container/worker-pool:latest
```
. Note that if you don't supply the
```
--image
```
flag, the deploy command attempts to deploy from source code.

Wait for the deployment to finish. Upon successful completion, Cloud Run displays a success message along with the revision information about the deployed worker pool.

您可以直接使用存储在Artifact Registry或Docker Hub中的容器镜像。Google推荐使用Artifact Registry，因为Docker Hub镜像的缓存时长最长为一小时。

您也可以通过设置Artifact Registry远程仓库，使用来自其他公共或私有仓库（如JFrog Artifactory、Nexus或GitHub Container Registry）的容器镜像。

要部署容器镜像，请运行以下命令：

bash

gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL

替换以下内容：

WORKER_POOL_NAME：您要部署的工作池名称。如果工作池尚不存在，此命令会在部署期间创建该工作池。您可以完全省略此参数，但省略后会提示您输入工作池名称。
IMAGE_URL：包含工作池的容器镜像引用，例如
```
us-docker.pkg.dev/cloudrun/container/worker-pool:latest
```
。请注意，如果您不提供
```
--image
```
标志，部署命令会尝试从源代码部署。

等待部署完成。成功完成后，Cloud Run会显示成功消息以及已部署工作池的版本信息。

Deploy a worker pool from source

从源代码部署工作池

You can deploy a new worker pool or worker pool revision to Cloud Run directly from source code using a single gcloud CLI command,

gcloud run worker-pools

deploy with the

--source

flag.

The deploy command defaults to source deployment if you don't supply the

--image

--source

flags.

Behind the scenes, this command 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 a worker pool from source, run the following command:

bash

gcloud run worker-pools deploy WORKER_POOL_NAME --source .

Replace

WORKER_POOL_NAME

with the name you want for your worker pool.

您可以使用单个gcloud CLI命令

gcloud run worker-pools deploy

并添加

--source

标志，直接从源代码部署新的工作池或工作池版本到Cloud Run。

如果您不提供

--image

或

--source

标志，部署命令默认使用源代码部署。

在后台，此命令使用Google Cloud的buildpacks和Cloud Build自动从源代码构建容器镜像，无需在本地安装Docker或设置buildpacks或Cloud Build。默认情况下，Cloud Run使用Cloud Build提供的默认机器类型。

要从源代码部署工作池，请运行以下命令：

bash

gcloud run worker-pools deploy WORKER_POOL_NAME --source .

将

WORKER_POOL_NAME

替换为您想要的工作池名称。

What to do if a deployment fails:

部署失败时的处理方法：

IAM/Permission Error: Read iam-security.md.
Crash on Boot / Healthcheck failed: Fetch the logs immediately using
```
gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20
```
to find the exact runtime error.
Native Dependency Error (Node/Python): If using
```
--no-build
```
, switch to
```
--source .
```
(Buildpacks) to compile native extensions properly for Linux.

IAM/权限错误：阅读iam-security.md。
启动崩溃/健康检查失败：立即使用
```
gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20
```
获取日志，查找确切的运行时错误。
原生依赖错误（Node/Python）：如果使用
```
--no-build
```
，切换到
```
--source .
```
（Buildpacks）以正确为Linux编译原生扩展。

Reference Directory

参考目录

Core Concepts: Services vs. Jobs vs. Worker pools, resource model, and auto-scaling behavior for services.
CLI Usage: Essential
```
gcloud run
```
commands for deployment and management.
Client Libraries: Using Google Cloud client libraries to interact with Cloud Run.
MCP Usage: Using the Cloud Run remote MCP server.
Infrastructure as Code: Terraform examples for services, jobs, worker pools, and IAM bindings.
IAM & Security: Roles, service identities, and ingress/egress controls.

If you need product information not found in these references, use the Developer Knowledge MCP server
search_documents
tool.

核心概念：服务、作业与工作池的对比，资源模型，以及服务的自动扩缩容行为。
CLI使用：用于部署和管理的核心
```
gcloud run
```
命令。
客户端库：使用Google Cloud客户端库与Cloud Run交互。
MCP使用：使用Cloud Run远程MCP服务器。
基础设施即代码：服务、作业、工作池和IAM绑定的Terraform示例。
IAM与安全：角色、服务身份和入站/出站控制。

如果在这些参考资料中找不到所需的产品信息，请使用开发者知识MCP服务器的
search_documents
工具。