The Ambassador Container

Container Images

To give you flexibility and independence from a hosting platform's uptime, you can pull the ambassador and aes images from any of the following registries:

• docker.io/datawire/
• quay.io/datawire/
• gcr.io/datawire/

For an even more robust installation, consider using a local registry as a pull through cache or configure a publicly accessible mirror.

Environment Variables

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

Log level names are case-insensitive. From least verbose to most verbose, valid log levels are error, warn/warning, info, debug, and trace.

Redis

The Ambassador Edge Stack make use of Redis for several purposes. By default, all components of the Ambassador Edge Stack share a Redis connection pool. If REDIS_PERSECOND is 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.

The Ambassador Edge Stack RateLimiting now supports redis clustering, local caching, and an upgraded redis client with improved scalability in preview mode. Set AES_RATELIMIT_PREVIEW to true to access these features.

Redis layer 4 connectivity (L4)

• SOCKET_TYPE and URL are the Go network name and Go network address to dial to talk to Redis; see Go net.Dial. Note that when using a port name instead of a port number, the name refers a well-known port name in the container's /etc/services, and not to a Kubernetes port name. For REDIS_URL (but not REDIS_PERSECOND_URL), not setting a value disables Ambassador Edge Stack features that require Redis.
• TLS_ENABLED (new in 1.5.0) specifies whether to use TLS when talking to Redis.
• TLS_INSECURE (new in 1.5.0) specifies whether to skip certificate verification when using TLS to talk to Redis. Alternatively, consider installing Redis' self-signed certificate in to the Ambassador Edge Stack container in order to leave certificate verification on.

Redis authentication (auth)

• If PASSWORD (new in 1.5.0) is non-empty, then it is used to AUTH to Redis immediately after the connection is established.
• If USERNAME (new in 1.5.0) is set, then that username is used with the password to log in as that user in the Redis 6 ACL. It is invalid to set a username without setting a password. It is invalid to set a username with Redis 5 or lower.
• If AUTH (only available when AES_RATELIMIT_PREVIEW=true) is set, the value will be used as the password to authenticate to redis (with username default).

Redis performance tuning (tune)

• POOL_SIZE is 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.

• PING_INTERVAL (new in 1.6.0; changed in 1.7.0) Of the idle connections in the normal pool (not extra connections created for a load surge), Ambassador will PING one of them every PING_INTERVAL÷POOL_SIZE; each connection will on average be PINGed every PING_INTERVAL. (Backward incompatibility: in 1.6.x Ambassador did not divide by POOL_SIZE; which itself was backward-incompatible from the pre-1.6.0 behavior of using 10s÷POOL_SIZE; 1.7.0 defaults to the pre-1.6.0 behavior.) (Backward incompatibility: in 1.7.0 this changed from an integer number of seconds to a duration-string; enabling sub-second values.)

• TIMEOUT (new in 1.6.0; changed in 1.7.0) 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) (since 1.7.0)

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

  (Backward incompatibility: in 1.7.0 this was renamed from IO_TIMEOUT to TIMEOUT; changed from an integer number of seconds to a duration-string, enabling sub-second values; and the default value changed from "10s" to "0", defaulting to the pre-1.6.0 behavior.)

• SURGE_LIMIT_INTERVAL (new in 1.7.0) 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 SURGE_LIMIT_INTERVAL. A value of "0" (the default) means "allow new connections to be created as fast as necessary. (Backward incompatibility: in 1.6.x this was a non-configurable "1s"; in 1.7.0 the default value is "0", defaulting to the pre-1.6.0 behavior.) The total number of connections that Ambassador can surge to is unbounded.

• SURGE_LIMIT_AFTER (new in 1.7.0) is how many connections after the normal pool is depleted can be created before SURGE_LIMIT_INTERVAL kicks in; the first POOL_SIZE+SURGE_LIMIT_AFTER connections are allowed to be created as fast as necessary. This setting has no effect if SURGE_LIMIT_INTERVAL is 0.

• SURGE_POOL_SIZE (new in 1.6.0; changed in 1.7.0) Normally during a surge, excess connections beyond POOL_SIZE are closed immediately after they are done being used, instead of being returned to a pool. SURGE_POOL_SIZE configures a "reserve" pool of size SURGE_POOL_SIZE for excess connections created during a surge. Excess connections beyond POOL_SIZE+SURGE_POOL_SIZE will still be closed immediately after use. (Backward incompatibility: in 1.7.0 this was renamed from POOL_MAX_SIZE to SURGE_POOL_SIZE; and the default value was changed from "20" to "0", now defaulting to the pre-1.6.0 behavior.)

• SURGE_POOL_DRAIN_INTERVAL (new in 1.7.0) is how quickly to drain connections from the surge pool after a surge is over; connections are closed at a rate of one connection per SURGE_POOL_DRAIN_INTERVAL. This setting has no effect if SURGE_POOL_SIZE is 0.

• TYPE (only available when AES_RATELIMIT_PREVIEW=true) specifies the type of the redis deployment. Options are:

  • SINGLE: Talk to a single instance of redis, or a redis proxy. Requires the redis REDIS_URL or REDIS_PERSECOND_URL to be either a single hostname:port pair or a unix domain socket reference.
  • SENTINEL: Talk to a redis deployment with sentinel instances (see https://redis.io/topics/sentinel). Requires the redis REDIS_URL or REDIS_PERSECOND_URL to be a comma separated list with the first string as the master name of the sentinel cluster followed by hostname:port pairs. The list size should be >= 2. The first item is the name of the master and the rest are the sentinels.
  • CLUSTER: Talk to a redis in cluster mode (see https://redis.io/topics/cluster-spec) Requires the redis REDIS_URL or REDIS_PERSECOND_URL to be a comma separated list of hostname:port pairs with all the nodes in the cluster.

• PIPELINE_WINDOW sets the duration after which internal pipelines will be flushed. If window is zero then implicit pipelining will be disabled.

• PIPELINE_LIMIT sets maximum number of commands that can be pipelined before flushing. If limit is zero then no limit will be used and pipelines will only be limited by the specified time window.

Port Assignments

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