Envoy configuration variables - AWS App Mesh

Envoy configuration variables

The following environment variables enable you to configure the Envoy containers for your App Mesh virtual node task groups.

Note

Envoy 1.17 will no longer support Envoy’s v2 xDS API. If you are using Envoy configuration variables that accept Envoy config files, they must be updated to the latest v3 xDS API.

Required variables

The following environment variable is required for all App Mesh Envoy containers. This variable can only be used with version 1.15.0 or later of the Envoy image. If you're using an earlier version of the image, then you must set the APPMESH_VIRTUAL_NODE_NAME variable instead.

APPMESH_RESOURCE_ARN

When you add the Envoy container to a task group, set this environment variable to the ARN of the virtual node or the virtual gateway that the task group represents. The following list contains example ARNs:

  • Virtual node – arn:aws:appmesh:Region-code:111122223333:mesh/meshName/virtualNode/virtualNodeName

  • Virtual gateway – arn:aws:appmesh:Region-code:111122223333:mesh/meshName/virtualGateway/virtualGatewayName

When using the App Mesh Preview Channel, ARNs must use the us-west-2 Region and use appmesh-preview, instead of appmesh. For example, the ARN of a virtual node in the App Mesh Preview Channel is arn:aws:appmesh-preview:us-west-2:111122223333:mesh/meshName/virtualNode/virtualNodeName.

Optional variables

The following environment variable is optional for App Mesh Envoy containers.

ENVOY_LOG_LEVEL

Specifies the log level for the Envoy container.

Valid values: trace, debug, info, warning, error, critical, off

Default: info

ENVOY_INITIAL_FETCH_TIMEOUT

Specifies the amount of time an Envoy will wait for first configuration response from the management server during the initialization process.

For more information, see Configuration sources in Envoy Documentation. 0 indicates there is no timeout.

Default: 0

Admin variables

These environment variables let you configure Envoy's administrative interface.

ENVOY_ADMIN_ACCESS_PORT

Specify a custom admin port for Envoy to listen on. Default: 9901.

ENVOY_ADMIN_ACCESS_LOG_FILE

Specify a custom path to write Envoy access logs to. Default: /tmp/envoy_admin_access.log.

Tracing variables

You can configure none, or one of the following tracing drivers.

AWS X-Ray variables

The following environment variables help you to configure App Mesh with AWS X-Ray. For more information, see the AWS X-Ray Developer Guide.

ENABLE_ENVOY_XRAY_TRACING

Enables X-Ray tracing using 127.0.0.1:2000 as the default daemon endpoint. To enable, set the value to 1 (default value is 0).

XRAY_DAEMON_PORT

Specify a port value to override the default X-Ray daemon port: 2000.

XRAY_SAMPLING_RULE_MANIFEST

Specify a file path in the Envoy container file system to configure the localized custom sampling rules for the X-Ray tracer. For more information, see Sampling rules in the AWS X-Ray Developer Guide. This variable is supported with Envoy image version v1.19.1.0-prod or later.

Datadog tracing variables

The following environment variables help you configure App Mesh with the Datadog agent tracer. For more information, see Agent Configuration in the Datadog documentation.

ENABLE_ENVOY_DATADOG_TRACING

Enables Datadog trace collection using 127.0.0.1:8126 as the default Datadog agent endpoint. To enable, set the value to 1 (default value is 0).

DATADOG_TRACER_PORT

Specify a port value to override the default Datadog agent port: 8126.

DATADOG_TRACER_ADDRESS

Specify an IP address to override the default Datadog agent address: 127.0.0.1.

DD_SERVICE

Specify a service name for traces to override the default Datadog service name: envoy-meshName/virtualNodeName. This variable is supported with Envoy image version v1.18.3.0-prod or later.

Jaeger tracing variables

The following environment variables help you configure App Mesh with Jaeger tracing. For more information, see Getting Started in the Jaeger documentation. These variables are supported with v1.16.1.0-prod or later version of the Envoy image.

