Ambassador Edge Stack Environment variables

Use the following variables for the environment of your Ambassador Edge Stack container:

Feature Flag Environment Variables

AMBASSADOR_ID

Ambassador Edge Stack supports running multiple installs in the same cluster without restricting a given instance of Ambassador Edge Stack to a single namespace. The resources that are visible to an installation can be limited with the AMBASSADOR_ID environment variable.

More information

AES_LOG_LEVEL

Adjust the log level by setting the AES_LOG_LEVEL environment variable; from least verbose to most verbose, the valid values are error, warn/warning, info, debug, and trace. The default is info. Log level names are case-insensitive.

More information

AES_DISABLE_LICENSE_USAGE_REPORTING

Usage data is collected and sent to Ambassador Labs servers on regular intervals. If you are using an in-cluster AirGapped license and wish to disable this, then setting AES_DISABLE_LICENSE_USAGE_REPORTING to true will prevent Ambassador Edge Stack from reporting license usage data. If your cluster is using a Cloud license then users are required to send this data and cannot disable it.

More license information

AGENT_CONFIG_RESOURCE_NAME

Allows overriding the default config_map/secret that is used for extracting the CloudToken for connecting with Ambassador cloud. It allows all components (and not only the Ambassador Agent) to authenticate requests to Ambassador Cloud. If unset it will just fallback to searching for a config map or secret with the name of edge-stack-agent-cloud-token. Note: the secret will take precedence if both a secret and config map are set.

AMBASSADOR_AMBEX_NO_RATELIMIT

Completely disables ratelimiting Envoy reconfiguration under memory pressure. This can help performance with the endpoint or Consul resolvers, but could make OOMkills more likely with large configurations. The default is false, meaning that the rate limiter is active.

More information

AMBASSADOR_AMBEX_SNAPSHOT_COUNT

