Introduction
The ingress listener sits at the top of the application networking object hierarchy. They approximately represent exposed ports and hold the configurations that get applied to traffic flowing through them. Since many applications utilize multiple ports, GSL allows you to define multiple listeners on a data plane proxy, albeit, with some caveats.
This guide will show you how to add a TCP and HTTP listener to a service’s data plane proxy. We will first add a new listener struct to the ingress template, select and embed the protocol mixin, then finally set the port value.
Prerequisites
- A GSL service file
1. Add the Listener to the Ingress Template
Open a GSL service file and locate the ingress field. It should look similar to:
gsl.#Service & {
...
ingress: (name): {
// primary listener
...
}
}
The ingress field takes a template struct. A template struct, unlike a normal struct, accepts any number of key-value pairs. In this case, each key-value pair defines a new ingress listener with a name set to the key. Other than the primary listener, whose name must match the service name, the name of the listener does not matter.
Add an ingress like so:
ingress: {
(name): {
// primary listener
...
}
"<new listener name>": {
}
}
2. Set the Listener Type
Listeners must declare the protocol they use. Greymatter supports the TCP and HTTP protocols. To set a listener as one or the other, you must embed a protocol mixin. You can only embed one protocol mixin. The only syntactic difference between the two types is the presence of routes. HTTP listeners expose the routes template whereas TCP listeners directly expose an upstream field.
2a. HTTP
Listeners handling traffic over the HTTP protocol must contain the #HTTPListener mixin:
"<listener name>": {
gsl.#HTTPListener
routes: {}
...
}
Routes are an HTTP-only feature and form an intermediary between the listener and the final upstream. Follow this guide to add a route to a listener.
2b. TCP
Listeners handling traffic over the TCP protocol must contain the TCPListener mixin:
"<listener name>": {
gsl.#TCPListener
upstream: {}
...
}
TCP listeners can only proxy a single upstream. As a result, TCP listeners do not have a routes or upstreams template. They only expose an upstream struct. Follow this guide to add an upstream.
3. Set the Port Value
Every listener needs a port to bind to. It is the only required field in a listener struct. To set the port add the aptly named port value:
"<listener name>": {
// gsl.#HTTPListener or gsl.#TCPListener
port: <integer value>
}
Conclusion
This guide showed how to add a listener–a port the data plane proxy listens for connections on–to a GSL service file. Listeners are the start of the application networking object hierarchy, but they cannot achieve much alone. Continue setting up a full connection pipeline by learning how to add a route or an upstream.