listener

Summary

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 at least one listener 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.

Usage

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.

Example Object

{
    "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
}

Secret Configuration for SPIFFE/SPIRE

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.

Envoy Reference

• Envoy Listener Reference

Fields

listener_key

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.

zone_key

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.

name

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.

active_network_filters

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.

network_filters

Array of filter configurations to be used when a filter is enabled.

active_http_filters

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.

http_filters

Array of filter configurations to be used when a filter is enabled.

ip

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.

port

Integer port this listener will bind to. Must be available on the host or the listener provisioning will fail.

protocol

DEPRECATION: This field has been deprecated and will be removed in the next major version release.

This field has no effect.

domain_keys

Array of domain keys that will be linked to this listener.

tracing_config

Configuration to set up distributed tracing on this listener.

secret

Configuration to set up SSL certificates through Envoy's Secret discovery service.

checksum

An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.