DocsEdge StackMajor Changes in Ambassador Edge Stack 2.X
Major Changes in Ambassador Edge Stack 2.X
The 2.X family introduces a number of changes to allow Ambassador Edge Stack to more gracefully handle larger installations, reduce global configuration to better handle multitenant or multiorganizational installations, reduce memory footprint, and improve performance. We welcome feedback!! Join us on Slack and let us know what you think.
While Ambassador Edge Stack 2 is functionally compatible with Ambassador Edge Stack 1.14, note that this is a major version change and there are important differences between Ambassador Edge Stack 1.X and Ambassador Edge Stack 3.5.1. For details, read on.
1. Configuration API Version
Ambassador Edge Stack 2.0 introduced API version
getambassador.io/v3alpha1 to allow
certain changes in configuration resources that are not backwards compatible with
Ambassador Edge Stack 1.X. The most notable example of change is the addition of the
Listener resource; however, there are important changes
Mapping as well.
the 2.0 developer previews.
getambassador.io/v3alpha1 may still change as we receive
2. Kubernetes 1.22 and Structural CRDs
Kubernetes 1.22 requires structural CRDs.
This change is primarily meant to support better CRD validation, but it also has the
effect that union types are no longer allowed in CRDs: for example, an element that can be
either a string or a list of strings is not allowed. Several such elements appeared in the
getambassador.io/v2 CRDs, requiring changes. In
ambassador_idmust always be a list of strings
Host.selector, and controls association between Hosts and Mappings
Mapping.tlscan only be a string
Mapping.labelsalways requires maps instead of strings
Ambassador Edge Stack 2.0 introduced the new mandatory
Listener CRD, and made some changes
Listener CRD defines where and how Ambassador Edge Stack should listen for requests from the network, and which
Host definitions should be used to process those requests.
Listeners are never created by Ambassador Edge Stack, and must be defined by the user. If you do not
Listeners, Ambassador Edge Stack will not listen anywhere for connections, and therefore won't do
anything useful. It will log a
WARNING to this effect.
Listener specifically defines
port: a port number on which to listen for new requests;
securityModel: the protocol stack and security model to use (e.g.
hostBinding: how to tell if a given
Hostshould be associated with this
Listenercan choose to consider all
Hosts, or only
Hosts in the same namespace as the
Listenercan choose to consider only
Hosts with a particular Kubernetes
Note that the
hostBinding is mandatory. A
Listener must specify how to identify the
Hosts to associate with the
Listener', or the
Listener will be rejected. This is intended to help prevent cases where a
Listener mistakenly grabs too many
Hosts: if you truly need a
Listener that associates with all
Hosts, the easiest way is to tell the
Listener to look for
Hosts in all namespaces, with no further selectors, for example:
Listener that has no associated
Hosts will be logged as a
WARNING, and will not be included in the Envoy configuration generated by Ambassador Edge Stack.
Note also that there is no limit on how many
Listeners may be created, and as such no limit on the number of ports to which a
Host may be associated.
Hosts No Longer Created
In Ambassador Edge Stack 1.X, Ambassador Edge Stack would make sure that a wildcard
Host, with a
"*", was always present.
Ambassador Edge Stack 2.X does not force a wildcard
Host: if you need the wildcard behavior, you will need to create
Host with a hostname of
Of particular note is that Ambassador Edge Stack will not respond to queries to an IP address unless a wildcard
Host is present. If
foo.example.com resolves to
10.11.12.13, and the only
Host has a
- requests to
http://foo.example.com/will work, but
- requests to
http://10.11.12.13/will not work.
Host with a
"*" will allow the second query to work.
Host CRD continues to define information about hostnames, TLS certificates, and how to handle requests that are "secure" (using HTTPS) or "insecure" (using HTTP). The
Mapping CRD continues to define how to map the URL space to upstream services.
However, as of Ambassador Edge Stack 2.0, a
Mapping will not be associated with a
Host unless at least one of the following is true:
hostnameattribute that matches the
- Note that a
host_regex, rather than
host_regexas a transition aid, but
host_regexare deprecated in favor of
host_regex: truewill be associated with all
Hosts. This is generally far less desirable than using
hostnamewith a DNS glob.
- Note that a
mappingSelectorthat matches the
- Note that a
selector, rather than a
selectorand, instead, looks only at
- Where a
selectorgot a default value if not specified,
mappingSelectormust be explicitly stated.
- Note that a
Without either a
hostname match or a
label match, the
Mapping will not be associated with the
Host in question. This is intended to help manage memory consumption with large numbers of
Hosts and large numbers of
Host can specify its
requestPolicy.insecure.action independently of any other
Host, allowing for HTTP routing as flexible as HTTPS routing.
TLSContext, and TLS Termination
As of Ambassador Edge Stack 2.0,
Hosts are required for TLS termination. It is no longer sufficient to create a
TLSContext by itself; the
Host is required.
The minimal setup for TLS termination is therefore a Kubernetes
Secret of type
kubernetes.io/tls, and a
Host that uses it:
It is not necessary to explicitly state a
TLSContext in the
tlsSecret is enough. Of course,
TLSContext is still the ideal way to share TLS configuration between more than one
Host. For further examples, see Configuring Ambassador Edge Stack Communications.
TCPMappings, and TLS Origination
TCPMapping could specify
tls: true to indicate TLS origination without supplying a certificate. This is not supported in
getambassador.io/v3alpha1: instead, use an
https:// prefix on the
service. In the Mapping, this is straightforward, but there are more details for the
TCPMapping when using TLS.
Mapping CRD includes a
labels field, used with rate limiting. The
syntax of the
labels has changed
for compatibility with Kubernetes 1.22.
Hosts and ACME
In Ambassador Edge Stack 2.0, ACME will be disabled if a
Host does not set
acmeProvider at all (prior to Ambassador Edge Stack 2.0, not mentioning
acmeProvider would result in the ACME client attempting, and failing, to start). If
acmeProvider is set, but
acmeProvider.authority is not set, the ACME client will continue to default to Let's Encrypt, in order to preserve compatibility with Ambassador Edge Stack prior to Ambassador Edge Stack 2.0. For further examples, see Configuring Ambassador Edge Stack to Communicate.
3. Other Changes
Envoy V3 API by Default
By default, Ambassador Edge Stack 2.X will configure Envoy using the V3 Envoy API.
More Performant Reconfiguration by Default
In Ambassador Edge Stack 1.X, the environment variable
AMBASSADOR_FAST_RECONFIGURE could be used to enable a higher performance implementation of the code Ambassador Edge Stack uses to validate and generate Envoy configuration. In Ambassador Edge Stack 2.X, this higher-performance mode is always enabled.
Changes to the
Module, and the
It is no longer possible to configure TLS using the
tls element of the
Module or using the
Module. Both of these cases are correctly covered by the
With the introduction of the
Listener resource, a few settings have moved from the
Module to the
Configuration for the
PROXY protocol is part of the
Listener resource in Ambassador Edge Stack 2.X, so the
use_proxy_protocol element of the
Module is no longer supported. Note that the
Listener resource can configure
PROXY resource per-
Listener, rather than having a single global setting. For further information, see the
xff_num_trusted_hops has been removed from the
Module, and its functionality has been moved to the
l7Depth setting in the
redirect_cleartext_from has been removed from the
insecure.additionalPort has been removed from the
Host CRD. Both of these cases are covered by adding additional
Listeners. For further examples, see Configuring Ambassador Edge Stack Communications.
Service Preview No Longer Supported
Service Preview is no longer supported as of Ambassador Edge Stack 2.X, as its use cases are supported by Telepresence.
Edge Policy Console No Longer Supported
The Edge Policy Console has been removed as of Ambassador Edge Stack 2.X, in favor of Ambassador Cloud.
Project CRD No Longer Supported
Project CRD has been removed as of Ambassador Edge Stack 2.X, in favor of Argo.