app.yaml 配置文件

app.yaml 文件定义了运行时的配置设置以及常规应用、网络和其他资源设置。

请勿将 app.yaml 添加到 .gcloudignore 文件中。部署可能需要 app.yaml，并且将其添加到 .gcloudignore 将导致部署失败。

语法

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

# This is a comment.

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

常规设置

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

名称	说明
`build_env_variables`	可选。如果您使用的是支持 buildpack 的运行时，则可以在 `app.yaml` 文件中定义构建环境变量。如需了解详情，请参阅使用构建环境变量。
`runtime`	必需。应用使用的运行时环境的名称。例如，如需指定运行时环境，请使用：
`env: flex`	必需：选择柔性环境。
`service: service_name`	在创建服务时是必需的。对于默认服务是可选的。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。在柔性环境中，`VERSION-dot-SERVICE-dot-PROJECT_ID` 的组合长度（其中 `VERSION` 是版本名称，`SERVICE` 是服务名称） `PROJECT_ID` 是项目 ID）不得超过 63 个字符，且首尾不能使用连字符。如果您在未指定服务名称的情况下进行部署，则系统会创建默认服务的新版本。如果您使用已存在的服务名称进行部署，则系统会创建该服务的新版本。如果您使用不存在的新服务名称进行部署，则系统会创建新服务和版本。我们建议为每个服务/版本组合使用唯一的名称。注意：服务以前称为“模块”。
`service_account`	可选。借助 `service_account` 元素，您可以将用户管理的服务账号指定为版本的身份。访问其他 Google Cloud 服务和执行任务时，将使用指定的服务账号。服务账号必须按以下格式提供： service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
`skip_files`	可选。`skip_files` 元素指定应用目录中的哪些文件不上传到 App Engine。该值要么是正则表达式，要么是正则表达式的列表。上传应用时，与正则表达式匹配的所有文件名都将从要上传的文件列表中删除。例如，要跳过名称以 `.bak` 结尾的文件，请添加如下所示的 `skip_files` 部分： skip_files: - ^.*\.bak$

网络设置

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

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

配置网络设置时，您可使用下列选项：

选项	说明
`name`	创建 Google Compute Engine 网络时，柔性环境中的每个虚拟机实例都将分配到该网络。此设置可用于指定网络名称。请指定简短名称，而不是资源路径（例如，`default` 而不是 `https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default`）。如果未指定网络名称，则会将实例分配给项目的默认网络（名称为 `default`）。如果要指定子网名称，则必须指定网络名称。
`instance_ip_mode`	可选。如需阻止实例接收临时外部 IP 地址，请将该项设置为 `internal` 并启用专用 Google 访问通道。如果您的实例之前未使用此设置进行部署，或者在部署时将该项设置为 `external`，那么您在重新部署实例并将该项设置为 `internal` 时，系统会从您的实例中移除临时外部 IP 地址。`internal` 设置有一些限制。默认值为 `external`。
`instance_tag`	可选。创建服务时，将为该服务的每个实例分配一个具有该名称的标记。在 `gcloud` 命令中，标记可用于将操作定位到一组实例。例如，请参阅 `--source-tags` 和 `--target-tags` 标志在 compute firewalls-create 命令中的使用。如果未指定，则不使用共享 VPC 时，实例将具有 `aef-INSTANCE_ID` 标记。如果使用共享 VPC，则实例将同时具有 `aef-INSTANCE_ID and aef-instance.` 标记
`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`)。`HOST_PORT` 必须介于 1024 到 65535 之间，且不能与以下端口冲突：22、8080、8090、8443、10000、10001、10400-10500、11211、24231。`CONTAINER_PORT` 必须介于 1 到 65535 之间，且不能与以下端口冲突：22、10001、10400-10500、11211。如果仅指定一个 `PORT`，则 App Engine 会假定该端口与主机和容器上的端口相同。默认情况下，TCP 和 UDP 流量都会被转发。流量必须直接发送至目标实例的 IP 地址，而不是通过 appspot.com 网域或您的自定义网域转发。

高级网络配置

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

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

创建自定义子网。
将网络名称和子网名称添加到您的 app.yaml 文件，如上所述。
要基于静态路由建立简单的 VPN，请为自定义子网创建网关和隧道。否则，请参阅如何创建其他类型的 VPN。

端口转发

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

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

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

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

在 app.yaml 的网络设置中，添加以下内容：
```
network:
  forwarded_ports:
    - 2222/tcp
```
1. 如果您使用 Python 运行时，请修改 app.yaml 以添加以下内容：
```
entrypoint: gunicorn -b :$PORT -b :2222 main:app
```
通过 Google Cloud 控制台或使用 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 到 32 之间的偶数，或介于 32 到 80 之间的 4 的倍数。	1 个核心
`memory_gb`	RAM 以 GB 为单位。应用请求的内存，不包含某些进程的开销所需的〜0.4 GB 内存。每个 CPU 核心需要的总内存介于 1.0 到 6.5 GB 之间。要计算所请求的内存，请使用以下公式： `memory_gb` = `cpu` * [1.0 - 6.5] - 0.4 在上述示例中，您指定了 2 个核心，因此您可请求的内存容量介于 1.6 到 12.6 GB 之间。可供应用使用的内存总容量由运行时环境设置为环境变量 `GAE_MEMORY_MB`。	0.6 GB
`disk_size_gb`	大小（以 GB 为单位）。最小值为 10 GB，最大值为 10240 GB。	13 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`	（Beta 版）每个实例的目标并发连接数。如果为此参数指定了值，自动扩缩器会根据所有正在运行的实例的平均并发连接数来决定何时减少或增加实例数。在实例收到关停信号 25 秒后，无论进行中的请求数为何，实例都会缩减。如果没有为此参数指定值，自动扩缩器不会以某个实例并发连接数为目标进行扩缩。连接数有别于请求数。客户端可以重复使用一个连接来发送多个请求。

手动扩缩

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

manual_scaling:
  instances: 5

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

名称	说明
`manual_scaling`	需要此设置才能为服务启用手动扩缩。
`instances`	要分配给服务的实例数。注意：在某些事件发生期间，正在运行的实例数在短时间内可能会低于此值。如果您的应用需要在特定数量的实例上连续运行，请考虑超额预配。

定义环境变量

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

env_variables:
  MY_VAR: "my value"

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