Listener CRD defines where, and how, Emissary-ingress should listen for requests from the network, and which
Host definitions should be used to process those requests. For further examples of how to use
Listener, see Configuring Emissary-ingress Communications.
Listeners are never created by Emissary-ingress, and must be defined by the user. If you do not
Listeners, Emissary-ingress will not listen anywhere for connections, and therefore won't do
anything useful. It will log a
WARNING to this effect.
---apiVersion: getambassador.io/v3alpha1kind: Listenermetadata:name: example-listenerspec:port: 8080 # int32, port number on which to listenprotocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCPsecurityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECUREstatsPrefix: example-listener # default depends on protocol; see belowl7Depth: 0 # int32hostBinding:namespace:from: SELF # SELF, ALLselector: ... # Kubernetes label selector
|The network port on which Emissary-ingress should listen. Required.|
|A high-level protocol type, like "HTTPS". Exactly one of |
|array of ||A sequence of low-level protocols to layer together. Exactly one of |
|How does Emissary-ingress decide whether requests here are secure? Required.|
|Under what name do statistics for this |
|How many layer 7 load balancers are between the edge of the network and Emissary-ingress? Optional; default is 0.|
|Mechanism for determining which |
protocol is the recommended way to tell Emissary-ingress that a
Listener expects connections using a well-known protocol. When using
protocolStack may not also be supplied.
protocol values are:
|Cleartext-only HTTP. HTTPS is not allowed.|
|Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set |
|Cleartext-only HTTP, using the HAProxy |
|Either HTTPS or HTTP, using the HAProxy |
|TCP sessions without HTTP at all. You will need to use |
|TLS sessions without HTTP at all. You will need to use |
securityModel defines how the
Listener will decide whether a request is secure or insecure:
|Requests are secure if, and only if, |
|Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients.|
|Requests are always insecure. You might set this for an HTTP-only |
X-Forwarded-Proto header mentioned above is meant to reflect the protocol the original client
used to contact Emissary-ingress. When no layer 7 proxies are in use, Envoy will make certain that the
X-Forwarded-Proto header matches the wire protocol of the connection the client made to Envoy,
which allows Emissary-ingress to trust
X-Forwarded-Proto for routing decisions such as deciding to
redirect requests made using HTTP over to HTTPS for greater security. When using Emissary-ingress as an
edge proxy or a typical API gateway, this is a desirable configuration; setting
XFP makes this easy.
When layer proxies are in use, the
XFP setting is often still desirable; however, you will also
need to set
l7Depth to allow it to function. See below.
INSECURE are helpful for cases where something downstream of Emissary-ingress should be
allowing only one kind of request to reach Emissary-ingress. For example, a
Listener behind a load
balancer that terminates TLS and checks client certificates might use
SecurityModel: SECURE, then use
Hosts to reject insecure requests if one somehow
When layer 7 (L7) proxies are in use, the connection to Emissary-ingress comes from the L7 proxy itself
rather than from the client. Examining the protocol and IP address of that connection is useless, and
instead you need to configure the L7 proxy to pass extra information about the client to Emissary-ingress
However, if Emissary-ingress always trusted
X-Forwarded-For, any client could
use them to lie about itself to Emissary-ingress. As a security mechanism, therefore, you must also
l7Depth in the
Listener to the number of trusted L7 proxies in front of Emissary-ingress. If
l7Depth is not set in the
xff_num_trusted_hops value from the
will be used. If neither is set, the default
l7Depth is 0.
l7Depth is 0, any incoming
X-Forwarded-Proto is stripped: Envoy always provides an
X-Forwarded-Proto matching the wire protocol of the incoming connection, so that
can be trusted. When
l7Depth is non-zero,
X-Forwarded-Proto is accepted from the L7 proxy, and
trusted. The actual wire protocol in use from the L7 proxy to Emissary-ingress is ignored.
l7Depth also affects Emissary-ingress's view of the client's source IP address, which is used as the
remote_address field when rate limiting, and for the
l7Depthis 0, Emissary-ingress uses the IP address of the incoming connection.
l7Depthis some value N that is non-zero, the behavior is determined by the value of
use_remote_addressis true (the default) then the trusted client address will be the Nth address from the right end of the
X-Forwarded-Forheader. (If the XFF contains fewer than N addresses, Envoy falls back to using the immediate downstream connection’s source address as a trusted client address.)
use_remote_addressis false, the trusted client address is the (N+1)th address from the right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the immediate downstream connection’s source address as a trusted client address.)
For more detailed examples of this interaction, refer to Envoy's documentation.
hostBinding specifies how this
Listener should determine which
Hosts are associated with it:
Hosts by the namespace of the
namespace.from: SELFaccepts only
Hosts in the same namespace as the
Hosts in any namespace.
Hosts that has labels matching the selector.
hostBinding is mandatory, and at least one of
selector must be set. If both are set, both must match for a
Host to be accepted.
Emissary-ingress produces detailed statistics which can be monitored in a variety of ways. Statistics have hierarchical names, and the
Listener will cause a set of statistics to be logged under the name specified by
statsPrefix depends on the protocol for this
- If the
Listenerspeaks HTTPS, the default is
- Otherwise, if the
Listenerspeaks HTTP, the default is
- Otherwise, if the
Listenerspeaks TLS, the default is
- Otherwise, the default is
Note that it doesn't matter whether you use
protocolStack: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy
PROXY protocol into account.
---apiVersion: getambassador.io/v3alpha1kind: Listenermetadata:name: example-listenerspec:port: 8080protocol: HTTPS...
will use a
---apiVersion: getambassador.io/v3alpha1kind: Listenermetadata:name: example-listenerspec:port: 8080protocol: TCP...
---apiVersion: getambassador.io/v3alpha1kind: Listenermetadata:name: example-listenerspec:port: 8080protocol: HTTPSPROXYstatsPrefix: proxy-8080...
would also use
ingress-https, but it explicitly overrides
For complete information on which statistics will appear for the
Listener, see the Envoy listener statistics documentation. Some important statistics include
|Gauge||Total active connections|
|Histogram||Connection length in milliseconds|
protocolStack is not recommended if you can instead use
protocol allows configuring the
Listener to use well-known protocol stacks,
protocolStack allows configuring exactly which protocols will be layered together. If
protocol allows what you need, it is safer to use
Protocol than to risk having the stack broken with an incorrect
The possible stack elements are:
|Cleartext-only HTTP; must be layered with |
|The HAProxy |
protocolStack supplies a list of these elements to describe the protocol stack. Order matters. Some examples:
|[ ||Cleartext-only HTTP, exactly equivalent to |
|[ ||HTTPS or HTTP, exactly equivalent to |
|[ ||The |
For further examples of how to use
Listener, see Configuring Emissary-ingress to Communicate.
ON THIS PAGE