ENABLE_ENVOY_JAEGER_TRACING

Enables Jaeger trace collection using 127.0.0.1:9411 as the default Jaeger endpoint. To enable, set the value to 1 (default value is 0).

JAEGER_TRACER_PORT

Specify a port value to override the default Jaeger port: 9411.

JAEGER_TRACER_ADDRESS

Specify an IP address to override the default Jaeger address: 127.0.0.1.

Envoy tracing variable

The following environment variable enables you to use your own tracing configuration.

ENVOY_TRACING_CFG_FILE

Specify a file path in the Envoy container file system. For more information, see config.trace.v3.Tracing in the Envoy documentation.

Note

If the tracing configuration requires specifying a tracing cluster, be sure to also configure the associated cluster configuration under static_resources in the same tracing config file. For example, Zipkin has a collector_cluster field for the cluster name that hosts the trace collectors, and that cluster needs to be statically defined.

DogStatsD variables

The following environment variables help you to configure App Mesh with DogStatsD. For more information, see the DogStatsD documentation.

ENABLE_ENVOY_DOG_STATSD

Enables DogStatsD stats using 127.0.0.1:8125 as the default daemon endpoint. To enable, set the value to 1.

STATSD_PORT

Specify a port value to override the default DogStatsD daemon port.

STATSD_ADDRESS

Specify an IP address value to override the default DogStatsD daemon IP address. Default: 127.0.0.1. This variable can only be used with version 1.15.0 or later of the Envoy image.

STATSD_SOCKET_PATH

Specify a unix domain socket for the DogStatsD daemon. If this variable is not specified, and if DogStatsD is enabled, then this value defaults to the DogStatsD daemon IP address port of 127.0.0.1:8125. If the ENVOY_STATS_SINKS_CFG_FILE variable is specified containing a stats sinks configuration, it will override all of the DogStatsD variables. This variable is supported with Envoy image version v1.19.1.0-prod or later.

App Mesh variables

The following variables help you configure App Mesh.

APPMESH_PREVIEW

Set the value to 1 to connect to the App Mesh Preview Channel endpoint. For more information about using the App Mesh Preview Channel, see App Mesh Preview Channel.

APPMESH_RESOURCE_CLUSTER

By default App Mesh uses the name of the resource you specified in APPMESH_RESOURCE_ARN when Envoy is referring to itself in metrics and traces. You can override this behavior by setting the APPMESH_RESOURCE_CLUSTER environment variable with your own name. This variable can only be used with version 1.15.0 or later of the Envoy image.

Envoy stats variables

The following environment variables help you to configure App Mesh with Envoy Stats. For more information, see the Envoy Stats documentation.

ENABLE_ENVOY_STATS_TAGS

Enables the use of App Mesh defined tags appmesh.mesh and appmesh.virtual_node. For more information, see config.metrics.v3.TagSpecifier in the Envoy documentation. To enable, set the value to 1.

ENVOY_STATS_CONFIG_FILE

Specify a file path in the Envoy container file system to override the default Stats tags configuration file with your own. For more information, see config.metrics.v3.StatsConfig.

Note

Setting a customized stats configuration that includes stats filters might lead Envoy to enter a state where it will no longer properly synchronize with the App Mesh state of the world. This is a bug in Envoy. Our recommendation is to not perform any filtering of statistics in Envoy. If filtering is absolutely necessary, we have a listed a couple of workarounds in this issue on our roadmap.

ENVOY_STATS_SINKS_CFG_FILE

Specify a file path in the Envoy container file system to override the default configuration with your own. For more information, see config.metrics.v3.StatsSink in the Envoy documentation.

Deprecated variables

The environment variables APPMESH_VIRTUAL_NODE_NAME and APPMESH_RESOURCE_NAME are no longer supported in Envoy version 1.15.0 or later, but are still supported for existing meshes. Instead of using these variables with Envoy version 1.15.0 or later, use APPMESH_RESOURCE_ARN for all App Mesh endpoints.