From 90c4a938b1deddf30a2f8a10d02b329912a4f4be Mon Sep 17 00:00:00 2001 From: Sebastian Bernauer Date: Fri, 31 Oct 2025 08:32:47 +0100 Subject: [PATCH 1/3] docs: Mention ListenerClass presets in installation guide --- .../listener-operator/pages/installation.adoc | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/modules/listener-operator/pages/installation.adoc b/docs/modules/listener-operator/pages/installation.adoc index 773306d7..b5879a0d 100644 --- a/docs/modules/listener-operator/pages/installation.adoc +++ b/docs/modules/listener-operator/pages/installation.adoc @@ -18,8 +18,46 @@ Resource sizing depends on cluster type(s), usage and scope, but as a starting p * 0.2 cores (e.g. i5 or similar) * 256MB RAM +== ListenerClass presets + +When installing the listener-operator you need choose a ListenerClass preset (or use the default one). +A ListenerClass controls two important things: + +* Service type: If ClusterIP, NodePort or LoadBalancer is used +* Pinning: When using NodePorts (and only then) if pinning is enabled, the Pods are pinned to a particular Kubernetes node, so that the Pods always starts on the same node and has a stable endpoint without the need for an (e.g. expensive) LoadBalancer. + However, this pinning causes problems when you rotate your nodes (e.g. on a regular basis), as Pod will be stuck in `Pending` when the node they are pinned to is gone. + +Use the following decision tree to decide on the ListenerClass preset to use: + +[plantuml, svg] +.... +@startuml +if (LoadBalancers supported?) is (yes) then + #palegreen:Use ephermal-nodes; + kill +else (no) + if (Nodes regularly rotated?) is (yes) then + #yellow:Use stable-nodes to prefer NodePort + over LoadBalancers. However, don't use + the external-stable ListenerClass at all, + use external-unstable instead; + kill + else (no) + #palegreen:Use stable-nodes; + kill +endif +@enduml +.... + +== stackablectl + +The recommended way to install the operator is using `stackablectl`. +Starting with 1.2.0 it automatically detects `kind` and `k3s` cluster and uses `stable-nodes` + == Helm -Helm allows you to download and deploy Stackable operators on Kubernetes and is by far the easiest installation method. + +As `stackablectl` internally invokes Helm, you can absolutely install the operator only using Helm. +Helm allows you to download and deploy Stackable operators on Kubernetes. NOTE: `helm repo` subcommands are not supported for OCI registries. The operators are installed directly, without adding the Helm Chart repository first. From 928c8ce57f93e7adf68bb81fcbb4eff4a8b554d0 Mon Sep 17 00:00:00 2001 From: Sebastian Bernauer Date: Mon, 3 Nov 2025 11:46:00 +0100 Subject: [PATCH 2/3] Switch to mermaid --- .../listener-operator/pages/installation.adoc | 25 ++++++------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/docs/modules/listener-operator/pages/installation.adoc b/docs/modules/listener-operator/pages/installation.adoc index b5879a0d..fa997ac1 100644 --- a/docs/modules/listener-operator/pages/installation.adoc +++ b/docs/modules/listener-operator/pages/installation.adoc @@ -29,24 +29,15 @@ A ListenerClass controls two important things: Use the following decision tree to decide on the ListenerClass preset to use: -[plantuml, svg] +[mermaid, width=100%] .... -@startuml -if (LoadBalancers supported?) is (yes) then - #palegreen:Use ephermal-nodes; - kill -else (no) - if (Nodes regularly rotated?) is (yes) then - #yellow:Use stable-nodes to prefer NodePort - over LoadBalancers. However, don't use - the external-stable ListenerClass at all, - use external-unstable instead; - kill - else (no) - #palegreen:Use stable-nodes; - kill -endif -@enduml +flowchart LR + LB{LoadBalancer supported?} + LB -->|yes| ephermal-nodes[Use ephermal-nodes] + LB -->|no| node-rotation{Nodes regularly rotated?} + + node-rotation -->|yes| complicated[Use stable-nodes to prefer NodePort
over LoadBalancers.
However, don't use the
external-stable ListenerClass at all,
use external-unstable instead] + node-rotation -->|no| stable-nodes[Use stable-nodes] .... == stackablectl From 2d67070a77abe5307bd5a2a855c4496dd043bf12 Mon Sep 17 00:00:00 2001 From: Sebastian Bernauer Date: Mon, 3 Nov 2025 13:21:41 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Malte Sander --- docs/modules/listener-operator/pages/installation.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/modules/listener-operator/pages/installation.adoc b/docs/modules/listener-operator/pages/installation.adoc index fa997ac1..6584325a 100644 --- a/docs/modules/listener-operator/pages/installation.adoc +++ b/docs/modules/listener-operator/pages/installation.adoc @@ -20,12 +20,12 @@ Resource sizing depends on cluster type(s), usage and scope, but as a starting p == ListenerClass presets -When installing the listener-operator you need choose a ListenerClass preset (or use the default one). -A ListenerClass controls two important things: +When installing the listener-operator you need to choose a ListenerClass preset (or use the default one). +A ListenerClass controls two important aspects: -* Service type: If ClusterIP, NodePort or LoadBalancer is used -* Pinning: When using NodePorts (and only then) if pinning is enabled, the Pods are pinned to a particular Kubernetes node, so that the Pods always starts on the same node and has a stable endpoint without the need for an (e.g. expensive) LoadBalancer. - However, this pinning causes problems when you rotate your nodes (e.g. on a regular basis), as Pod will be stuck in `Pending` when the node they are pinned to is gone. +* Service type: Determines whether ClusterIP, NodePort or LoadBalancer is used +* Pinning: When using NodePorts (and only then) if pinning is enabled, the Pods are bound to a specific Kubernetes node. This allows the Pods to always start on the same node and keep a stable endpoint without the need for an (e.g. expensive) LoadBalancer. + However, this pinning can cause problems during node rotation (e.g. on a regular basis), as Pod will be stuck in `Pending` when the node they are pinned to is gone. Use the following decision tree to decide on the ListenerClass preset to use: