A Listener object exposes a set of Pods according to the rules of a ListenerClass, but it also adds a couple of other features that are useful for the Stackable platform at large.


The exact rules of pod exposure are dictated by the specified ListenerClass, which allow a single Listener definition to be reused in different clusters, regardless of the Kubernetes distribution or cloud provider.

Address API

A Listener writes back all addresses that it can be reached on to Listener.status.ingress_addresses, which can then be used to generate discovery information. Contrary to Kubernetes' Service, this is done regardless of the type of service, and transparently also contains information about remapped ports.

Address volume projection

Listener objects can be mounted into a Pod as a PersistentVolumeClaim, which contains information about how the Pod should request that external clients refer to it.

For example, if the volume is mounted to /stackable/listener, the primary address can be read from /stackable/listener/default-address/address, and the public http port number can be read from /stackable/listener/default-address/ports/http.

Per-replica listeners

A Listener PVC can also specify a ListenerClass rather than a Listener, in which case a Listener object is created automatically. These PVCs can automatically be created for each replica using either StatefulSet's volumeClaimTemplates (for long-lived listeners that will be kept across replica restarts and upgrades) or Pod's volumes[].ephemeral (for temporary listeners that are deleted when their corresponding Pod is deleted).

Sticky scheduling

When mounting a Listener PVC, it will be made "sticky" to that node if the ListenerClass uses a strategy that depends on the node that the workload is running on.

Keep in mind that this will only work correctly when using long-lived PVCs (such as via StatefulSet's volumeClaimTemplates). Ephemeral PVCs will be "reset" for every pod that is created, even if they refer to a long-lived Listener object.