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
AmbassadorAMBASSADOR_IDdefaultPlain string
AmbassadorAMBASSADOR_NAMESPACEdefault (1)Kubernetes namespace
AmbassadorAMBASSADOR_SINGLE_NAMESPACEEmptyBoolean; non-empty=true, empty=false
AmbassadorAMBASSADOR_ENVOY_BASE_ID0Integer
AmbassadorAMBASSADOR_FAST_VALIDATIONEmptyEXPERIMENTAL -- Boolean; non-empty=true, empty=false
AmbassadorAMBASSADOR_UPDATE_MAPPING_STATUSfalseBoolean; true=true, any other value=false
Ambassador Edge StackAES_LOG_LEVELinfoLog level (see below)
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_USERNAMEEmptyPlain string
Primary Redis (auth)REDIS_PASSWORDEmptyPlain string
Primary Redis (tune)REDIS_POOL_SIZE10Integer
Primary Redis (tune)REDIS_POOL_MAX_SIZE20Integer
Primary Redis (tune)REDIS_PING_INTERVAL10Integer (seconds)
Primary Redis (tune)REDIS_IO_TIMEOUT10Integer (seconds)
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 (tune)REDIS_PERSECOND_POOL_SIZE10Integer
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_POOL_MAX_SIZE20Integer
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_PING_INTERVAL10Integer (seconds)
Per-Second RateLimit Redis (tune)REDIS_PERSECOND_IO_TIMEOUT10Integer (seconds)
RateLimitEXPIRATION_JITTER_MAX_SECONDS300Integer
RateLimitUSE_STATSDfalseBoolean; Go strconv.ParseBool
RateLimitSTATSD_HOSTlocalhostHostname
RateLimitSTATSD_PORT8125Integer
RateLimitGOSTATS_FLUSH_INTERVAL_SECONDS5Integer
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

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.

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.

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) 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 seconds; each connection will on average be PINGed every PING_INTERVAL×POOL_SIZE seconds; increasing POOL_SIZE without reducing PING_INTERVAL will increase the amount of time between PINGs on a given connection. (Backward incompatibility: prior to the introduction of this setting in 1.6.0 this was non-configurable and Ambassador would PING a connection every 10÷POOL_SIZE seconds, as if PING_INTERVAL=10÷POOL_SIZE.)
  • IO_TIMEOUT (new in 1.6.0) sets 3 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

During a load surge, if the pool is depleted, then Ambassador allows new connections to be created as fast as necessary for the first POOL_SIZE connections; once the number of connections reaches 2×POOL_SIZE Ambassador limits creation of new connections to once per second. (Backward incompatibility: prior to 1.6.0 the creation of new connections was never limited during a surge.) The total number of connections that Ambassador can surge to is unbounded.

  • POOL_MAX_SIZE (new in 1.6.0) During a load surge, instead of closing connections immediately after use, they are placed in to a "reserve" pool of size POOL_MAX_SIZE. (Backward incompatibility: prior to 1.6.0 there was no reserve pool.) Excess connections beyond POOL_SIZE+POOL_MAX_SIZE will still be closed immediately after use. Connections in the reserve pool are drained at a rate of 1 connection per minute.

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
8080envoyDefault HTTP service port
8443envoyDefault HTTPS service port

  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, contact us, or request a demo.