Google Cloud Run Python 客户端(google-cloud-run 0.15.0)控制平面自动化实战指南
Google Cloud Run Python 客户端(google-cloud-run 0.15.0)控制平面自动化实战指南
导读
本文以 Context Hub 仓库中维护的 Cloud Run Python 文档 为主体,系统讲解如何使用 google-cloud-run 0.15.0 包通过 Python 对 Google Cloud Run 进行控制平面(control-plane)自动化:创建与管理 Service、Job、Execution、Task、Revision 以及 Worker Pool 等资源。读完本文,你将掌握 ADC 认证配置、客户端初始化、基于 long-running operation 的服务与任务生命周期管理、update mask 局部更新、异步客户端用法,以及常见陷阱与版本敏感信息,能够直接编写可运行的 Cloud Run 自动化脚本。
一、Golden Rule:控制平面自动化,而非运行时替换
google-cloud-run 的定位非常明确:它是 Cloud Run 控制平面的管理 SDK,不是容器运行时契约的替代品。在使用之前必须分清两条边界:
- 它能做什么:管理 Cloud Run 资源——Services(服务)、Jobs(任务)、Executions(执行)、Tasks(任务实例)、Revisions(修订版本)和 Worker Pools(工作池)的创建、查询、更新与删除,以及触发任务执行。
- 它不做什么:它不会替你部署源码,也不负责容器内部的请求处理。你部署的应用仍然需要在容器中监听预期端口并正常处理请求(即满足 Cloud Run 运行时契约);资源模板里必须显式给出容器镜像或其它受支持的部署产物。
认证方面,文档给出的默认路径是 Application Default Credentials(ADC),而不是手写 token 或 API Key:
- 本地开发:执行
gcloud auth application-default login,并导出GOOGLE_CLOUD_PROJECT与GOOGLE_CLOUD_LOCATION两个环境变量。 - 显式需要文件凭证时:将
GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 密钥文件路径。 - 硬编码的访问令牌和提交到仓库里的服务账号密钥是错误的默认做法。
二、安装与版本固定
文档给出的标准安装流程(建议在虚拟环境中进行):
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "google-cloud-run==0.15.0"
常见替代方案同样支持固定版本号:
uv add "google-cloud-run==0.15.0"
poetry add "google-cloud-run==0.15.0"
注意固定版本(==0.15.0)的重要性:本文档 frontmatter 中声明的版本为 versions: "0.15.0"(见 DOC.md 头部元数据),所有 API 形状、参数与示例都以该版本为准。当前仓库同时维护了 Node.js 版本(@google-cloud/run 3.2.0)的 JavaScript 文档,两者按语言拆分为不同目录,遵循 内容指南 中"多语言文档使用 author/docs/entry-name/language/DOC.md 子目录"的约定。
三、认证与客户端初始化
Cloud Run 使用 Google Cloud 的标准认证体系,从 ADC 起步而不是手工拼装 token:
# 本地开发:登录并写入 ADC 默认凭证
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="my-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
当明确需要文件型凭证(如 CI 或本地脚本)时:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
基本客户端初始化:
import os
from google.cloud import run_v2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
parent = f"projects/{project_id}/locations/{location}"
services_client = run_v2.ServicesClient()
jobs_client = run_v2.JobsClient()
这里有一个值得注意的设计细节:location 通过 os.environ.get(..., "us-central1") 带默认值,而 project_id 使用 os.environ[...] 强制要求设置。这是为了避免脚本在未显式指定项目时静默操作错误的 GCP 环境——文档在 Configuration Notes 中同样强调:"导出 GOOGLE_CLOUD_PROJECT 和你部署的区域,避免脚本静默修改错误的区域"。
如果需要自定义端点或 universe domain(如 VPC 内网端点、非公开数据中心场景),可以通过 client_options 传入。生成客户端在 client_options 上暴露了 api_endpoint 与 universe_domain 设置:
from google.cloud import run_v2
from google.api_core.client_options import ClientOptions
client = run_v2.ServicesClient(
client_options=ClientOptions(
api_endpoint="run.googleapis.com",
universe_domain="googleapis.com",
)
)
四、客户端体系(Client Surface)
包按 API 领域组织为多个专用客户端:
| 客户端 | 职责 |
|---|---|
ServicesClient / ServicesAsyncClient |
Service 的增删改查 |
JobsClient / JobsAsyncClient |
Job 的增删改查与执行触发 |
ExecutionsClient |
查询 Job 执行产生的 Execution |
TasksClient |
查询 Execution 内部的 Task |
RevisionsClient |
查询 Service 的修订版本 |
WorkerPoolsClient |
Worker Pool 管理 |
BuildsClient |
构建相关操作 |
使用原则很清晰:用 ServicesClient 做服务 CRUD,用 JobsClient 做任务 CRUD 和执行触发;当需要检查这些操作产生的衍生资源(Execution、Task、Revision)时,再使用对应的 follow-on 客户端,而不是试图从原始的 Service/Job 资源对象上推断执行状态。
五、服务(Service)管理实战
5.1 列出与查询服务
列出服务使用 location 级 parent,查询单个服务则使用完整资源名(full resource name):
import os
from google.cloud import run_v2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
client = run_v2.ServicesClient()
parent = f"projects/{project_id}/locations/{location}"
# 列出:返回可迭代的服务集合
for service in client.list_services(parent=parent):
print(service.name, list(service.urls))
# 查询单个:使用 client 提供的 resource path 辅助方法
service_name = client.service_path(project_id, location, "hello-service")
service = client.get_service(name=service_name)
print(service.name)
print(list(service.urls))
注意 service_path() 这类辅助方法的存在意义:它帮你按 projects/{project}/locations/{location}/services/{service} 的模式拼出正确资源名,避免手写字符串出错。文档在 Configuration Notes 中明确建议:"需要资源名字符串时,优先使用 service_path()、job_path() 等客户端辅助方法"。
5.2 创建服务
Cloud Run 的变更类操作都是 long-running operation(长时间运行的操作)——创建、更新、删除、执行调用都不会同步完成,必须调用 .result() 等待操作结束,才能假定资源已经存在:
import os
from google.cloud import run_v2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
parent = f"projects/{project_id}/locations/{location}"
client = run_v2.ServicesClient()
service = run_v2.Service(
template=run_v2.RevisionTemplate(
service_account="runtime-sa@my-project.iam.gserviceaccount.com",
containers=[
run_v2.Container(
image="us-docker.pkg.dev/cloudrun/container/hello",
env=[run_v2.EnvVar(name="APP_ENV", value="prod")],
)
],
)
)
operation = client.create_service(
parent=parent,
service=service,
service_id="hello-service",
)
created = operation.result()
print(created.name)
print(list(created.urls))
几个结构要点:
run_v2.Service.template是RevisionTemplate,它描述的是"这个服务用什么样的 Revision 模板来跑"。RevisionTemplate.containers是容器列表,每个Container必须指定镜像地址(image),可以附加环境变量env列表(run_v2.EnvVar(name=..., value=...))与启动参数args。service_account指定容器运行时使用的服务账号(runtime service account),应具备拉取镜像与访问所依赖 GCP 资源的权限。create_service返回 operation,必须.result()才能拿到创建完成的Service对象。
5.3 使用 update mask 更新服务
部分更新(patch)必须携带 FieldMask,只有 update mask 中列出的路径会被应用。这一点对自动化脚本(尤其是 Agent 场景)极其重要——文档特别警告:"没有 update mask 时,Agent 往往以为本地改动的对象会自动同步到服务端状态,但实际上不会"。
import os
from google.cloud import run_v2
from google.protobuf import field_mask_pb2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
client = run_v2.ServicesClient()
service_name = client.service_path(project_id, location, "hello-service")
service = client.get_service(name=service_name)
# 在内存中修改对象
service.template.containers[0].env.append(
run_v2.EnvVar(name="FEATURE_FLAG", value="on")
)
# 只更新 template.containers 这一个路径
update_mask = field_mask_pb2.FieldMask(paths=["template.containers"])
updated = client.update_service(
service=service,
update_mask=update_mask,
).result()
print(updated.name)
工作流是标准的"先 get、再改内存对象、最后带 mask patch"三步:get_service 拿回当前状态 → 修改 service.template.containers[0].env → update_service 只应用 template.containers 路径。这样既能避免整对象覆盖造成的意外变更,也节省请求负载。
六、任务(Job)管理实战
6.1 创建并运行任务
Job 与 Service 是相互独立的资源类型。Job 使用 ExecutionTemplate 定义执行模板,其中内嵌 TaskTemplate 描述每个任务实例的容器配置;task_count 控制每次执行产生的任务实例数量。
import os
from google.cloud import run_v2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
parent = f"projects/{project_id}/locations/{location}"
client = run_v2.JobsClient()
job = run_v2.Job(
template=run_v2.ExecutionTemplate(
task_count=1,
template=run_v2.TaskTemplate(
service_account="runtime-sa@my-project.iam.gserviceaccount.com",
containers=[
run_v2.Container(
image="us-docker.pkg.dev/my-project/batch/worker:latest",
args=["--mode", "daily"],
env=[run_v2.EnvVar(name="APP_ENV", value="prod")],
)
],
),
)
)
created = client.create_job(
parent=parent,
job=job,
job_id="daily-job",
).result()
execution = client.run_job(name=created.name).result()
print(execution.name)
关键语义:
create_job返回 operation,.result()后得到Job。run_job(name=created.name)是触发执行的方法,它同样返回 operation,但其结果是一个Execution——这就是"用 follow-on 客户端检查执行状态"的数据来源。- 容器
args可以携带批处理任务的命令行参数(如["--mode", "daily"]),配合环境变量完成一次典型的批处理任务定义。
6.2 检查执行与任务
执行(Execution)和任务(Task)是 Job 运行后产生的衍生资源,应使用 ExecutionsClient 与 TasksClient 查询,而不是从 Job 对象上推断执行状态:
from google.cloud import run_v2
executions = run_v2.ExecutionsClient()
tasks = run_v2.TasksClient()
job_name = "projects/my-project/locations/us-central1/jobs/daily-job"
execution_parent = f"{job_name}/executions"
# 列出该 Job 名下的所有 Execution
for execution in executions.list_executions(parent=execution_parent):
print(execution.name)
# 列出某个 Execution 名下的所有 Task
task_parent = f"{job_name}/executions/my-execution"
for task in tasks.list_tasks(parent=task_parent):
print(task.name)
资源名层级关系为:.../jobs/{job}/executions/{execution}/tasks/{task}。列出 Execution 用 {job_name}/executions 作为 parent,列出 Task 用某个具体的 {execution_name} 作为 parent。
七、异步用法
如果应用其余部分已经是异步架构,文档建议直接使用 async 变体客户端,而不是把同步客户端包在线程池里:
import os
from google.cloud import run_v2
project_id = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
client = run_v2.ServicesAsyncClient()
parent = f"projects/{project_id}/locations/{location}"
async def list_services() -> None:
async for service in client.list_services(parent=parent):
print(service.name)
异步客户端采用 async for 的异步迭代器模式,天然适合与 asyncio 生态(如 FastAPI、aiohttp 应用)融合。ServicesAsyncClient、JobsAsyncClient 对应的也是同一套资源模型,只是调用风格异步化。
八、配置要点汇总
- 资源名遵循标准 Google Cloud 模式:
projects/{project}/locations/{location}/services/{service}、projects/{project}/locations/{location}/jobs/{job}。资源名是区域性的(regional),为us-central1构造的 Service/Job 名不会在europe-west1中解析成功。 - 优先使用辅助方法:
service_path()、job_path()等客户端方法负责拼装资源名字符串,避免手写出错。 - 客户端级配置:生成客户端支持
client_options、credentials、transport以及自定义 retry/timeout 值。文档明确建议使用这些官方入口,而不是去 patch transport 内部实现。 - 环境变量纪律:本地或 CI 自动化时,导出
GOOGLE_CLOUD_PROJECT与目标部署区域,防止脚本静默操作错误的区域。
九、常见陷阱(Common Pitfalls)
- 本包只管理资源,不直接部署源码:资源模板中仍需提供容器镜像或其他受支持的部署产物。
- 务必等待 long-running operation:create、update、delete、run 调用都不会同步完成,必须
.result()(Python)等待结束再读取或假定变更生效。对应的 Node.js 版本文档中同样强调operation.promise()(见 JavaScript 版 DOC.md)。 - 不要混用区域:为
us-central1构造的资源名不会在europe-west1解析成功。 - 部分更新必须带 update mask:否则本地改动不会自动 patch 到服务端。
- ADC 是默认认证路径:硬编码访问令牌、把服务账号密钥提交进仓库都是错误做法。
- 覆盖执行参数或环境变量前先核对请求类型:如果你要覆盖 Job 的执行参数或环境变量,先对照生成的请求类型确认容器名与 override 字段。
- Worker Pool 并非处处可用:客户端面包含 worker-pool API,但不要假设你的目标项目或区域都存在 Worker Pool。
十、版本敏感信息(截至 2026-03-12)
- PyPI 与生成的参考文档均显示
google-cloud-run 0.15.0,本文档即针对该版本编写。 latest文档根下的已发布 changelog 目前只收录到0.14.0,即 release note 的覆盖范围滞后于包版本。如果需要0.15.0的精确变更细节,应核对 PyPI 发布历史或包仓库,不要假设 changelog 页面是完整的。- 生成的 changelog 记录了以下近期行为变化:
0.14.0:当客户端证书可用且未显式禁用 mTLS 时,自动启用 mTLS。0.12.0:废弃了客户端构造函数中的credentials_file辅助参数。0.11.0:包含围绕 worker pools 与 build worker pools 的 breaking changes。
十一、如何在 Context Hub 中获取与使用这份文档
本文档是 Context Hub 内容库的一部分(google/run 条目),面向 Agent 的获取流程与 get-api-docs 技能 保持一致:
chub search "cloud run" --json # 检索条目,得到 id,如 google/run
chub get google/run --lang py # 拉取 Python 语言变体(即本文档)
几个与文档使用相关的实现细节值得了解:
- 语言归一化:CLI 的
--lang接受py、js、ts、rb、cs等短名或全名,py会被归一化为python(见 normalize.js),因此在chub get google/run --lang py中传入短名即可命中本 Python 变体。 - 语言推断与歧义处理:
resolveDocPath(见 registry.js)在条目只有一个语言变体时自动选中;当多个语言变体存在且未指定--lang时,会返回needsLanguage并列出可用语言提示用户补选。本文档与 JavaScript 变体共存,正属于多语言条目。 - 版本选择:未指定版本时,CLI 会选择该语言下的
recommendedVersion;当前google/run的 Python 变体声明版本为 0.15.0,即默认拉取的版本。
附:官方资料入口
文中涉及的行为与参数均以本仓库维护的 Python 版 DOC.md 为准。如需查阅官方参考与发布历史,可访问 Google Cloud 官方文档站点的 Cloud Run Python reference 根页面、Services/Jobs 客户端参考页与 changelog 页面,以及 PyPI 上 google-cloud-run 的包页面;Google Cloud 官方 ADC 指南提供认证配置的权威说明。