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 RedisREDIS_POOL_SIZE10Integer
Primary RedisREDIS_POOL_MAX_SIZE20Integer
Primary RedisREDIS_SOCKET_TYPENone, must be set explicitlyGo network such as tcp or unix; see Go net.Dial
Primary RedisREDIS_URLNone, must be set explicitlyGo network address; for TCP this is a host:port pair; see Go net.Dial
Primary RedisREDIS_USERNAMEEmptyPlain string
Primary RedisREDIS_PASSWORDEmptyPlain string
Primary RedisREDIS_TLS_ENABLEDfalseBoolean; Go strconv.ParseBool
Primary RedisREDIS_TLS_INSECUREfalseBoolean; Go strconv.ParseBool
Primary RedisREDIS_PING_INTERVAL10Integer (seconds)
Primary RedisREDIS_IO_TIMEOUT10Integer (seconds)
Per-Second RateLimit RedisREDIS_PERSECONDfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit RedisREDIS_PERSECOND_POOL_SIZE10Integer
Per-Second RateLimit RedisREDIS_PERSECOND_POOL_MAX_SIZE20Integer
Per-Second RateLimit RedisREDIS_PERSECOND_SOCKET_TYPENone, must be set explicitly (if REDIS_PERSECOND)Go network such as tcp or unix; see Go net.Dial
Per-Second RateLimit RedisREDIS_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 RedisREDIS_PERSECOND_USERNAMEEmptyPlain string
Per-Second RateLimit RedisREDIS_PERSECOND_PASSWORDEmptyPlain string
Per-Second RateLimit RedisREDIS_PERSECOND_TLS_ENABLEDfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit RedisREDIS_PERSECOND_TLS_INSECUREfalseBoolean; Go strconv.ParseBool
Per-Second RateLimit RedisREDIS_PERSECOND_PING_INTERVAL10Integer (seconds)
Per-Second RateLimit RedisREDIS_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; there will be a total of up to REDIS_POOL_SIZE connections to Redis. 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.

If REDIS_PASSWORD (or REDIS_PERSECOND_PASSWORD) is non-empty, then it is used to AUTH to Redis immediately after the connection is established. If REDIS_USERNAME (or REDIS_PERSECOND_USERNAME) is set, then that username is used with 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 REDIS_TLS_ENABLED (or REDIS_PERSECOND_TLS_ENABLED) is true, then TLS is used when communicating with Redis. Setting REDIS_TLS_INSECURE (or REDIS_PERSECOND_TLS_INSECURE) to true disables TLS verification when doing so; alternatively, consider installing Redis' self-signed certificate in to the Ambassador Edge Stack container.

Note that when using a port name instead of a port number in a Go network address (as as in REDIS_URL or REDIS_PERSECOND_URL), the name refers a well-known port name in the container's /etc/services, and not to a Kubernetes port name.

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.