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 that 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,
    "use_remote_address": false,
    "access_loggers": null,
    "http2_protocol_options": {}
}
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.
use_remote_address
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.
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.
access_loggers
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.
http2_protocol_options
Options for configuring HTTP/2. Setting this field on the listener indicates that the listener will only accept HTTP/2 connections.