Use the following variables for the environment of your Emissary-ingress container:
|Variable||Default value||Value type|
|Boolean; Python |
|Boolean; non-empty=true, empty=false|
Emissary-ingress supports running multiple installs in the same cluster without restricting a given instance of Emissary-ingress to a single namespace.
The resources that are visible to an installation can be limited with the
AMBASSADOR_ID environment variable.
Adjust the log level by setting the
AES_LOG_LEVEL environment variable; from least verbose to most verbose, the valid values are
trace. The default is
Log level names are case-insensitive.
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
ambassador-agent-cloud-token. Note: the secret will take precedence if both a secret and config map are set.
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.
Envoy-configuration snapshots get saved (as
/ambassador/snapshots. The number of snapshots is controlled by the
AMBASSADOR_AMBEX_SNAPSHOT_COUNT environment variable.
Set it to 0 to disable.
Each Emissary-ingress installation generates a unique cluster ID based on the UID of its Kubernetes namespace and its Emissary-ingress ID: the resulting cluster ID is a UUID which cannot be used
to reveal the namespace name nor Emissary-ingress ID itself. Emissary-ingress 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 Emissary-ingress 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.
Controls where Emissary-ingress will store snapshots. By default, the latest configuration will be in
/ambassador/snapshots. If you have overridden it, Emissary-ingress saves configurations in
To completely disable feature reporting, set the environment variable
AMBASSADOR_DISABLE_FEATURES to any non-empty value.
At each reconfiguration, Emissary-ingress keeps around the old version of it's envoy config for the duration of the configured drain time.
AMBASSADOR_DRAIN_TIME variable controls how much of a grace period Emissary-ingress provides active clients when reconfiguration happens.
Its unit is seconds and it defaults to 600 (10 minutes). This can impact memory usage because Emissary-ingress needs to keep around old versions of its configuration
for the duration of the drain time.
By default, Emissary-ingress will configure Envoy using the V3 Envoy API.
In Emissary-ingress 2.0, you were able switch back to Envoy V2 by setting the
AMBASSADOR_ENVOY_API_VERSION environment variable to "V2".
Emissary-ingress 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 Emissary-ingress such as V4.
Configures Edgissary (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 Edgissary uptime.
Configures Emissary-ingress to bind its health check server to the provided address. If not set Emissary-ingress will bind to all addresses (
Configures Emissary-ingress to bind its health check server to the provided port. If not set Emissary-ingress will listen on the admin port(
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
Emissary-ingress will read the mTLS certificates from
/etc/istio-certs unless configured to use a different directory with the
environment variable and create a secret in that location named
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.
A dedicated Listener is created for non-blocking readiness checks. By default, the Listener will listen on the loopback address
8006 is part of the reserved ports dedicated to Emissary-ingress. 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 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.
Restricts Emissary-ingress'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 Emissary-ingress, then set
AMBASSADOR_LABEL_SELECTOR=version-two=true in its Deployment.
Resources without the specified label will be ignored.
Controls namespace configuration for Amabssador.
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.
When set, configures Emissary-ingress to only work within a single namespace.
The number of snapshots that Emissary-ingress should save.
By default, Emissary-ingress 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
true to disable verifying the TLS certificates.
Emissary-ingress 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).
If you are a user of the Datadog monitoring system, pulling in the Envoy statistics from Emissary-ingress is very easy.
Because the DogStatsD protocol is slightly different than the normal StatsD protocol, in addition to setting Emissary-ingress's
STATSD_ENABLED=true environment variable, you also need to set the
DOGSTATSD=true environment variable.
Emissary-ingress integrates Scout, a service that periodically checks with Datawire servers to advise of available updates. Scout also sends anonymized usage data and the Emissary-ingress version. This information is important to us as we prioritize test coverage, bug fixes, and feature development. Note that the Emissary-ingress will run regardless of the status of Scout.
We do not recommend you disable Scout, since we use this mechanism to notify users of new releases (including critical fixes and security issues). This check can be disabled by setting
the environment variable
1 in your Emissary-ingress deployment.
If enabled, then Emissary-ingress 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 Emissary-ingress's deployment YAML
When this variable is set, Emissary-ingress 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 Emissary-ingress 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.
Allows for configuring StatsD on a port other than the default (8125)
How often, in seconds, to submit statsd reports (if
Used with the Ambassador Consul connector. Sets the Ambassador ID so multiple instances of this integration can run per-Cluster when there are multiple Emissary-ingresses (Required if
AMBASSADOR_ID is set in your Emissary-ingress
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.
Used with the Ambassador Consul connector. Sets the namespace of the Kubernetes
v1.Secret created by this program.
Used with the Ambassador Consul connector. Sets the IP or DNS name of the target Consul HTTP API server
Used with the Ambassador Consul connector. Sets the port number of the target Consul HTTP API server.
Disables the built-in snapshot server
Base ID of the Envoy process
Bypasses EDS handling of endpoints and causes endpoints to be inserted to clusters manually. This can help resolve with
caused by certification rotation relating to a delay between EDS + CDS.
If you set the
AMBASSADOR_FORCE_SECRET_VALIDATION environment variable, invalid Secrets will be rejected,
TLSContext resource attempting to use an invalid certificate will be disabled entirely.
Enables support for knative
AMBASSADOR_UPDATE_MAPPING_STATUS is set to the string
true, Emissary-ingress will update the
status of every
CRD that it accepts for its configuration. This has no effect on the proper functioning of Emissary-ingress 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.
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.
In Emissary-ingress version
3.2, a bug with how
Hosts are associated with
Mappings was fixed and with how
Listeners are assocaited with
selector fields in
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
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
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
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
"false"). A future version of
Emissary-ingress may remove the ability to opt-out of this bugfix.
mappingSelectorfield is only configurable on
v3alpha1CRDs. In the
v2CRDs the equivalent field is
mappingSelectormay be configured in the
selectorhas been deprecated in favour of
See The Host documentation for more information about
Emissary-ingress uses the following ports to listen for HTTP/HTTPS traffic automatically via TCP:
|8001||envoy||Internal stats, logging, etc.; not exposed outside pod|
|8002||watt||Internal watt snapshot access; not exposed outside pod|
|8003||ambex||Internal ambex snapshot access; not exposed outside pod|
|8005||snapshot||Exposes a scrubbed Emissary-ingress snapshot outside of the pod|
|8080||envoy||Default HTTP service port|
|8443||envoy||Default HTTPS service port|
|8877||diagd||Direct access to diagnostics UI; provided by |
- This may change in a future release to reflect the Pods's
namespace if deployed to a namespace other than