Envoy-configuration snapshots get saved (as ambex-#.json) in /ambassador/snapshots. The number of snapshots is controlled by the AMBASSADOR_AMBEX_SNAPSHOT_COUNT environment variable. Set it to 0 to disable.

More information

AMBASSADOR_CLUSTER_ID

Each Ambassador Edge Stack installation generates a unique cluster ID based on the UID of its Kubernetes namespace and its Ambassador Edge Stack ID: the resulting cluster ID is a UUID which cannot be used to reveal the namespace name nor Ambassador Edge Stack ID itself. Ambassador Edge Stack needs RBAC permission to get namespaces for this purpose, as shown in the default YAML files provided by Datawire; if not granted this permission it will generate a UUID based only on the Ambassador Edge Stack ID. To disable cluster ID generation entirely, set the environment variable AMBASSADOR_CLUSTER_ID to a UUID that will be used for the cluster ID.

More information

AMBASSADOR_CONFIG_BASE_DIR

Controls where Ambassador Edge Stack will store snapshots. By default, the latest configuration will be in /ambassador/snapshots. If you have overridden it, Ambassador Edge Stack saves configurations in $AMBASSADOR_CONFIG_BASE_DIR/snapshots.

More information

AMBASSADOR_DISABLE_FEATURES

To completely disable feature reporting, set the environment variable AMBASSADOR_DISABLE_FEATURES to any non-empty value.

More information

AMBASSADOR_DRAIN_TIME

At each reconfiguration, Ambassador Edge Stack keeps around the old version of it's envoy config for the duration of the configured drain time. The AMBASSADOR_DRAIN_TIME variable controls how much of a grace period Ambassador Edge Stack provides active clients when reconfiguration happens. Its unit is seconds and it defaults to 600 (10 minutes). This can impact memory usage because Ambassador Edge Stack needs to keep around old versions of its configuration for the duration of the drain time.

More information

AMBASSADOR_ENVOY_API_VERSION

By default, Ambassador Edge Stack will configure Envoy using the V3 Envoy API. In Ambassador Edge Stack 2.0, you were able switch back to Envoy V2 by setting the AMBASSADOR_ENVOY_API_VERSION environment variable to "V2". Ambassador Edge Stack 3.0 has removed support for the V2 API and only the V3 API is used. While this variable cannot be set to another value in 3.0, it may be used when introducing new API versions that are not yet available in Ambassador Edge Stack such as V4.

AMBASSADOR_GRPC_METRICS_SINK

Configures Ambassador Edge Stack (envoy) to send metrics to the Agent which are then relayed to the Cloud. If not set then we don’t configure envoy to send metrics to the agent. If set with a bad address:port then we log an error message. In either scenario, it just stops metrics from being sent to the Agent which has no negative effect on general routing or Ambassador Edge Stack uptime.

AMBASSADOR_HEALTHCHECK_BIND_ADDRESS

Configures Ambassador Edge Stack to bind its health check server to the provided address. If not set Ambassador Edge Stack will bind to all addresses (0.0.0.0).

AMBASSADOR_HEALTHCHECK_BIND_PORT

Configures Ambassador Edge Stack to bind its health check server to the provided port. If not set Ambassador Edge Stack will listen on the admin port(8877).

AMBASSADOR_HEALTHCHECK_IP_FAMILY

Allows the IP Family used by health check server to be overriden. By default, the health check server will listen for both IPV4 and IPV6 addresses. In some clusters you may want to force IPV4_ONLY or IPV6_ONLY.

AMBASSADOR_ISTIO_SECRET_DIR

Ambassador Edge Stack will read the mTLS certificates from /etc/istio-certs unless configured to use a different directory with the AMBASSADOR_ISTIO_SECRET_DIR environment variable and create a secret in that location named istio-certs.

More information

AMBASSADOR_JSON_LOGGING

When AMBASSADOR_JSON_LOGGING is set to true, JSON format will be used for most of the control plane logs. Some (but few) logs from gunicorn and the Kubernetes client-go package will still be in text only format.

More information

AMBASSADOR_READY_PORT

A dedicated Listener is created for non-blocking readiness checks. By default, the Listener will listen on the loopback address and port 8006. 8006 is part of the reserved ports dedicated to Ambassador Edge Stack. If their is a conflict then setting AMBASSADOR_READY_PORT to a valid port will configure Envoy to Listen on that port.

AMBASSADOR_READY_LOG

When AMBASSADOR_READY_LOG is set to true, the envoy /ready endpoint will be logged. It will honor format provided in the Module resource or default to the standard log line format.

AMBASSADOR_LABEL_SELECTOR

Restricts Ambassador Edge Stack's configuration to only the labelled resources. For example, you could apply a version-two: true label to all resources that should be visible to Ambassador Edge Stack, then set AMBASSADOR_LABEL_SELECTOR=version-two=true in its Deployment. Resources without the specified label will be ignored.

AMBASSADOR_NAMESPACE

Controls namespace configuration for Amabssador.

More information

AMBASSADOR_RECONFIG_MAX_DELAY

Controls up to how long Ambassador will wait to receive changes before doing an Envoy reconfiguration. The unit is in seconds and must be > 0.

AMBASSADOR_SINGLE_NAMESPACE

When set, configures Ambassador Edge Stack to only work within a single namespace.

More information

AMBASSADOR_SNAPSHOT_COUNT

The number of snapshots that Ambassador Edge Stack should save.

AMBASSADOR_VERIFY_SSL_FALSE

By default, Ambassador Edge Stack will verify the TLS certificates provided by the Kubernetes API. In some situations, the cluster may be deployed with self-signed certificates. In this case, set AMBASSADOR_VERIFY_SSL_FALSE to true to disable verifying the TLS certificates.

More information

DISABLE_CA_MANAGEMENT

Ambassador Edge Stack used the emissary API Ext Conversion Webhook server to convert between CustomResource versions. By default it manages creating and rotating a CA Certificate that is used by the Conversion Webhook server to generate Server certificates. This can be disabled and handled externally by the user.

Note: only used by the emissary-apiext Deployment

More information

DISABLE_CRD_MANAGEMENT

Ambassador Edge Stack used the emissary API Ext Conversion Webhook server to convert between CustomResource versions. By default it manages patching the CustomResourceDefinitions with the CA Bundle so that the kube-api-server can verify the server certificates. This can be disabled and handled externally by the user.

Note: only used by the emissary-apiext Deployment

More information

DD_ENTITY_ID

Ambassador Edge Stack supports setting the dd.internal.entity_id statitics tag using the DD_ENTITY_ID environment variable. If this value is set, statistics will be tagged with the value of the environment variable. Otherwise, this statistics tag will be omitted (the default).

More information

DOGSTATSD

If you are a user of the Datadog monitoring system, pulling in the Envoy statistics from Ambassador Edge Stack is very easy. Because the DogStatsD protocol is slightly different than the normal StatsD protocol, in addition to setting Ambassador Edge Stack's STATSD_ENABLED=true environment variable, you also need to set theDOGSTATSD=true environment variable.

More information

SCOUT_DISABLE

Ambassador Edge Stack integrates Scout, a service that periodically checks with Ambassador Labs servers to sends anonymized usage data and the Ambassador Edge Stack version. This information is important to us as we prioritize test coverage, bug fixes, and feature development. Note that the Ambassador Edge Stack will run regardless of the status of Scout.

We do not recommend you disable Scout. This check can be disabled by setting the environment variable SCOUT_DISABLE to 1 in your Ambassador Edge Stack deployment.

More information

STATSD_ENABLED

If enabled, then Ambassador Edge Stack has Envoy expose metrics information via the ubiquitous and well-tested StatsD protocol. To enable this, you will simply need to set the environment variable STATSD_ENABLED=true in Ambassador Edge Stack's deployment YAML

More information

STATSD_HOST

When this variable is set, Ambassador Edge Stack by default sends statistics to a Kubernetes service named statsd-sink on UDP port 8125 (the usual port of the StatsD protocol). You may instead tell Ambassador Edge Stack to send the statistics to a different StatsD server by setting the STATSD_HOST environment variable. This can be useful if you have an existing StatsD sink available in your cluster.

More information

STATSD_PORT

Allows for configuring StatsD on a port other than the default (8125)

More information

STATSD_FLUSH_INTERVAL

How often, in seconds, to submit statsd reports (if STATSD_ENABLED)

More information

_AMBASSADOR_ID

Used with the Ambassador Consul connector. Sets the Ambassador ID so multiple instances of this integration can run per-Cluster when there are multiple Ambassador Edge Stacks (Required if AMBASSADOR_ID is set in your Ambassador Edge Stack Deployment

More information

_AMBASSADOR_TLS_SECRET_NAME

Used with the Ambassador Consul connector. Sets the name of the Kubernetes v1.Secret created by this program that contains the Consul-generated TLS certificate.

More information

_AMBASSADOR_TLS_SECRET_NAMESPACE

Used with the Ambassador Consul connector. Sets the namespace of the Kubernetes v1.Secret created by this program.

More information

_CONSUL_HOST

Used with the Ambassador Consul connector. Sets the IP or DNS name of the target Consul HTTP API server

More information

_CONSUL_PORT

Used with the Ambassador Consul connector. Sets the port number of the target Consul HTTP API server.

More information

AMBASSADOR_DISABLE_SNAPSHOT_SERVER

Disables the built-in snapshot server

AMBASSADOR_ENVOY_BASE_ID

Base ID of the Envoy process

AES_RATELIMIT_PREVIEW

Enables support for redis clustering, local caching, and an upgraded redis client with improved scalability in preview mode.

More information

AES_AUTH_TIMEOUT

Configures the default timeout in the authentication extension.

More information

REDIS_SOCKET_TYPE

Redis currently support three different deployment methods. Ambassador Edge Stack can now support using a Redis deployed in any of these ways for rate limiting when AES_RATELIMIT_PREVIEW=true.

More information

REDIS_URL

The URL to dial to talk to Redis.

This will be either a hostname:port pair or a comma separated list of hostname:port pairs depending on the REDIS_TYPE you are using.

More information

REDIS_TLS_ENABLED

Specifies whether to use TLS when talking to Redis.

More information

REDIS_TLS_INSECURE

Specifies whether to skip certificate verification when using TLS to talk to Redis.

More information

REDIS_USERNAME

REDIS_USERNAME and REDIS_PASSWORD handle all Redis authentication that is separate from Rate Limit Preview so failing to set them when using REDIS_AUTH will result in Ambassador not being able to authenticate with Redis for all of its other functionality.

More information

REDIS_PASSWORD

REDIS_USERNAME and REDIS_PASSWORD handle all Redis authentication that is separate from Rate Limit Preview so failing to set them when using REDIS_AUTH will result in Ambassador not being able to authenticate with Redis for all of its other functionality.

More information

REDIS_AUTH

If you configure REDIS_AUTH, then REDIS_USERNAME cannot be changed from the value default, and REDIS_PASSWORD should contain the same value as REDIS_AUTH.

More information

REDIS_POOL_SIZE

The number of connections to keep around when idle. The total number of connections may go lower than this if there are errors. The total number of connections may go higher than this during a load surge.

More information

REDIS_PING_INTERVAL

The rate at which Ambassador will ping the idle connections in the normal pool (not extra connections created for a load surge).

More information

REDIS_TIMEOUT

Sets 4 different timeouts:

1. (*net.Dialer).Timeout for establishing connections
2. (*redis.Client).ReadTimeout for reading a single complete response
3. (*redis.Client).WriteTimeout for writing a single complete request
4. The timeout when waiting for a connection to become available from the pool (not including the dial time, which is timed out separately)

A value of "0" means "no timeout".

More information

REDIS_SURGE_LIMIT_INTERVAL

During a load surge, if the pool is depleted, then Ambassador may create new connections to Redis in order to fulfill demand, at a maximum rate of one new connection per REDIS_SURGE_LIMIT_INTERVAL.

More information

REDIS_SURGE_LIMIT_AFTER

The number of connections that can be created after the normal pool is depleted before REDIS_SURGE_LIMIT_INTERVAL kicks in.

More information

REDIS_SURGE_POOL_SIZE

Normally during a surge, excess connections beyond REDIS_POOL_SIZE are closed immediately after they are done being used, instead of being returned to a pool.

REDIS_SURGE_POOL_SIZE configures a "reserve" pool for excess connections created during a surge.

More information

REDIS_SURGE_POOL_DRAIN_INTERVAL

How quickly to drain connections from the surge pool after a surge is over.

More information

REDIS_PIPELINE_WINDOW

The duration after which internal pipelines will be flushed.

More information

REDIS_PIPELINE_LIMIT

The maximum number of commands that can be pipelined before flushing.

More information

REDIS_TYPE

Redis currently support three different deployment methods. Ambassador Edge Stack can now support using a Redis deployed in any of these ways for rate limiting when AES_RATELIMIT_PREVIEW=true.

More information

REDIS_PERSECOND

If true, a second Redis connection pool is created (to a potentially different Redis instance) that is only used for per-second RateLimits; this second connection pool is configured by the REDIS_PERSECOND_* variables rather than the usual REDIS_* variables.

More information

REDIS_PERSECOND_SOCKET_TYPE

Configures the REDIS_SOCKET_TYPE for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_URL

Configures the REDIS_URL for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_TLS_ENABLED

Configures REDIS_TLS_ENABLED for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_TLS_INSECURE

Configures REDIS_TLS_INSECURE for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_USERNAME

Configures the REDIS_USERNAME for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_PASSWORD

Configures the #REDIS_PASSWORD for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_AUTH

Configures REDIS_AUTH for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_POOL_SIZE

Configures the REDIS_POOL_SIZE for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_PING_INTERVAL

Configures the REDIS_PING_INTERVAL for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_TIMEOUT

Configures the REDIS_TIMEOUT for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_SURGE_LIMIT_INTERVAL

Configures the REDIS_SURGE_LIMIT_INTERVAL for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_SURGE_LIMIT_AFTER

Configures REDIS_SURGE_LIMIT_AFTER for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_SURGE_POOL_SIZE

Configures the REDIS_SURGE_POOL_SIZE for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_SURGE_POOL_DRAIN_INTERVAL

Configures the REDIS_SURGE_POOL_DRAIN_INTERVAL for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_TYPE

Configures the REDIS_TYPE for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_PIPELINE_WINDOW

Configures the REDIS_PIPELINE_WINDOW for the second REDIS_PERSECOND connection pool.

More information

REDIS_PERSECOND_PIPELINE_LIMIT

Configures the REDIS_PIPELING_LIMIT for the second REDIS_PERSECOND connection pool.

More information

EXPIRATION_JITTER_MAX_SECONDS

USE_STATSD

The RateLimitService reports to statsd, and attempts to do so by default (USE_STATSD, STATSD_HOST, STATSD_PORT, GOSTATS_FLUSH_INTERVAL_SECONDS).

GOSTATS_FLUSH_INTERVAL_SECONDS

Configures the flush interval in seconds for the go statistics.

LOCAL_CACHE_SIZE_IN_BYTES

Only available if AES_RATELIMIT_PREVIEW: "true. The AES rate limit extension can optionally cache over-the-limit keys so it does not need to read the redis cache again for requests with labels that are already over the limit.

Setting LOCAL_CACHE_SIZE_IN_BYTES to a non-zero value with enable local caching.

More information

NEAR_LIMIT_RATIO

Only available if AES_RATELIMIT_PREVIEW: "true". Adjusts the ratio used by the near_limit statistic for tracking requests that are "near the limit". Defaults to 0.8 (80%) of the limit defined in the RateLimit rule.

More information

AMBASSADOR_URL

Fallback base URL used when a Mapping configured for the DevPortal doesn't include a Mapping.Spec.Host. This should be set to the base URL that you expose your API on and is used by the DevPortal for generating the correct calls to your backend service documentation.

DEVPORTAL_CONTENT_URL

Default URL to the repository hosting the content for the Portal

More information

DEVPORTAL_CONTENT_DIR

Default content subdirectory within the DEVPORTAL_CONTENT_URL the devportal content is located at (defaults to /)

More information

DEVPORTAL_CONTENT_BRANCH

Default content branch within the repo at DEVPORTAL_CONTENT_URL to use for the devportal content (defaults to master)

More information

DEVPORTAL_DOCS_BASE_PATH

Base path for each api doc (defaults to /doc/)

More information

POLL_EVERY_SECS

Interval for polling OpenAPI docs; default 60 seconds. Set to 0 to disable devportal polling.

More information

AES_ACME_LEADER_DISABLE

This prevents Ambassador Edge Stack from trying to manage ACME. When enabled, Host resources will be unable to use ACME to manage their tls secrets regardless of the config on the Host resource.

AES_REPORT_DIAGNOSTICS_TO_CLOUD

By setting AES_REPORT_DIAGNOSTICS_TO_CLOUD to false, you can disable the feature where diagnostic information about your installation of Ambassador Edge Stack will be sent to Ambassador cloud. If this variable is disabled, you will be unable to access cluster diagnostic information in the cloud.

AES_SNAPSHOT_URL

Configures the default endpoint where config snapshots are stored and accessed.

ENV_AES_SECRET_NAME

Use to override the name of the secret that Ambassador Edge Stack attempts to find licensing information in.

ENV_AES_SECRET_NAMESPACE

Use to override the namespace of the secret that Ambassador Edge Stack attempts to find licensing information in. By default, Ambassador Edge Stack will look for the secret in the same namespace that Ambassador Edge Stack was installed in.

AMBASSADOR_EDS_BYPASS

Bypasses EDS handling of endpoints and causes endpoints to be inserted to clusters manually. This can help resolve with 503 UH caused by certification rotation relating to a delay between EDS + CDS.

AMBASSADOR_FORCE_SECRET_VALIDATION

If you set the AMBASSADOR_FORCE_SECRET_VALIDATION environment variable, invalid Secrets will be rejected, and a Host or TLSContext resource attempting to use an invalid certificate will be disabled entirely.

More information

AMBASSADOR_KNATIVE_SUPPORT

Enables support for knative

AMBASSADOR_UPDATE_MAPPING_STATUS

If AMBASSADOR_UPDATE_MAPPING_STATUS is set to the string true, Ambassador Edge Stack will update the status of every Mapping CRD that it accepts for its configuration. This has no effect on the proper functioning of Ambassador Edge Stack itself, and can be a performance burden on installations with many Mappings. It has no effect for Mappings stored as annotations.

The default is false. We recommend leaving AMBASSADOR_UPDATE_MAPPING_STATUS turned off unless required for external systems.

More information

ENVOY_CONCURRENCY

Configures the optional --concurrency command line option when launching Envoy. This controls the number of worker threads used to serve requests and can be used to fine-tune system resource usage.

DISABLE_STRICT_LABEL_SELECTORS

In Ambassador Edge Stack version 3.2, a bug with how Hosts are associated with Mappings was fixed and with how Listeners are associated with Hosts. The mappingSelector\selector fields in Hosts and Listeners were not properly being enforced in prior versions. If any single label from the selector was matched then the resources would be associated with each other instead of requiring all labels in the selector to be present. Additonally, if the hostname of a Mapping matched the hostname of a Host then they would be associated regardless of the configuration of mappingSelector\selector.

In version 3.2 this bug was fixed and resources that configure a selector will only be associated if all labels required by the selector are present. This brings the mappingSelector and selector fields in-line with how label selectors are used throughout Kubernetes. To avoid unexpected behavior after the upgrade, add all labels that configured in any mappingSelector\selector to Mappings you want to associate with the Host or the Hosts you want to be associated with the Listener. You can opt-out of this fix and return to the old association behavior by setting the environment variable DISABLE_STRICT_LABEL_SELECTORS to "true" (default: "false"). A future version of Ambassador Edge Stack may remove the ability to opt-out of this bugfix.

Note: The mappingSelector field is only configurable on v3alpha1 CRDs. In the v2 CRDs the equivalent field is selector. either selector or mappingSelector may be configured in the v3alpha1 CRDs, but selector has been deprecated in favour of mappingSelector.

See The Host documentation for more information about Host / Mapping association.

Port assignments

Ambassador Edge Stack uses the following ports to listen for HTTP/HTTPS traffic automatically via TCP: