容器运行时合同

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页面列出了 Cloud Run 中容器的主要要求和行为。Cloud Run 服务和 Cloud Run 作业之间存在一些差异:我们会对存在差异的地方进行说明。

支持的语言和映像

您的容器映像可以运行以您选择的编程语言编写的代码并使用任何基础映像,前提是该映像遵循本页面中列出的限制条件。

必须针对 Linux 64 位编译容器映像中的可执行文件。Cloud Run 明确支持 Linux x86_64 ABI 格式。

Cloud Run 接受 Docker Image Manifest V2、架构 1架构 2OCI 映像格式的容器映像。

不支持用于多架构映像清单列表

侦听正确的端口上的请求(服务)

对于 Cloud Run 服务,容器必须在请求发送到的端口上的 0.0.0.0 上侦听请求。默认情况下,请求将发送到 8080,但您可以配置 Cloud Run 以将请求发送到您选择的端口。Cloud Run 会将 PORT 环境变量注入容器中。在 Cloud Run 容器实例内部,PORT 环境变量的值始终反映请求发送到的端口。默认值为 8080

作业执行中运行的容器必须在完成时退出

对于 Cloud Run 作业,容器必须在作业成功完成时退出并显示退出代码 0,在作业失败时退出则显示非零退出代码。

由于作业不应响应请求,因此容器不应侦听端口或启动网络服务器。

传输层加密 (TLS)

容器不应直接实现任何传输层安全。应由 Cloud Run 为 HTTPS 和 gRPC 终止 TLS,之后将请求以 HTTP/1 或 gRPC 形式通过代理转发到不具备 TLS 的容器。

如果您将 Cloud Run 服务配置为使用 HTTP/2 端到端连接,则容器必须处理 HTTP/2 明文 (h2c) 格式的请求,因为 TLS 仍会被 Cloud Run 自动终止。

响应(服务)

对于 Cloud Run 服务,容器实例必须在收到请求后,于请求超时设置中指定的时间内(包括容器实例启动时间)发送响应。否则,请求将结束并返回 504 错误。

环境变量

Cloud Run 服务和作业具有不同的环境变量。

服务的环境变量

以下环境变量会自动添加到正在运行的容器中:

名称 说明 示例
PORT 您的 HTTP 服务器应侦听的端口。 8080
K_SERVICE 正在运行的 Cloud Run 服务的名称。 hello-world
K_REVISION 正在运行的 Cloud Run 修订版本的名称。 hello-world.1
K_CONFIGURATION 创建了该修订版本的 Cloud Run 配置的名称。 hello-world

作业的环境变量

对于 Cloud Run 作业,系统会设置以下环境变量:

名称 说明 示例
CLOUD_RUN_JOB 正在运行的 Cloud Run 作业的名称。 hello-world
CLOUD_RUN_EXECUTION 正在运行的 Cloud Run 执行的名称。 hello-world-abc
CLOUD_RUN_TASK_INDEX 对于每个任务,该值设置为 0 到“任务数减去 1”之间的唯一值。 0
CLOUD_RUN_TASK_ATTEMPT 此任务已经重试的次数。从 0 开始(表示第一次尝试),然后每次连续重试时递增 1,上限为最大重试值。 0
CLOUD_RUN_TASK_COUNT --tasks 参数中定义的任务数。 1

请求和响应标头要求(服务)

对于 Cloud Run 服务,标头名称仅限于可打印的非空格 ASCII,且不能包含英文冒号。根据 IETF RFC 7230 的规定,标头值仅限于可见的 ASCII 字符,以及空格和水平制表符

文件系统访问

容器的文件系统是可写的,并且受以下行为的约束:

  • 这是一个内存中文件系统,因此向其中写入数据会使用容器实例的内存。
  • 停止容器实例时,写入文件系统的数据不会保留。

容器实例生命周期

Cloud Run 作业和服务的生命周期特征不同,因此以下各子部分分别介绍了这些特征。

对于服务

以下内容仅适用于服务。

服务扩缩

对于 Cloud Run 服务,为响应传入请求,服务会自动扩容到特定数量的容器实例,每个实例都运行已部署的容器映像。

当修订版本未收到任何流量时,它会缩减为配置的容器实例数下限(默认为零)。

启动

对于 Cloud Run 服务,容器实例必须在启动后的 4 分钟内侦听请求。在此启动期间,系统会向容器实例分配 CPU。 您可以启用启动 CPU 加速,在容器实例启动期间临时增加 CPU 分配,以缩短启动延迟时间。

一旦容器实例侦听已配置的端口,请求就会立即发送到容器实例。

等待容器实例启动的请求将在队列中保留最多 10 秒。

您可以配置启动探测以确定容器是否已启动并已准备好处理请求。

处理请求

对于 Cloud Run 服务,当容器实例处理至少一个请求时,系统始终会分配 CPU。

空闲

对于 Cloud Run 服务,空闲容器实例是指未处理任何请求的实例。

分配给空闲容器实例的 CPU 取决于所配置的 CPU 分配

除非容器实例因容器实例数下限配置设置而必须保持空闲状态,否则它将保持空闲状态超过 15 分钟。

关停

对于 Cloud Run 服务,空闲容器实例可以随时关停,包括通过最少数量的实例保持备用状态的容器实例。在关停正在处理请求的容器实例时,新的传入请求会被路由到其他实例,而当前正在处理的请求则会给予一定时间让其完成。

