本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Envoy 配置变量
**重要**
终止支持通知：2026 年 9 月 30 日， AWS 将停止对的支持。 AWS App Mesh 2026 年 9 月 30 日之后，您将无法再访问 AWS App Mesh 控制台或 AWS App Mesh 资源。有关更多信息，请访问此博客文章[从迁移 AWS App Mesh 到 Amazon ECS Service Connect](https://aws.amazon.com/blogs/containers/migrating-from-aws-app-mesh-to-amazon-ecs-service-connect)。
使用以下环境变量为您的 App Mesh 虚拟节点任务组配置 Envoy 容器。
**注意**
App Mesh Envoy 1.17 不支持 Envoy 的 **v2 xDS** API。如果您使用的是接受 [Envoy 配置文件的 Envoy 配置变量](https://docs.aws.amazon.com/app-mesh/latest/userguide/envoy-config.html)，则必须将其更新为最新的 **v3 xDS** API。
## 必需的变量
所有 App Mesh Envoy 容器都需要以下环境变量。此变量只能用于 Envoy 映像版本 `1.15.0` 或更高版本。如果您使用的是较早版本的映像，则必须改用 `APPMESH_VIRTUAL_NODE_NAME` 变量。
`APPMESH_RESOURCE_ARN`
在将 Envoy 容器添加到任务组时，请将此环境变量设置为任务组所代表的虚拟节点或虚拟网关的 ARN。以下列表包含示例 ARNs：
+ **虚拟节点** — arn: aws: appmesh:: mesh/ /virtualNode/ {{Region-code}} {{111122223333}} {{meshName}} {{virtualNodeName}}
+ **虚拟网关** — arn: aws: appmesh:: mesh/ /virtualGateway/ {{Region-code}} {{111122223333}} {{meshName}} {{virtualGatewayName}}
## 可选变量
以下环境变量对于 App Mesh Envoy 容器是可选的。
`ENVOY_LOG_LEVEL`
指定 Envoy 容器的日志级别。
有效值：`trace`、`debug`、`info`、`warn`、`error`、`critical`、`off`
默认值：`info`
`ENVOY_INITIAL_FETCH_TIMEOUT`
指定 Envoy 在初始化过程中等待来自管理服务器的第一个配置响应的时间。
有关更多信息，请参阅 Envoy 文档中的 [Configuration 资源](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/config_source.proto#envoy-v3-api-field-config-core-v3-configsource-initial-fetch-timeout)。设置为 `0` 时，没有超时。
默认值：`0`
`ENVOY_CONCURRENCY`
在启动 Envoy 时设置 `--concurrency` 命令行选项。默认情况下，不设置该选项。此选项在 Envoy 版本 `v1.24.0.0-prod` 或更高版本中可用。
有关更多信息，请参阅[命令行选项](https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-concurrency)。
### 管理员变量
使用这些环境变量来配置 Envoy 的管理接口。
`ENVOY_ADMIN_ACCESS_PORT`
指定 Envoy 要侦听的自定义管理端口。默认值：`9901`。
Envoy 管理端口应不同于虚拟网关或虚拟节点上的任何侦听器端口
`ENVOY_ADMIN_ACCESS_LOG_FILE`
指定写入 Envoy 访问日志的自定义路径。默认值：`/tmp/envoy_admin_access.log`。
`ENVOY_ADMIN_ACCESS_ENABLE_IPV6`
切换 Envoy 的管理界面以接受 `IPv6` 流量，这样该接口就可以同时接受 `IPv4` 流量和 `IPv6` 流量。默认情况下，此标志设置为 false，并且 Envoy 只侦听 `IPv4` 流量。此变量只能用于 Envoy 镜像版本 1.22.0 或更高版本。
### 代理变量
使用这些环境变量为 Envoy 配置 AWS App Mesh 代理。有关更多信息，请参阅适用于 [Envoy 的 App Mesh 代理](https://docs.aws.amazon.com//app-mesh/latest/userguide/appnet-agent.html)。
`APPNET_ENVOY_RESTART_COUNT`
指定代理在正在运行的任务或容器组 (pod) 中重新启动 Envoy 代理进程的次数（如果容器组 (pod) 已退出）。代理还会在每次 Envoy 退出时记录退出状态，以便于故障排除。该变量的默认值为 `0`。设置默认值后，代理不会尝试重新启动该进程。
默认值：`0`
最高：`10`
`PID_POLL_INTERVAL_MS`
指定代理检查 Envoy 代理进程状态的时间间隔（以毫秒为单位）。默认值为 `100`。
默认值：`100`
最低：`100`
最高：`1000`
`LISTENER_DRAIN_WAIT_TIME_S`
指定 Envoy 代理在进程退出之前等待活动连接关闭的时间（以秒为单位）。
默认值：`20`
最低：`5`
最高：`110`
`APPNET_AGENT_ADMIN_MODE`
启动代理的管理接口服务器并将其绑定到 tcp 地址或 unix 套接字。
有效值：`tcp`、`uds`
`APPNET_AGENT_HTTP_PORT`
指定用于在 `tcp` 模式下绑定代理管理接口的端口。确保端口值为 > `1024` if `uid` \!= `0`。确保端口小于`65535`。
默认值：`9902`
`APPNET_AGENT_ADMIN_UDS_PATH`
在 `uds` 模式下为代理的管理接口指定 unix 域套接字路径。
默认值：`/var/run/ecs/appnet_admin.sock`
### 跟踪变量
您可以不配置以下跟踪驱动程序或其中一个跟踪驱动程序。
#### AWS X-Ray 变量
使用以下环境变量来配置带 AWS X-Ray的 App Mesh。有关更多信息，请参阅 [AWS X-Ray 开发人员指南](https://docs.aws.amazon.com/xray/latest/devguide/)。
`ENABLE_ENVOY_XRAY_TRACING`
使用 `127.0.0.1:2000` 作为默认进程守护程序端点启用 X-Ray 跟踪。要启用，请将值设置为 `1`。默认值为 `0`。
`XRAY_DAEMON_PORT`
指定端口值以覆盖默认 X-Ray 进程守护程序端口：`2000`。
`XRAY_SAMPLING_RATE`
指定采样率以覆盖 X-Ray tracer 的默认采样率 `0.05` (5%)。将该值指定为介于 `0` 和 `1.00` 之间的小数(100%)。如果已指定 `XRAY_SAMPLING_RULE_MANIFEST`，则该值将被覆盖。版本 `v1.19.1.1-prod` 及更高版本的 Envoy 映像支持此变量。
`XRAY_SAMPLING_RULE_MANIFEST`
在 Envoy 容器文件系统中指定文件路径，为 X-Ray tracer 配置本地化的自定义采样规则。有关更多信息，请参阅《AWS X-Ray 开发人员指南》**中的[采样规则](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-go-configuration.html#xray-sdk-go-configuration-sampling)。版本 `v1.19.1.0-prod` 及更高版本的 Envoy 映像支持此变量。
`XRAY_SEGMENT_NAME`
为轨迹指定分段名称以覆盖默认 X-Ray 分段名称。默认情况下，此值将设置为 `mesh/resourceName`。Envoy 镜像版本 `v1.23.1.0-prod` 或更高版本支持此变量。
#### Datadog 跟踪变量
以下环境变量可帮助您使用 Datadog 代理追踪器配置 App Mesh。有关更多信息，请参阅 Datadog 文档中的[代理配置](https://docs.datadoghq.com/tracing/send_traces/)。
`ENABLE_ENVOY_DATADOG_TRACING`
使用作为默认 Datadog 代理端点的 `127.0.0.1:8126` 启用 Datadog 跟踪收集。要启用，请将该值设置为 `1`（默认值为 `0`）。
`DATADOG_TRACER_PORT`
指定一个端口值以覆盖默认 Datadog 代理端口：`8126`。
`DATADOG_TRACER_ADDRESS`
指定 IP 地址以覆盖默认的 Datadog 代理地址：`127.0.0.1`。
`DD_SERVICE`
为跟踪指定服务名称以覆盖默认的 Datadog 服务名称：`envoy-meshName`/`virtualNodeName`。版本 `v1.18.3.0-prod` 及更高版本的 Envoy 映像支持此变量。
#### Jaeger 追踪变量
使用以下环境变量配置带有 Jaeger 跟踪的 App Mesh。有关更多信息，请参阅 Jaeger 文档中的[入门](https://www.jaegertracing.io/docs/1.21/getting-started/)。版本 `1.16.1.0-prod` 及更高版本的 Envoy 镜像支持这些变量。
`ENABLE_ENVOY_JAEGER_TRACING`
使用 `127.0.0.1:9411` 作为默认 Jaeger 端点启用 Jaeger 跟踪收集。要启用，请将该值设置为 `1`（默认值为 `0`）。
`JAEGER_TRACER_PORT`
指定端口值以覆盖默认 Jaeger 端口：`9411`。
`JAEGER_TRACER_ADDRESS`
指定 IP 地址以覆盖默认 Jaeger 地址：`127.0.0.1`。
`JAEGER_TRACER_VERSION`
指定收集器是否需要 `PROTO` 编码格式的 `JSON` 轨迹。默认情况下，该值将设置为 `PROTO`。Envoy 镜像版本 `v1.23.1.0-prod` 或更高版本支持此变量。
#### 特使跟踪变量
将以下环境变量设置为使用您自己的跟踪配置。
`ENVOY_TRACING_CFG_FILE`
在 Envoy 容器文件系统中指定文件路径。有关更多信息，请参阅 Envoy 文档中的[https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/http_tracer.proto#envoy-v3-api-msg-config-trace-v3-tracing](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/http_tracer.proto#envoy-v3-api-msg-config-trace-v3-tracing)。
如果跟踪配置需要指定跟踪集群，请确保在同一个跟踪配置文件 `static_resources` 中配置关联的集群配置。例如，Zipkin 有一个用于托管跟踪收集器的集群名称[https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/zipkin.proto#config-trace-v3-zipkinconfig](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/zipkin.proto#config-trace-v3-zipkinconfig)字段，该集群需要静态定义。
### DogStatsD 变量
使用以下环境变量将 App Mesh 配置为 DogStats D。有关更多信息，请参阅 [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/) 文档。
`ENABLE_ENVOY_DOG_STATSD`
使用`127.0.0.1:8125`作为默认守护程序端点启用 DogStats D 统计信息。要启用，请将值设置为 `1`。
`STATSD_PORT`
指定端口值以覆盖默认 DogStats D 守护程序端口。
`STATSD_ADDRESS`
指定 IP 地址值以覆盖默认 DogStats D 守护程序 IP 地址。默认值：`127.0.0.1`。此变量只能用于 Envoy 映像版本 `1.15.0` 或更高版本。
`STATSD_SOCKET_PATH`
为 DogStats D 守护程序指定 unix 域套接字。如果未指定此变量且启用了 DogStats D，则此值默认为 DogStats D 守护程序 IP 地址端口。`127.0.0.1:8125`如果指定的`ENVOY_STATS_SINKS_CFG_FILE`变量包含 stats sinks 配置，则它将覆盖所有 DogStats D 变量。Envoy 镜像版本 `v1.19.1.0-prod` 或更高版本支持此变量。
### App Mesh 变量
以下变量可帮助您配置 App Mesh。
`APPMESH_RESOURCE_CLUSTER`
默认情况下，当 Envoy 在指标和跟踪中引用自己`APPMESH_RESOURCE_ARN`时，App Mesh 使用您在中指定的资源名称。您可以通过使用自己的名称设置 `APPMESH_RESOURCE_CLUSTER` 环境变量来覆盖此行为。此变量只能用于 Envoy 映像版本 `1.15.0` 或更高版本。
`APPMESH_METRIC_EXTENSION_VERSION`
将该值设置 `1` 为可启用 App Mesh 指标扩展。有关 App Mesh 指标扩展的更多信息，请参阅 [App Mesh 的指标扩展](metrics.md)。
`APPMESH_DUALSTACK_ENDPOINT`
将该值设置为 `1` 以连接到 App Mesh 双堆栈端点。设置此标志后，Envoy 将使用我们支持双堆栈的域。默认情况下，此标志设置为 false，并且仅连接到我们的 `IPv4` 域名。此变量只能用于 Envoy 镜像版本 1.22.0 或更高版本。
### 特使统计变量
使用以下环境变量为 App Mesh 配置 Envoy 统计信息。有关更多信息，请参阅 [Envoy Stats](https://www.envoyproxy.io/docs/envoy/v1.6.0/api-v2/config/metrics/v2/stats.proto) 文档。
`ENABLE_ENVOY_STATS_TAGS`
允许使用 App Mesh 定义的标签 `appmesh.mesh` 和 `appmesh.virtual_node`。有关更多信息，请参阅 [config.metrics.v3。 TagSpecifier](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/metrics/v3/stats.proto#config-metrics-v3-tagspecifier)在特使文档中。要启用，请将值设置为 `1`。
`ENVOY_STATS_CONFIG_FILE`
在 Envoy 容器文件系统中指定文件路径，用自己的文件路径覆盖默认的 Stats 标签配置文件。有关更多信息，请参阅 [config.metrics.v3。 StatsConfig](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/metrics/v3/stats.proto#config-metrics-v3-statsconfig)。
设置包含统计过滤器的自定义统计信息配置可能会导致 Envoy 进入无法再与 App Mesh 世界状态正确同步的状态。这是 Envoy 中的一个[错误](https://github.com/envoyproxy/envoy/issues/9856)。我们建议不要在 Envoy 中对统计数据进行任何过滤。如果绝对需要过滤，我们在路线图上列出了本次[发布版本](https://github.com/aws/aws-app-mesh-roadmap/issues/283)的几个解决方法。
`ENVOY_STATS_SINKS_CFG_FILE`
在 Envoy 容器文件系统中指定文件路径，用自己的文件路径覆盖默认配置。有关更多信息，请参阅 [config.metrics.v3。 StatsSink](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/metrics/v3/stats.proto#config-metrics-v3-statssink)在特使文档中。
### 已弃用的变量
Envoy 版本 `1.15.0` 或更高版本不再支持环境变量 `APPMESH_VIRTUAL_NODE_NAME` 和 `APPMESH_RESOURCE_NAME`。但是，现有网格仍然支持它们。与其在 Envoy 版本 `1.15.0` 或更高版本中使用这些变量，不如将这些变量 `APPMESH_RESOURCE_ARN` 用于所有 App Mesh 端点。