Skip to content

Commit 5e5aa0f

Browse files
xeniapenightkr
andauthored
docs: improve listener documentation (#318)
* Rewrite listener docs to be clearer * s/PVC/volume * Fix some old naming in usage doc * small link and wording fixes * small fix * add newline after each full stop * remove note --------- Co-authored-by: Natalie Klestrup Röijezon <nat@nullable.se>
1 parent ed0ac4b commit 5e5aa0f

File tree

5 files changed

+87
-18
lines changed

5 files changed

+87
-18
lines changed

docs/modules/listener-operator/examples/listenerclass-public-gke.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
apiVersion: listeners.stackable.tech/v1alpha1
33
kind: ListenerClass
44
metadata:
5-
name: public
5+
name: external-stable
66
spec:
77
serviceType: LoadBalancer

docs/modules/listener-operator/examples/listenerclass-public-onprem.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
apiVersion: listeners.stackable.tech/v1alpha1
33
kind: ListenerClass
44
metadata:
5-
name: public
5+
name: external-stable
66
spec:
77
serviceType: NodePort
Lines changed: 81 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,97 @@
11
= Listener
22
:description: The Listener exposes Pods based on ListenerClass rules, provides address info via Ingress_addresses, supports PVC mounting, and enables sticky scheduling.
33

4-
A Listener object exposes a set of Pods according to the rules of a xref:listenerclass.adoc[], but it also adds a couple of other features that are useful for the Stackable data platform at large.
4+
:fn-kubernetes-service: footnote:[It is actually implemented using them, but don't rely on that.]
55

6-
== ListenerClass
6+
A Listener object represents a single exposed (possibly) load-balanced service that clients can connect to.
7+
It can be thought of as the Stackable Data Platform equivalent of a Kubernetes https://kubernetes.io/docs/concepts/services-networking/service/[Service,window=_blank].{fn-kubernetes-service}
78
8-
The exact rules of pod exposure are dictated by the specified xref:listenerclass.adoc[], which allow a single Listener definition to be reused in different clusters, regardless of the Kubernetes distribution or cloud provider.
9+
The mechanism for the service is controlled by the xref:listenerclass.adoc[].
10+
This way, a single Listener definition can be reused in different clusters, expressing the same _intent_ regardless of the Kubernetes distribution or cloud provider's limitations.
911

10-
== Address API
12+
Listeners only direct traffic to Pods that also mount them as a xref:volume.adoc[volume].
13+
The volume allows the operator to xref:#pinning[pin] the Pod to a specific Node, and provides an API for workloads to retrieve their external address.
1114

12-
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.
13-
Contrary to Kubernetes' Service, this is done regardless of the type of service, and transparently also contains information about remapped ports.
15+
[#address-api]
16+
== Address API
1417

15-
== Address volume projection
18+
NOTE: The CRD-based API is intended for external clients that need to retrieve the address.
19+
The workload can retrieve _its own_ address(es) by using the xref:volume.adoc#downwards-api[downwards API].
1620

17-
Listener objects can be mounted into a Pod as a PersistentVolumeClaim (PVC), which contains information about how the Pod should request that external clients refer to it.
21+
A Listener writes back all addresses that it can be reached on to `Listener.status.ingressAddresses`, which can then be used to connect to the service (generate discovery information).
22+
Compared to Kubernetes' Services, this list is provided _regardless_ of the type of the backing Service.
1823

19-
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`.
24+
Ports may be remapped from the Service definition.
25+
Never assume that the exposed port on an address will match your declared port.
26+
Instead, read the port numbers from `.ports.\{portname\}`.
27+
Otherwise, it will break when using NodePort services.
2028

2129
== Per-replica listeners
2230

23-
A Listener PVC can also specify a xref:listenerclass.adoc[] rather than a Listener, in which case a Listener object is created automatically.
24-
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).
31+
A Listener volume can also specify a xref:listenerclass.adoc[] rather than a Listener, in which case a Listener object is created automatically for each volume.
32+
33+
These volumes, in turn, can automatically be created for each replica using either:
34+
35+
- StatefulSet's `volumeClaimTemplates` (for long-lived listeners that will be kept across replica restarts and upgrades), or
36+
- Pod's `volumes[].ephemeral` (for temporary listeners that are deleted when their corresponding Pod is deleted)
37+
38+
[#pinning]
39+
== Pinning
40+
41+
When mounting a Listener volume, it will be "pinned" to that node if the xref:listenerclass.adoc[] uses a strategy that depends on the node that the workload is running on.
42+
43+
Keep in mind that this will only work correctly when using long-lived volumes (such as via StatefulSet's `volumeClaimTemplates`).
44+
Ephemeral volumes will be "reset" for every pod that is created, even if they refer to a long-lived Listener object.
2545

26-
== Sticky scheduling
46+
[#reference]
47+
== Reference
2748

28-
When mounting a Listener PVC, it will be made "sticky" to that node if the xref:listenerclass.adoc[] uses a strategy that depends on the node that the workload is running on.
49+
[source,yaml]
50+
----
51+
apiVersion: listeners.stackable.tech/v1alpha1
52+
kind: Listener
53+
metadata:
54+
name: my-listener
55+
spec:
56+
className: external-unstable
57+
ports:
58+
- name: http
59+
port: 9864
60+
protocol: TCP
61+
extraPodSelectorLabels:
62+
foo: bar
63+
publishNotReadyAddresses: true
64+
status:
65+
ingressAddresses:
66+
- address: 172.18.0.3
67+
addressType: IP
68+
ports:
69+
http: 32222
70+
nodePorts:
71+
http: 32222
72+
serviceName: my-listener
73+
----
2974

30-
Keep in mind that this will only work correctly when using long-lived PVCs (such as via StatefulSet's `volumeClaimTemplates`).
31-
Ephemeral PVCs will be "reset" for every pod that is created, even if they refer to a long-lived Listener object.
75+
`spec.className`:: The name of the xref:listenerclass.adoc[] to use.
76+
`spec.ports`:: The ports exposed from the backing Pods.
77+
`spec.ports.name`:: The name of the port.
78+
`spec.ports.port`:: The number of the port.
79+
This must match the port number exposed by the container.
80+
`spec.ports.protocol`:: The IP protocol (TCP/UDP/SCTP).
81+
Defaults to TCP.
82+
`spec.extraPodSelectorLabels`:: Traffic will only be forwarded to Pods that apply these labels.
83+
This field exists for exceptional cases, where Pods sometimes want to stop receiving traffic based on some dynamic condition.
84+
Normal target selection should use xref:volume.adoc[Listener volumes] instead.
85+
(Volumes are still required when using `extraPodSelectorLabels`.)
86+
`spec.publishNotReadyAddresses`:: If false, traffic will only be directed to Pods that are Ready.
87+
If true, traffic will be directed to any running Pod. Defaults to true.
88+
`status.ingressAddresses`:: A list of all addresses that the Listener can be reached on.
89+
See xref:#address-api[].
90+
`status.ingressAddresses.address`:: The hostname or IP address of this Listener.
91+
`status.ingressAddresses.addressType`:: `IP` if `address` is an IP address, `Hostname` if it is a hostname.
92+
`status.ingressAddresses.ports.\{portName\}`:: The _exposed_ port number for a given port name (as defined in `.spec.ports`).
93+
Note that this may be different than the port specified in `.spec.ports.port``.
94+
`status.nodePorts.\{portName\}`:: For internal use only.
95+
You probably want to use `.status.ingressAddresses` instead.
96+
_If_ the ListenerClass is configured to use xref:listenerclass.adoc#servicetype-nodeport[NodePort] then this is the port number that each port is accessible on on its respective Node.
97+
`status.serviceName`:: The name of the Kubernetes Service object backing this Listener.

docs/modules/listener-operator/pages/usage.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,5 @@ Or like this for on-premise environments:
2525
----
2626
include::example$listenerclass-public-onprem.yaml[]
2727
----
28+
29+
These are normally installed by the appropriate xref:listenerclass.adoc#presets[preset].

docs/modules/listener-operator/pages/volume.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ When this address must be configured statically in clients (such as for HDFS Nam
1515
Mounting listeners into Pods as PersistentVolume allows the Listener Operator to pin these workloads to one node.
1616
Note that this only happens for xref:listenerclass.adoc[]es that actually benefit from pinning.
1717

18-
== Pod metadata injection
18+
[#downwards-api]
19+
== Downwards API
1920

2021
Some services (such as Kafka) need to know their external address, so that they can advertize it to their own replica discovery mechanism.
2122
xref:listener.adoc[] volumes contain a file tree that exposes this information:

0 commit comments

Comments
 (0)