使用 app.yaml 配置应用

App Engine 中的自定义运行时应用是使用 app.yaml 文件进行配置的,该文件包含 CPU、内存、网络和磁盘资源、扩缩以及环境变量等其他常规设置。

app.yaml 文件简介

app.yaml 文件中指定自定义运行时应用的所有运行时配置,包括版本和网址。该文件充当特定服务版本的部署描述符。 您必须先为应用的 default 服务创建 app.yaml 文件,然后才能为其他服务创建和部署 app.yaml 文件。

您可以为 app.yaml 文件指定一个独特的名称,但还必须使用部署命令指定该文件名。例如,如果您将 app.yaml 文件命名为 service-name-app.yamlapp.flexible.yaml,则必须使用下列任一命令部署您的应用:

gcloud app deploy service-name-app.yaml
gcloud app deploy app.flexible.yaml
您可能只需在相应的 app.yaml 文件中定义几个元素,具体取决于应用服务的复杂程度。下面的示例演示了柔性环境中的简单自定义运行时应用可能需要哪些内容:

runtime: custom
env: flex

语法

app.yaml 文件的语法为 YAML 格式。YAML 格式支持注释,其中任何以井号 (#) 字符开头的行都会被忽略,例如:

# This is a comment.

网址和文件路径格式使用 POSIX 扩展正则表达式语法,但排序元素和排序类除外。支持对分组匹配项的反向引用(例如 \1),另外还支持以下 Perl 扩展:\w \W \s \S \d \D

基本设置

app.yaml 文件可以包含这些常规设置。请注意,其中一些设置是必需的:

名称说明
runtime: custom 此设置是必需的。 它是该应用使用的 App Engine 语言运行时的名称。如要指定自定义运行时,请使用 custom

可以使用其他运行时;如需了解详情,请参阅各语言的文档。

env: flex 选择柔性环境。
service: service_name 在创建服务时是必需的。 对于默认服务是可选的。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。在柔性环境中,服务和版本的总长度不能超过 48 个字符,且首尾不能使用连字符。请为每项服务和每个版本选择唯一的名称。 服务名称和版本名称不得重复。

注意:服务以前称为“模块”。

skip_files

可选。skip_files 元素指定应用目录中的哪些文件不上传到 App Engine。该值要么是正则表达式,要么是正则表达式的列表。上传应用时,与正则表达式匹配的所有文件名都将从要上传的文件列表中删除。

例如,要跳过名称以 .bak 结尾的文件,请添加如下所示的 skip_files 部分:


skip_files:
- ^.*\.bak$

网络设置

您可以在 app.yaml 配置文件中指定网络设置,例如:

network:
  instance_tag: TAG_NAME
  name: NETWORK_NAME
  subnetwork_name: SUBNETWORK_NAME
  session_affinity: true
  forwarded_ports:
    - PORT
    - HOST_PORT:CONTAINER_PORT
    - PORT/tcp
    - HOST_PORT:CONTAINER_PORT/udp

配置网络设置时,您可使用下列选项:

选项 说明
instance_tag 创建服务时,将为该服务的每个实例分配一个具有该名称的标记。在 gcloud 命令中,标记可用于将操作定位到一组实例。例如,请参阅 --source-tags--target-tags 标志在 compute firewalls-create 命令中的使用。
name 创建 Google Compute Engine 网络时,柔性环境中的每个虚拟机实例都将分配到该网络。此设置可用于指定网络名称。请指定简短名称,而不是资源路径(例如,default 而不是 https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default)。如果未指定网络名称,则会将实例分配给项目的默认网络(名称为 default)。如果要指定子网名称,则必须指定网络名称。
subnetwork_name 可选。您可以将网络分段并使用自定义子网。确保指定了网络 name。请指定简短名称,而不是资源路径(例如 default 而不是 https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default)。子网必须与应用位于同一区域。
session_affinity 可选。设置为 true 可将 App Engine 配置为将给定用户的多个顺序请求路由到同一 App Engine 实例,例如在会话期间本地存储用户数据。会话粘性有助于检查 Cookie 的值,从而识别由同一个用户发出的多个请求,然后将所有此类请求定向到同一个实例。如果该实例重新启动、运行状况不佳、过载或在实例数量减少时变得不可用,则会话粘性会遭到破坏,并且系统会将其他请求路由到其他实例。请注意,启用会话粘性可能会影响您的负载平衡设置。此参数在默认情况下处于停用状态。
forwarded_ports 可选。您可以将端口从实例 (HOST_PORT) 转发到 Docker 容器 (CONTAINER_PORT)。如果您只指定了 PORT,则 App Engine 假定它与主机和容器上的端口相同。默认情况下,TCP 和 UDP 流量都会被转发。流量必须直接定向到目标实例的 IP 地址,而不是通过 appspot.com 网域或您的自定义网域。

高级网络配置

您可以将 Compute Engine 网络细分为子网。这样,您就可以启用 VPN 方案,例如访问公司网络中的数据库。

要为 App Engine 应用启用子网,请执行以下操作:

  1. 创建自定义子网

  2. 将网络名称和子网名称添加到您的 app.yaml 文件,如所述。

  3. 要基于静态路由建立简单的 VPN,请为自定义子网创建网关和隧道。 否则,请参阅如何创建其他类型的 VPN

端口转发

通过端口转发,您可以直接连接实例上的 Docker 容器。此流量可以通过任何协议传输。端口转发旨在帮助您处理可能需要连接调试程序或分析器的情况。流量必须直接发送至目标实例的 IP 地址,而不是通过 appspot.com 网域或您的自定义网域转发。

默认情况下,不允许来自网络外部的传入流量通过 Google Cloud Platform 防火墙。 在 app.yaml 文件中指定端口转发后,您必须添加一条防火墙规则,以允许来自您要打开的端口的流量通过。

您可以在 Google Cloud Console 的“网络防火墙规则”页面中指定防火墙规则,也可以使用 gcloud 命令指定。

例如,如果要转发来自端口 2222 的 TCP 流量,请执行以下操作:

  1. app.yaml 的网络设置中,添加以下内容:

    network:
      forwarded_ports:
        - 2222/tcp
    
  2. 通过 Cloud Console 或使用 gcloud compute firewall-rules create 指定防火墙规则,以允许来自任意来源的流量 (如 0.0.0.0/0) 和来自 tcp:2222 的流量通过。

资源设置

这些设置可控制计算资源。App Engine 会根据您指定的 CPU 数量和内存容量分配机器类型。系统会保证该机器的资源至少达到您指定的水平(可能会更高)。

您最多可在资源设置中指定 8 个卷的 tmpfs。随后,您就能启用需要通过 tmpfs 共享内存的工作负载,还能提升文件系统 I/O。

例如:

resources:
  cpu: 2
  memory_gb: 2.3
  disk_size_gb: 10
  volumes:
  - name: ramdisk1
    volume_type: tmpfs
    size_gb: 0.5

配置资源设置时,您可使用以下选项:

选项 说明 默认值
cpu 核心数;它必须是 1 或者介于 2 到 96 之间的偶数。 1 个核心
memory_gb

RAM 以 GB 为单位。应用请求的内存,不包含某些进程的开销所需的〜0.4 GB 内存。每个 CPU 核心需要的总内存介于 0.9 到 6.5 GB 之间。

要计算所请求的内存,请使用以下公式:

memory_gb = cpu * [0.9 - 6.5] - 0.4

在上述示例中,您指定了 2 个核心,因此您可请求的内存容量介于 1.4 到 12.6 GB 之间。可供应用使用的内存总容量由运行时环境设置为环境变量 GAE_MEMORY_MB

0.6 GB
disk_size_gb 大小(以 GB 为单位)。最小值为 10 GB,最大值为 10240 GB。 10 GB
name 如果使用卷,则此选项必需。卷的名称。名称必须是唯一的,并且长度介于 1 到 63 个字符之间。字符可以是小写字母、数字或短划线。第一个字符必须是字母,最后一个字符不能是短划线。该卷在应用容器中以 /mnt/NAME 的形式装载。
volume_type 如果使用卷,则此选项必需。必须为 tmpfs
size_gb 如果使用卷,则此选项必需。卷的大小(以 GB 为单位)。最小值为 0.001 GB,最大值为应用程序容器和底层设备上的可用内存量。Google 不会在您的系统中添加额外的 RAM 来满足磁盘需求。要从应用容器可用的内存中减去为 tmpfs 卷分配的 RAM。精确度由系统而定。

分组运行状况检查

分组运行状况检查默认启用。您可以通过定期运行状况检查请求确认虚拟机实例是否已成功部署,并检查正在运行的实例是否保持正常运行状态。每个运行状况检查都必须在指定的时间间隔内获得响应。

如果连续多个运行状况检查请求都未能得到实例的响应,当达到指定数量时,该实例会被判定为运行状况不佳。如果某实例处于非活动状态,则该实例将重启。如果某实例未准备就绪,则它收不到任何客户端请求。如果没有空闲的磁盘空间,运行状况检查也会失败。

您可使用以下两种运行状况检查:

  • 活动性检查会确认虚拟机和 Docker 容器是否正在运行。App Engine 会重启运行状况不佳的实例。
  • 就绪性检查会确认实例是否准备好接受传入请求。未通过就绪性检查的实例不会添加到可用实例池中。

默认情况下,来自运行状况检查的 HTTP 请求不会转发到您的应用容器。如果要将运行状况检查范围扩展到您的应用,请为活跃性检查就绪性检查指定路径。如果应用返回 200 OK 响应代码,则对应用的自定义运行状况检查会被视为成功。

活动性检查

活动性检查会确认虚拟机和 Docker 容器是否正在运行。 被视为运行状况欠佳的实例会重启。

您可以通过向 app.yaml 文件中添加可选的 liveness_check 部分来自定义活跃性检查请求,例如:

liveness_check:
  path: "/liveness_check"
  check_interval_sec: 30
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2

以下设置适用于活动性检查:

字段 默认值 范围(最小值-最大值) 说明
path 如果您希望将活跃性检查转发到您的应用容器,请指定网址路径,例如 "/liveness_check"
timeout_sec 4 秒 1-300 每个请求的超时间隔,以秒为单位。
check_interval_sec 30 秒 1-300 两次检查之间的时间间隔,以秒为单位。 请注意,该值必须大于 timeout_sec。
failure_threshold 4 次检查 1-10 如果某实例未通过此连续检查次数,则表示该实例运行状况欠佳。
success_threshold 2 次检查 1-10 在成功通过此连续检查次数之后,运行状况欠佳的实例将重新变为运行状况良好。
initial_delay_sec 300 秒 0-3600 实例启动后的延迟(以秒为单位),启动期间会忽略运行状况检查响应。 此设置适用于每个新建实例,并且可以为新实例留出更多时间,供其进行启动并进入运行状态。此设置会延迟自动修复功能进行检查的时间,并可能会在实例正在启动的情况下提前重新创建实例。初始延迟计时器从实例处于 RUNNING 模式时开始计时。例如,如果您的应用需要执行很长时间的初始化任务才能做好处理流量的准备,则可能需要增加延迟。

就绪性检查

就绪性检查会确认实例能否接受传入的请求。 未通过就绪性检查的实例不会添加到可用实例池中。

您可以通过向 app.yaml 文件添加可选的 readiness_check 部分来自定义运行状况检查请求,例如:

readiness_check:
  path: "/readiness_check"
  check_interval_sec: 5
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2
  app_start_timeout_sec: 300

以下设置适用于就绪性检查:

字段 默认值 范围(最小值-最大值) 说明
path 如果您希望将就绪性检查转发到应用容器,请指定网址路径,例如 "/readiness_check"
timeout_sec 4 秒 1-300 每个请求的超时间隔,以秒为单位。
check_interval_sec 5 秒 1-300 两次检查之间的时间间隔,以秒为单位。 请注意,该值必须大于 timeout_sec。
failure_threshold 2 次检查 1-10 如果某实例未通过此连续检查次数,则表示该实例运行状况欠佳。
success_threshold 2 次检查 1-10 在成功通过此连续检查次数之后,运行状况欠佳的实例将变为运行状况良好。
app_start_timeout_sec 300 秒 1-1800 此设置适用于新部署,而不是单个虚拟机。它指定部署中足够数量的实例通过运行状况检查所允许的最长时间(以秒为单位)。如果超出此时间,则部署将失败并回滚。 配置好 Compute Engine 实例并创建负载平衡器后端服务后,计时器开始计时。 例如,如果您希望在部署期间提供更长时间的超时以使足够数量的实例正常运行,则可能需要增加超时时间。

运行状况检查频率

为确保高可用性,App Engine 会为每个运行状况检查程序创建冗余副本。如果某个运行状况检查程序失败,冗余副本可以立即接管该程序,无任何延迟。

如果检查应用程序的 nginx.health_check 日志,可能会发生比配置更频繁的运行状态查询,因为多余的运行状况检查程序也在遵循您的设置。这些冗余运行状况检查程序是由系统自动创建,您无法配置。

服务扩缩设置

用于控制服务扩缩的密钥取决于您为该服务分配的扩缩类型。

您可以使用自动扩缩或手动扩缩。默认使用自动扩缩。

自动扩缩

您可以通过将 automatic_scaling 部分添加到 app.yaml 文件来配置自动扩缩。例如:

automatic_scaling:
  min_num_instances: 1
  max_num_instances: 15
  cool_down_period_sec: 180
  cpu_utilization:
    target_utilization: 0.6
  target_concurrent_requests: 100

下表列出了可用于自动扩缩的设置:

名称 说明
automatic_scaling 默认采用自动扩缩。 若要指定任何自动扩缩设置,请添加此行。
min_num_instances 为您的服务提供的实例数下限。 服务在部署时,会获得此数量的实例并根据流量进行扩缩。 必须为 1 或更大值,默认为 2 以减少延迟。
max_num_instances 您的服务可扩展至的实例数上限。 项目的最大实例数量受项目的资源配额限制。 默认值为 20
cool_down_period_sec 自动扩缩程序在开始从新实例收集信息之前应该等待的秒数。 这可以防止自动扩缩程序在实例初始化期间收集信息,在此期间收集的使用数据并不可靠。冷却期必须大于或等于 60 秒。 默认为 120
cpu_utilization 如果要指定目标 CPU 利用率,请使用此标头。
target_utilization 目标 CPU 利用率。 CPU 利用率是所有正在运行的实例的平均利用率,用于决定何时加减实例数量。请注意,在实例收到关停信号后的 25 秒,无论进行中的请求数为何,实例都会缩减。默认为 0.5
target_concurrent_requests 测试版)针对每个实例定位并发请求。所有正在运行的实例的平均并发请求数用于确定何时减少或增加实例数。请注意,在实例收到关停信号 25 秒后,无论进行中的请求数为何,实例都会缩减。如果未指定其值,则无效。

手动扩缩

您可以通过向 app.yaml 文件添加 manual_scaling 部分来配置手动调节。例如:

manual_scaling:
  instances: 5

下表列出了可用于手动扩缩的设置:

名称说明
manual_scaling 需要此设置才能为服务启用手动扩缩。
instances 要分配给服务的实例数。

定义环境变量

您可以在 app.yaml 中定义环境变量,使其适用于您的应用,例如:

env_variables:
  MY_VAR: "my value"

其中,MY_VARmy value 是您要定义的环境变量的名称和值,每个环境变量条目在 env_variables 元素下缩进两个空格。