Major Changes in Emissary 2.X
The 2.X family introduces a number of changes to allow Emissary 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 Emissary 2 is functionally compatible with Emissary 1.14, note that this is a major version change and there are important differences between Emissary 1.X and Emissary $version$. For details, read on.
1. Configuration API Version getambassador.io/v3alpha1
Emissary 2.0 introduced API version getambassador.io/v3alpha1
to allow
certain changes in configuration resources that are not backwards compatible with
Emissary 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.
getambassador.io/v2
and getambassador.io/v3alpha1
. If you are using any resources with
older API versions, you will need to upgrade them.
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
Emissary 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 Emissary 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 Emissary, and must be defined by the user. If you do not
define any Listener
s, Emissary 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:
apiVersion: getambassador.io/v3alpha1
kind: listener
metadata:
name: all-hosts-listener
spec:
port: 8080
securityModel: XFP
protocol: HTTPS
hostBinding:
namespace:
from: ALL
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 Emissary.
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.
Listener
.Learn more about
Host
.
Wildcard Host
s No Longer Created
In Emissary 1.X, Emissary would make sure that a wildcard Host
, with a hostname
of "*"
, was always present.
Emissary 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 Emissary 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
.
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 Emissary 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.
Host
.Learn more about
Mapping
.
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
.
Host
, TLSContext
, and TLS Termination
As of Emissary 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:
---
kind: Secret
type: kubernetes.io/tls
metadata:
name: minimal-secret
data:
tls secret goes here
---
apiVersion: getambassador.io/v3alpha1
kind: Host
metadata:
name: minimal-host
spec:
hostname: minimal.example.com
tlsSecret:
name: minimal-secret
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 Emissary Communications.
Host
.Learn more about
TLSContext
.
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
.
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.
Mapping
.
3. Other Changes
Envoy V3 API by Default
By default, Emissary 2.X will configure Envoy using the
V3 Envoy API. In Emissary
$version$, you may switch back to Envoy V2 by setting the AMBASSADOR_ENVOY_API_VERSION
environment variable to “V2”; in Emissary 2.2.0, support for the Envoy V2 API (and
the AMBASSADOR_ENVOY_API_VERSION
environment variable) will be removed.
More Performant Reconfiguration by Default
In Emissary 1.X, the environment variable AMBASSADOR_FAST_RECONFIGURE
could be used to enable a higher performance implementation of the code Emissary uses to validate and generate Envoy configuration. In Emissary 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 Emissary 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.
Listener
.
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 Emissary Communications.
Service Preview No Longer Supported
Service Preview is no longer supported as of Emissary 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 Emissary 2.X, in favor of Ambassador Cloud.
Project
CRD No Longer Supported
The Project
CRD has been removed as of Emissary 2.X, in favor of Argo.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.