ListenerClass docs (#466)

* Updated docstring in code * Added page * regenerate charts and cargo fmt * updated text * updated text
stackabletech · Sep 4, 2023 · 0175793 · 0175793
1 parent fff4a2e
commit 0175793
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 6 deletions.
diff --git a/deploy/helm/druid-operator/crds/crds.yaml b/deploy/helm/druid-operator/crds/crds.yaml
@@ -8225,13 +8225,15 @@ spec:
                     listenerClass:
                       default: cluster-internal
                       description: |-
-                        In the future this setting will control, which ListenerClass <https://docs.stackable.tech/home/stable/listener-operator/listenerclass.html> will be used to expose the service. Currently only a subset of the ListenerClasses are supported by choosing the type of the created Services by looking at the ListenerClass name specified, In a future release support for custom ListenerClasses will be introduced without a breaking change:
+                        This field controls which type of Service the Operator creates for this DruidCluster:
 
                         * cluster-internal: Use a ClusterIP service
 
                         * external-unstable: Use a NodePort service
 
                         * external-stable: Use a LoadBalancer service
+
+                        This is a temporary solution with the goal to keep yaml manifests forward compatible. In the future, this setting will control which ListenerClass <https://docs.stackable.tech/home/stable/listener-operator/listenerclass.html> will be used to expose the service, and ListenerClass names will stay the same, allowing for a non-breaking change.
                       enum:
                         - cluster-internal
                         - external-unstable

diff --git a/docs/modules/druid/pages/usage-guide/listenerclass.adoc b/docs/modules/druid/pages/usage-guide/listenerclass.adoc
@@ -0,0 +1,17 @@
+= Service exposition with ListenerClasses
+
+Apache Druid offers a web UI and an API, both are exposed by the `router` role. Other roles also expose API endpoints such as the `broker` and `coordinator`. The Operator deploys services called `<name>-<role>` (where `<name>` is the name of the DruidCluster and `<role>` is the role for the Service) through which Druid can be reached.
+
+These services can have three different types: `cluster-internal`, `external-unstable` and `external-stable`. Read more about the types in the xref:concepts:service-exposition.adoc[service exposition] documentation at platform level.
+
+This is how the listener class is configured:
+
+[source,yaml]
+----
+spec:
+  clusterConfig:
+    listenerClass: cluster-internal  # <1>
+----
+<1> The default `cluster-internal` setting. 
+
+This setting affects all role Services at once.
diff --git a/docs/modules/druid/partials/nav.adoc b/docs/modules/druid/partials/nav.adoc
@@ -3,6 +3,7 @@
 ** xref:druid:getting_started/first_steps.adoc[]
 * xref:druid:usage-guide/index.adoc[]
 ** xref:druid:usage-guide/pod-placement.adoc[]
+** xref:druid:usage-guide/listenerclass.adoc[]
 ** xref:druid:usage-guide/ingestion.adoc[]
 ** xref:druid:usage-guide/deep-storage.adoc[]
 ** xref:druid:usage-guide/resources-and-storage.adoc[]

diff --git a/rust/crd/src/lib.rs b/rust/crd/src/lib.rs
@@ -242,17 +242,17 @@ pub struct DruidClusterConfig {
     /// These volumes will be mounted into all pods below `/stackable/userdata/{volumename}`
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub extra_volumes: Vec<Volume>,
-    /// In the future this setting will control, which ListenerClass <https://docs.stackable.tech/home/stable/listener-operator/listenerclass.html>
-    /// will be used to expose the service.
-    /// Currently only a subset of the ListenerClasses are supported by choosing the type of the created Services
-    /// by looking at the ListenerClass name specified,
-    /// In a future release support for custom ListenerClasses will be introduced without a breaking change:
+    /// This field controls which type of Service the Operator creates for this DruidCluster:
     ///
     /// * cluster-internal: Use a ClusterIP service
     ///
     /// * external-unstable: Use a NodePort service
     ///
     /// * external-stable: Use a LoadBalancer service
+    ///
+    /// This is a temporary solution with the goal to keep yaml manifests forward compatible.
+    /// In the future, this setting will control which ListenerClass <https://docs.stackable.tech/home/stable/listener-operator/listenerclass.html>
+    /// will be used to expose the service, and ListenerClass names will stay the same, allowing for a non-breaking change.
     #[serde(default)]
     pub listener_class: CurrentlySupportedListenerClasses,
 }