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.11.1. For details, read on.
1. Configuration API Version getambassador.io/v3alpha1
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
mandatory Listener
resource; however, there are important changes
in Host
and Mapping
as well.
API version getambassador.io/v3alpha1
replaces x.getambassador.io/v3alpha1
from
the 2.0 developer previews. getambassador.io/v3alpha1
may still change as we receive
feedback.
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 getambassador.io/v3alpha1
:
ambassador_id
must always be a list of stringsHost.mappingSelector
supersedesHost.selector
, and controls association between Hosts and MappingsMapping.hostname
supersedesMapping.host
andMapping.host_regex
Mapping.tls
can only be a stringMapping.labels
always requires maps instead of strings
2. Listener
s, Host
s, and Mapping
s
Ambassador Edge Stack 2.0 introduced the new mandatory Listener
CRD, and made some changes
to the Host
and Mapping
resources.
The Listener
CRD
The new 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.
Note that Listener
s are never created by Ambassador Edge Stack, and must be defined by the user. If you do not
define any Listener
s, Ambassador Edge Stack will not listen anywhere for connections, and therefore won't do
anything useful. It will log a WARNING
to this effect.
A Listener
specifically defines
port
: a port number on which to listen for new requests;protocol
andsecurityModel
: the protocol stack and security model to use (e.g.HTTPS
using theX-Forwarded-Proto
header); andhostBinding
: how to tell if a givenHost
should be associated with thisListener
:- a
Listener
can choose to consider allHost
s, or onlyHost
s in the same namespace as theListener
, or - a
Listener
can choose to consider onlyHost
s with a particular Kuberneteslabel
.
- a
Note that the hostBinding
is mandatory. A Listener
must specify how to identify the Host
s 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 Host
s: if you truly need a Listener
that associates with all Host
s, the easiest way is to tell the Listener
to look for Host
s in all namespaces, with no further selectors, for example:
A Listener
that has no associated Host
s 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 Listener
s may be created, and as such no limit on the number of ports to which a Host
may be associated.
Wildcard Host
s No Longer Created
In Ambassador Edge Stack 1.X, Ambassador Edge Stack would make sure that a wildcard Host
, with a hostname
of "*"
, 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
a 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
hostname
of foo.example.com
, then:
- requests to
http://foo.example.com/
will work, but - requests to
http://10.11.12.13/
will not work.
Adding a Host
with a hostname
of "*"
will allow the second query to work.
Host
and Mapping
Association
The 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:
The
Mapping
specifies ahostname
attribute that matches theHost
in question.- Note that a
getambassador.io/v2
Mapping
hashost
andhost_regex
, rather thanhostname
.- A
getambassador.io/v3alpha1
Mapping
will honorhost
andhost_regex
as a transition aid, buthost
andhost_regex
are deprecated in favor ofhostname
. - A
Mapping
that specifieshost_regex: true
will be associated with allHost
s. This is generally far less desirable than usinghostname
with a DNS glob.
- A
- Note that a
The
Host
specifies amappingSelector
that matches theMapping
's Kuberneteslabel
s.- Note that a
getambassador.io/v2
Host
has aselector
, rather than amappingSelector
.- A
getambassador.io/v3alpha1
Host
ignoresselector
and, instead, looks only atmappingSelector
. - Where a
selector
got a default value if not specified,mappingSelector
must be explicitly stated.
- A
- 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 Host
s and large numbers of Mapping
s.
Independent Host
Actions
Each Host
can specify its requestPolicy.insecure.action
independently of any other Host
, allowing for HTTP routing as flexible as HTTPS routing.
Host
, TLSContext
, and TLS Termination
As of Ambassador Edge Stack 2.0, Host
s 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 Host
: setting 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.
Mapping
s, TCPMapping
s, and TLS Origination
A getambassador.io/v2
Mapping
or 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
s and labels
The Mapping
CRD includes a labels
field, used with rate limiting. The
syntax of the labels
has changed
for compatibility with Kubernetes 1.22.
Host
s 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 ambassador
Module
, and the tls
Module
It is no longer possible to configure TLS using the tls
element of the ambassador
Module
or using the tls
Module
. Both of these cases are correctly covered by the TLSContext
resource.
With the introduction of the Listener
resource, a few settings have moved from the Module
to the Listener
.
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 ambassador
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 Listener
documentation.
xff_num_trusted_hops
has been removed from the Module
, and its functionality has been moved to the l7Depth
setting in the Listener
resource.
TLSContext
redirect_cleartext_from
and Host
insecure.additionalPort
redirect_cleartext_from
has been removed from the TLSContext
resource; insecure.additionalPort
has been removed from the Host
CRD. Both of these cases are covered by adding additional Listener
s. 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
The Project
CRD has been removed as of Ambassador Edge Stack 2.X, in favor of Argo.