在关停容器实例之前,Cloud Run 会发送一个 SIGTERM 信号,指示实例将于 10 秒后进行实际的关停,届时 Cloud Run 则会发送一个 SIGKILL 信号。在此期间,系统会为容器实例分配 CPU 并计费。如果容器实例未捕获到 SIGTERM 信号,则会立即关停。(请参阅代码示例,了解如何捕获 SIGTERM 信号。)

强制终止

如果 Cloud Run 容器实例超出允许的内存限制,则该容器实例会被终止。所有仍在该容器实例上处理的请求都会被终止并显示 HTTP 500 错误。

对于作业

对于 Cloud Run 作业,容器实例会一直运行,直到容器实例退出、达到任务超时或容器崩溃。如果容器实例未捕获到 SIGTERM 信号,则会立即关停。(请参阅代码示例,了解如何捕获 SIGTERM 信号。)

强制终止

如果 Cloud Run 容器实例超出允许的内存限制,则该容器实例会被终止。所有仍在该容器实例上处理的请求都会被终止并显示 HTTP 500 错误。

如果任务超出任务超时,Cloud Run 会发送“SIGTERM”信号,指示容器实例将于 10 秒后实际关停,届时 Cloud Run 会发送 SIGKILL 信号,关闭容器实例。

在此期间,容器实例在整个生命周期中都会被分配 CPU 并计费。

容器实例资源

CPU

默认情况下,系统会为每个 Cloud Run 容器实例分配已配置vCPU(默认为 1 个)。

vCPU 是底层硬件的抽象,可提供可变 CPU 平台上单个硬件超线程的大致等效 CPU 时间。 Cloud Run 使用的所有 CPU 平台都支持 AVX2 指令集。请注意,容器合同不包含任何其他 CPU 平台详细信息。

容器实例可以同时在多个核心上执行。

对于 Cloud Run 服务,您可以指定 CPU 始终在实例的生命周期内分配,或仅在容器实例启动和请求处理期间分配。如需了解详情,请参阅 CPU 分配

如果您配置了一些最少的实例,则这些实例也受 CPU 分配配置的约束。

您可以启用启动 CPU 加速,在容器实例启动期间临时增加 CPU 分配,以缩短启动延迟时间。

内存

默认情况下,系统会为每个 Cloud Run 容器实例分配已配置的内存(默认为 512 MiB)。

内存的典型用途包括:

  • 将代码加载到内存中以运行服务
  • 写入文件系统
  • 在容器中运行的额外进程(例如 nginx 服务器)
  • PHP OpCache 等内存缓存系统
  • 每个请求的内存用量

并发(服务)

对于 Cloud Run 服务,每个 Cloud Run 容器实例默认设置为多个并发,其中每个容器实例可以同时接收多个请求。您可以通过设置并发来更改此设置。

容器实例沙盒

如果您使用第一代执行环境,则会使用 gVisor 容器运行时沙盒对 Cloud Run 容器实例进行沙盒化。如 gVisor syscall 兼容性参考文档中所述,此容器沙盒可能不支持某些系统调用。

如果您使用第二代执行环境,则可完全兼容 Linux。Cloud Run 作业始终使用第二代执行环境。在第二代执行环境中,/sys/class/dmi/id/product_name 设置为 Google Compute Engine

容器实例元数据服务器

Cloud Run 容器实例公开一个元数据服务器,您可以使用该服务器检索容器实例的详细信息,例如项目 ID、区域、实例 ID 或服务帐号。它还可用于为运行时服务帐号生成令牌

您可以使用具有 Metadata-Flavor: Google 标头的 http://metadata.google.internal/ 端点进行简单的 HTTP 请求,从元数据服务器访问此数据:不需要客户端库。如需了解详情,请参阅获取元数据

下表列出了部分可用的元数据服务器信息:

路径 说明
/computeMetadata/v1/project/project-id Cloud Run 服务或作业所属项目的 ID
/computeMetadata/v1/project/numeric-project-id Cloud Run 服务或作业所属项目的编号
/computeMetadata/v1/instance/region 此 Cloud Run 服务或作业所在的区域,返回 projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id 容器实例的唯一标识符(也可在日志中提供)。
/computeMetadata/v1/instance/service-accounts/default/email 此 Cloud Run 服务或作业的运行时服务帐号的电子邮件地址。
/computeMetadata/v1/instance/service-accounts/default/token 此 Cloud Run 服务或作业的服务帐号生成 OAuth2 访问令牌。Cloud Run 服务代理用于提取令牌。此端点将返回包含 access_token 属性的 JSON 响应。详细了解如何提取和使用此访问令牌。

请注意,Cloud Run 不会提供容器实例运行所在的 Google Cloud 可用区的详细信息。因此,元数据特性 /computeMetadata/v1/instance/zone 始终返回 projects/PROJECT-NUMBER/zones/REGION-1

文件名

容器中使用的文件名必须与 UTF-8 兼容:UTF-8 或可以安全自动转换为 UTF-8 的内容,否则容器映像可能无法部署。此限制仅适用于文件名:对文件内容中使用的字符编码没有限制。

如果将文件名与其他编码一起使用,则必须将这些文件名转换为 UTF-8 格式,然后再尝试部署。

出站请求超时

对于 Cloud Run 服务,从容器到 VPC 的请求在空闲时间达到 10 分钟后超时。对于从容器到互联网的请求,空闲时间达到 20 分钟后超时。