Any number of listener
objects are attached to each proxy in order to receive incoming traffic. Their main use is to specify the address, port, and protocol that will be used to receive incoming requests. A sidecar can have as many Listeners created as is needed, though at least one listener must exist or it will not be able to receive any traffic.
WARNING At least one listener must be allocated for a proxy to receive traffic. Additionally, the
port
exposed by thatlistener
must match the port advertised to the service discovery mechanism in use.NOTE Listeners can also be configured directly in the
proxy
objects. When defined there, they cannot be shared among multiple proxies, but saves the user from creating additional config objects.
A common usage pattern is for 2-3 listeners on each sidecar. One listener is setup to listen on all network interfaces (0.0.0.0) and will receive traffic from the rest of the mesh. This is the port that is advertised in service discovery. This listener would have configurations for AuthN and AuthZ, instrumentation, etc.
Another listener is configured for egress requests from the service. This is bound only to the loopback interface (127.0.0.1), and will thus only receive traffic from the local microservice. This listener would be setup with routes and filters to facilitate regular HTTP traffic out to the rest of the mesh.
A third lister (or more, as needed) would handle specific traffic and protocols to dependencies. The example below shows a listener setup to handle TCP traffic to MongoDB listening on the default MongoDB port.
{"zone_key": "default-zone","listener_key": "catalog-listener","domain_keys": ["catalog"],"name": "catalog","ip": "0.0.0.0","port": 9080,"protocol": "http_auto","tracing_config": null,"use_remote_address": false,"access_loggers": null,"http2_protocol_options": {}}
To configure the service to require SPIFFE/SPIRE on its ingress, you must set a secret
on the listener. NOTE if you intend to use SPIFFE/SPIRE on a service ingress, do not set an ssl_config
on the corresponding domain object. Any ssl_config
set on the domain will override this secret set on the listener. An example secret object is as follows:
"secret": {"secret_key": "secret-{{.service.serviceName}}-secret","secret_name": "spiffe://{{ .Values.global.spire.trustDomain }}/{{.service.serviceName}}/mTLS","secret_validation_name": "spiffe://{{ .Values.global.spire.trustDomain }}","ecdh_curves": ["X25519:P-256:P-521:P-384"]}
This object will configure Envoy to use Secret Discovery Service to fetch SPIFFE certificates from the configured path specified as an environment variable SPIRE_PATH
in gm-proxy
. For information on how Envoy's SDS works, see the docs. The secret_key
specifies the name of the secret to fetch. secret_name
should be the SPIFFE Id of your certificate. secret_validation_name
will set the validation context for the sds secret config.
A unique key to identify this listener configuration in the Fabric API. This key is used in proxy objects to attach physical listeners to Sidecars.
The zone in which this object will live. It will only be able to be referenced by objects or sent to Sidecars that live in the same zone.
A unique name for this listener on the Sidecar. This does not need to be globally unique across the Fabric mesh, but needs to be unique for each Sidecar.
Array of network filters that should be active on this listener's filter chain. This list acts as a simple mechanism for turning specific filters on/off without needing to completely remove their configuration from the network_filter section.
NOTE: The order of filters in this array dictates the evaluation order of the filters in the chain.
Array of filter configurations to be used when a filter is enabled.
Array of http filters that should be active on this listener's filter chain. This list acts as a simple mechanism for turning specific filters on/off without needing to completely remove their configuration from the http_filter section.
NOTE: The order of filters in this array dictates the evaluation order of the filters in the chain.
Array of filter configurations to be used when a filter is enabled.
Boolean value which should only be set for front-facing edge nodes in order to allow for x-forwarding through a proxy. This field is false by default, allowing the connection manager to operate in a transparent mode which does not modify the XFF list.
Network interface this listener will bind to. For example, "0.0.0.0"
to listen for requests from anywhere on the network, or "127.0.0.1:
to listen only for local requests.
Integer port this listener will bind to. Must be available on the host or the listener provisioning will fail.
DEPRECATION: This field has been deprecated and will be removed in the next major version release.
This field has no effect.
Array of domain keys that will be linked to this listener.
Configuration to set up distributed tracing on this listener.
Configuration to set up SSL certificates through Envoy's Secret discovery service.
An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.
Configuration object for configuring the Listener's HTTP Connection Manager access loggers and the envoy.router upstream loggers.
By default, one HTTP gRPC access logger (connected to the xds_cluster) and one File Logger (logging to /dev/stdout
) is configured in the HTTP Connection Manager. Configuring a gRPC logger overwrites the default gRPC logger, but not the default File Logger (and vice-versa). The envoy.router contains only one HTTP gRPC logger (also connected to the xds_cluster), and the same overwriting rules apply.
Configuration object
"access_loggers": {"http_connection_loggers": {"disabled": false,"file_loggers": [{"path": "","format": "","json_format": {},"typed_json_format": {}}],"http_grpc_access_loggers": [{"common_config": {"log_name": "","grpc_service": {"cluster_name": ""}}}]},"http_upstream_loggers": {"disabled": false,"file_loggers": [{"path": "","format": "","json_format": {},"typed_json_format": {}}],"http_grpc_access_loggers": [{"common_config": {"log_name": "","grpc_service": {"cluster_name": ""}}}]}}
http_connection_loggers
add loggers to the HTTP Connection Manager, and http_upstream_loggers
add loggers to the envoy.router
. The logger configurations mirror the Envoy Access Logger docs.
Setting disabled
removes all access loggers.
Options for configuring HTTP/2. Setting this field on the listener indicates that the listener will only accept HTTP/2 connections.