Search the Docs

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:

PurposeVariableDefault valueValue type
CoreAMBASSADOR_IDdefaultPlain string
CoreAMBASSADOR_NAMESPACEdefault (1)Kubernetes namespace
CoreAMBASSADOR_SINGLE_NAMESPACEEmptyBoolean; non-empty=true, empty=false
CoreAMBASSADOR_ENVOY_BASE_ID0Integer
CoreAMBASSADOR_LEGACY_MODEfalseBoolean; Go strconv.ParseBool
CoreAMBASSADOR_FAST_RECONFIGUREfalseEXPERIMENTAL -- Boolean; true=true, any other value=false
CoreAMBASSADOR_UPDATE_MAPPING_STATUSfalseBoolean; true=true, any other value=false
CoreAMBASSADOR_DISABLE_SNAPSHOT_SERVERfalseBoolean; non-empty=true, empty=false
Edge StackAES_LOG_LEVELinfoLog level (see below)
Edge StackAES_RATELIMIT_PREVIEWfalseBoolean; Go strconv.ParseBool
Primary Redis (L4)REDIS_SOCKET_TYPEtcpGo network such as tcp or unix; see Go net.Dial
Primary Redis (L4)REDIS_URLNone, must be set explicitlyGo network address; for TCP this is a host:port pair; see Go net.Dial
Primary Redis (L4)REDIS_TLS_ENABLEDfalseBoolean; Go strconv.ParseBool
Primary Redis (L4)REDIS_TLS_INSECUREfalseBoolean; Go strconv.ParseBool
Primary Redis (auth)REDIS_AUTHEmptyRequires AES_RATELIMIT_PREVIEW; Plain string
Primary Redis (auth)REDIS_USERNAMEEmptyPlain string
Primary Redis (auth)REDIS_PASSWORDEmptyPlain string
Primary Redis (tune)REDIS_POOL_SIZE10Integer
Primary Redis (tune)REDIS_PING_INTERVAL10sDuration; Go time.ParseDuration
Primary Redis (tune)REDIS_TIMEOUT0sDuration; Go time.ParseDuration
Primary Redis (tune)REDIS_SURGE_LIMIT_INTERVAL0sDuration; Go time.ParseDuration
Primary Redis (tune)REDIS_SURGE_LIMIT_AFTERThe value of REDIS_POOL_SIZEInteger
Primary Redis (tune)REDIS_SURGE_POOL_SIZE0Integer
Primary Redis (tune)REDIS_SURGE_POOL_DRAIN_INTERVAL1mDuration; Go time.ParseDuration
Primary Redis (tune)REDIS_PIPELINE_WINDOW0Requires AES_RATELIMIT_PREVIEW; Duration; Go time.ParseDuration
Primary Redis (tune)REDIS_PIPELINE_LIMIT0Requires AES_RATELIMIT_PREVIEW; Integer; [Go strconv.ParseInt][]
Primary Redis (tune)REDIS_TYPESINGLERequires AES_RATELIMIT_PREVIEW; String; SINGLE, SENTINEL, or CLUSTER
Per-Second RateLimit RedisREDIS_PERSECONDfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit Redis (L4)REDIS_PERSECOND_SOCKET_TYPENone, must be set explicitly (if REDIS_PERSECOND)Go network such as tcp or unix; see Go net.Dial
Per-Second RateLimit Redis (L4)REDIS_PERSECOND_URLNone, must be set explicitly (if REDIS_PERSECOND)Go network address; for TCP this is a host:port pair; see Go net.Dial
Per-Second RateLimit Redis (L4)REDIS_PERSECOND_TLS_ENABLEDfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit Redis (L4)REDIS_PERSECOND_TLS_INSECUREfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit Redis (auth)REDIS_PERSECOND_USERNAMEEmptyPlain string
Per-Second RateLimit Redis (auth)REDIS_PERSECOND_PASSWORDEmptyPlain string
Per-Second RateLimit Redis (auth)REDIS_PERSECOND_AUTHEmptyRequires AES_RATELIMIT_PREVIEW; Plain string
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_POOL_SIZE10Integer
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_PING_INTERVAL10sDuration; Go time.ParseDuration
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_TIMEOUT0sDuration; Go time.ParseDuration
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_SURGE_LIMIT_INTERVAL0sDuration; Go time.ParseDuration
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_SURGE_LIMIT_AFTERThe value of REDIS_PERSECOND_POOL_SIZEInteger
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_SURGE_POOL_SIZE0Integer
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_SURGE_POOL_DRAIN_INTERVAL1mDuration; Go time.ParseDuration
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_TYPESINGLERequires AES_RATELIMIT_PREVIEW; String; SINGLE, SENTINEL, or CLUSTER
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_PIPELINE_WINDOW0Requires AES_RATELIMIT_PREVIEW; Duration; Go time.ParseDuration
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_PIPELINE_LIMIT0Requires AES_RATELIMIT_PREVIEW; Integer
RateLimitEXPIRATION_JITTER_MAX_SECONDS300Integer
RateLimitUSE_STATSDfalseBoolean; Go strconv.ParseBool
RateLimitSTATSD_HOSTlocalhostHostname
RateLimitSTATSD_PORT8125Integer
RateLimitGOSTATS_FLUSH_INTERVAL_SECONDS5Integer
RateLimitLOCAL_CACHE_SIZE_IN_BYTES0Requires AES_RATELIMIT_PREVIEW; Integer
RateLimitNEAR_LIMIT_RATIO0.8Requires AES_RATELIMIT_PREVIEW; Float; [Go strconv.ParseFloat][]
Developer PortalAMBASSADOR_URLhttps://api.example.comURL
Developer PortalDEVPORTAL_CONTENT_URLhttps://github.com/datawire/devportal-contentgit-remote URL
Developer PortalDEVPORTAL_CONTENT_DIR/Rooted Git directory
Developer PortalDEVPORTAL_CONTENT_BRANCHmasterGit branch name
Developer PortalPOLL_EVERY_SECS60Integer
EnvoySTATSD_ENABLEDfalseBoolean; Python value.lower() == "true"
EnvoyDOGSTATSDfalseBoolean; Python value.lower() == "true"
EnvoyENVOY_CONCURRENCYEmptyInteger

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:

PortProcessFunction
8001envoyInternal stats, logging, etc.; not exposed outside pod
8002wattInternal watt snapshot access; not exposed outside pod
8003ambexInternal ambex snapshot access; not exposed outside pod
8004diagdInternal diagd access when AMBASSADOR_FAST_RECONFIGURE is set; not exposed outside pod
8005snapshotExposes a scrubbed ambassador snapshot outside of the pod
8080envoyDefault HTTP service port
8443envoyDefault HTTPS service port
8877diagdDirect access to diagnostics UI; provided by busyambassador entrypoint when AMBASSADOR_FAST_RECONFIGURE is set

  1. This may change in a future release to reflect the Pods's namespace if deployed to a namespace other than default. https://github.com/datawire/ambassador/issues/1583

Questions?

We’re here to help. If you have questions, join our Slack or contact us.