Listener overview

A listener is a process on the gateway that checks for incoming connection requests for a specific domain, IP address, port, and protocol. When a request is received on a listener, the gateway verifies the request, and then looks up the routing rules in the route table to decide how to forward the request to the destination in the cluster.

Listener setup

Listeners are configured on the virtual gateway custom resource. Depending on the virtual gateway deployment pattern that you decided on, you might have one or multiple virtual gateways for a host that you serve traffic for. If you want to centrally manage all connections for a host, add all listeners that you want to allow for your host to the same virtual gateway resource. For more granular control, create multiple virtual gateway resources, each with one listener configuration.

Type of listener

To decide what type of gateway listener is right for you depends on several factors, such as the protocol that your client and your destination support, the security and encryption requirements that you have, and the gateway's capabilities. Use the following decision tree to find the listener for your use case. To learn more about the configuration options that are illustrated in the decision tree, see Listener configuration options

Decision tree to find the right listener for your setup

Listener configuration options

Review the options that you can decide on when configuring your listener.

Host

When you set up your listener in the virtual gateway, you can decide to apply that listener to all the hosts that your gateway serves, or to limit the listener configuration to a particular host. The setup that is right for you depends on the virtual gateway deployment pattern that you decided on and the level of control that you want to have. For example, if you decide to have one virtual gateway for all hosts, you include all the listeners for each host in the same virtual gateway. To have more granular control, you can create a separate virtual gateway for each host, or a separate gateway for each host and listener combination.

Protocol and port

The protocol and port that you set up for your listener depends on the protocol that is supported by your clients and the security requirements that you have. For example, to connect a layer 7 HTTP client, you can choose between the HTTP and HTTPS protocol. However for TCP clients, you might choose to set up a TCP or TLS listener.

Depending on the protocol that you choose, you must set up the corresponding port that is available on the ingress gateway. To view available protocols and ports, you can run the following command.

kubectl get service istio-ingressgateway -n gloo-mesh-gateways -o yaml

TLS settings

The TLS settings on the gateway determine how to handle incoming encrypted traffic. Review the settings that are available to you.

Secure traffic from the client to the gateway

Setting Description
Simple TLS You can protect the connection from the client to the gateway by using simple TLS. With simple TLS, only the gateway is set up with an SSL certificate that the client can use to validate the server's identity. Only after the identity is successfully validated, a connection from the client to the gateway is established.
Mutual TLS (mTLS) Mutual TLS is similar to simple TLS, but requires both the client and the server to be set up with a TLS certificate. During the TLS handshake, the client and the server verify each other's identity by using the TLS certificates. Only after successful verification and validation on both sides, the connection between the client and the gateway is established.

Secure traffic from the gateway to the destination

Setting Description
TLS termination You can offload the work of encryption and decryption from your destination app so that your app can focus on its business logic. To do that, you must set up your gateway for simple or mutual TLS. The gateway uses the TLS certificate to terminate incoming TLS connections and decrypt requests. The unencrypted request is then forwarded to the destination workload. Similarly, responses from a destination are sent as unencrypted responses to the gateway, where they are encrypted with the SSL server certificate before the response is forwarded to the client.
Passthrough Instead of terminating incoming TLS connections at the gateway, you can decide to pass the encrypted traffic through to the destination. Note that the destination app must be set up with an SSL certificate to be capable of decrypting and encrypting traffic.
TLS origination TLS origination is the opposite of TLS termination. When TLS origination is enabled, the ingress gateway encrypts incoming HTTP requests, or terminates and re-encrypts incoming HTTPS traffic by using TLS certificates before forwarding the request to an HTTPS server or service in the cluster. Note that because encrypted traffic is forwarded to the destination workload, the destination must be set up with an SSL certificate to be capable of decrypting incoming requests.