Merge branch 'refs/heads/main' into feat/add-cra-and-compliance-structure

Author: lfrancke

antora-playbook.yml

@@ -25,6 +25,10 @@ urls:
   redirect_facility: netlify
   # See https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/#html-extension-style-key
   html_extension_style: indexify
+antora:
+  extensions:
+    - require: '@sntke/antora-mermaid-extension'
+      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs
 content:
   sources:
     - url: .
@@ -267,8 +271,6 @@ asciidoc:
     - '@asciidoctor/tabs'
   attributes:
     base-repo: https://github.com/stackabletech
-    plantuml-server-url: http://www.plantuml.com/plantuml
-    kroki-fetch-diagram: true
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
     external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
 # the default caching directory is ./.cache/antora

local-antora-playbook.yml

@@ -10,6 +10,10 @@ urls:
   # This replaces the component version in the URL of the latest stable version with 'stable'
   # i.e. /commons-operator/stable/index.html instead of /commons-operator/0.3/index.html
   latest_version_segment: stable
+antora:
+  extensions:
+    - require: '@sntke/antora-mermaid-extension'
+      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs
 content:
   sources:
     - url: ./
@@ -252,8 +256,6 @@ asciidoc:
     - '@asciidoctor/tabs'
   attributes:
     base-repo: https://github.com/stackabletech
-    plantuml-server-url: http://www.plantuml.com/plantuml
-    kroki-fetch-diagram: true
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
     external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
 # the default caching directory is ./.cache/antora

modules/concepts/pages/observability/telemetry.adoc

@@ -1,4 +1,5 @@
 = Telemetry signals in operators
+:env-filter-syntax: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
 
 [NOTE]
 ====
@@ -46,9 +47,9 @@ telemetry:
     format: null  # <3>
 ----
 
-<1> Boolean: `true, false`
-<2> Enum: `error, warning, info, debug, trace`
-<3> Enum: `plain, json`
+<1> Boolean: `true`, `false`
+<2> String: `error`, `warn`, `info`, `debug`, `trace`, `off` (or {env-filter-syntax}[more complex filters,window=_blank])
+<3> Enum: `plain`, `json`
 
 == File logs
 
@@ -65,9 +66,9 @@ telemetry:
     maxFiles: 6            # <4>
 ----
 
-<1> Boolean: `true, false`
-<2> Enum: `error, warning, info, debug, trace`
-<3> Enum: `never, daily, hourly, minutely`
+<1> Boolean: `true`, `false`
+<2> String: `error`, `warn`, `info`, `debug`, `trace`, `off` (or {env-filter-syntax}[more complex filters,window=_blank])
+<3> Enum: `never`, `daily`, `hourly`, `minutely`
 <4> Unsigned Integer
 
 == OpenTelemetry logs and traces
@@ -88,6 +89,6 @@ telemetry:
     endpoint: null # <3>
 ----
 
-<1> Boolean: `true, false`
-<2> Enum: `error, warning, info, debug, trace`
-<3> String: E.g. `my-collector:4317`
+<1> Boolean: `true`, `false`
+<2> String: `error`, `warn`, `info`, `debug`, `trace`, `off` (or {env-filter-syntax}[more complex filters,window=_blank])
+<3> String: E.g. `https://my-collector:4317` (Note: it must contain the scheme)

modules/concepts/pages/service-discovery.adoc

@@ -7,11 +7,9 @@ Stackable operators provide a _service discovery ConfigMap_ for each product ins
 
 == Motivation
 
-Products on the Stackable platform can, and in some cases must be connected with each other to run correctly. Some products are fundamental to the platform while others depend on them. For example, a NiFi cluster requires a ZooKeeper connection to run in distributed mode. Other products can optionally be connected with each other for better data flow. For example Trino does not store the query data itself, instead it interfaces with other applications to get access to it.
+Products on the Stackable platform can, and in some cases must be connected with each other to run correctly. Some products are fundamental to the platform while others depend on them. For example, an HBase cluster requires a ZooKeeper connection to run in distributed mode. Other products can optionally be connected with each other for better data flow. For example Trino does not store the query data itself, instead it interfaces with other applications to get access to it.
 
-To connect NiFi to ZooKeeper, NiFi needs to know at which host and port it can find the ZooKeeper instance. However the exact address is not known in advance. To enable a connection from NiFi to ZooKeeper purely based on the name of the ZooKeeper cluster, the discovery ConfigMap is used.
-
-With the ConfigMap, the name of the ZooKeeper cluster is enough to know how to connect to it, the ConfigMap has the same name as the cluster and contains all the information needed to connect to the ZooKeeper cluster.
+The ZooKeeper connection details are published by the ZooKeeper operator in a discovery ConfigMap. This ConfigMap has the same name as the ZooKeeper cluster and can be referenced by clients (HBase in our example) when connecting to it.
 
 === Example
 
@@ -39,11 +37,11 @@ data:
   ZOOKEEPER: simple-zk-server-default-0.simple-zk-server-default.default.svc.cluster.local:2181,simple-zk-server-default-1.simple-zk-server-default.default.svc.cluster.local:2181
 ----
 
-The information needed to connect can be a string like above, for example a JDBC connect string: `jdbc:postgresql://localhost:12345`. But a ConfigMap can also contain multiple configuration files which can then be mounted into a client Pod. This is the case for xref:hdfs:discovery.adoc[HDFS], where the `core-site.xml` and `hdfs-site.xml` files are put into the discovery ConfigMap.
+The connection details can be a string like above, for example a JDBC connect string: `jdbc:postgresql://localhost:12345`. But a ConfigMap can also contain multiple configuration files which can then be mounted into a client Pod. This is the case for xref:hdfs:discovery.adoc[HDFS], where the `core-site.xml` and `hdfs-site.xml` files are put into the discovery ConfigMap.
 
 == Usage of the service discovery ConfigMap
 
-The ConfigMap is used by Stackable operators to connect products together, but can also be used by the user to retrieve connection information to connect to product instances. The operators consume only the ConfigMap, so it is also possible to create a ConfigMap by hand for a product instance that is not operated by a Stackable operator. These different usage scenarios are explained below.
+Discovery ConfigMaps are used by Stackable operators to connect products together, but can also be used by the user to retrieve connection information to connect to product instances. The operators consume only the ConfigMap, so it is also possible to create a ConfigMap by hand for a product instance that is not operated by a Stackable operator. These different usage scenarios are explained below.
 
 === Service discovery within Stackable
 

modules/guides/pages/debug-network-traffic.adoc

@@ -3,24 +3,24 @@
 :tcpdump: https://www.tcpdump.org/
 :mitmproxy: https://www.mitmproxy.org/
 
-You likely know this problem: Some tools is behaving weird, and you need to debug (often times HTTP/HTTPS or DNS) traffic between Kubernetes Pods.
-If the tool would be running on a local machine, one would simply start {tcpdump}[`tcpdump`] and inspect the traffic.
-Maybe use {mitmproxy}[`mitmproxy`] as a HTTPS proxy to re-encrypt the HTTPS traffic, so that it is readable.
+You likely know this problem: Some tool is behaving weird, and you need to debug (often times HTTP/HTTPS or DNS) traffic between Kubernetes Pods.
+If the tool would be running on a local machine, one would simply start {tcpdump}[`tcpdump`{external-link-icon}^] and inspect the traffic.
+Maybe use {mitmproxy}[`mitmproxy`{external-link-icon}^] as a HTTPS proxy to re-encrypt the HTTPS traffic, so that `mitmproxy` can inspect the decrypted traffic.
 
 However, as we are running in a containerized environment, things are a bit more complicated.
 This guide explains you how you can capture and inspect traffic anyway.
 
 There are a few things needed:
 
-1. A sidecar running {tcpdump}[`tcpdump`], capturing the traffic into a file.
+1. A sidecar running {tcpdump}[`tcpdump`{external-link-icon}^], capturing the traffic into a file.
 2. If TLS (e.g. HTTPS) traffic is involved, the product needs to be configured in such a way, that it writes the TLS session keys into a file.
    The key log can be used afterwards to decrypt the TLS traffic.
 3. Wireshark to make it easier to inspect the captured traffic.
    You can give it the TLS key log and it will automatically decrypt the TLS traffic.
 
 == Simple usage
 
-If you only care about unencrypted communications, you can use this snippet to dump all traffic using {tcpdump}[`tcpdump`].
+If you only care about unencrypted communications, you can use this snippet to dump all traffic using {tcpdump}[`tcpdump`{external-link-icon}^].
 
 [source,yaml]
 ----
@@ -53,7 +53,7 @@ Let's make things a bit more interesting using a real-world example.
 Let's assume Superset is behaving weird and we want to debug the network traffic from Superset to Trino, which is using HTTPS.
 
 As of Java 21 the JVM does not respect the `SSLKEYLOGFILE` env var and does not seem to have support to write the TLS key log.
-So we need to use a third-party Java agent called https://github.com/neykov/extract-tls-secrets[extract-tls-secrets] for that.
+So we need to use a third-party Java agent called https://github.com/neykov/extract-tls-secrets[extract-tls-secrets{external-link-icon}^] for that.
 
 [source,yaml]
 ----
@@ -149,6 +149,6 @@ image::debug-network-traffic/4.png[]
 
 == Follow-up tips
 
-1. You can filter the packets in the {tcpdump}[`tcpdump`] call to reduce the capture file size.
+1. You can filter the packets in the {tcpdump}[`tcpdump`{external-link-icon}^] call to reduce the capture file size.
 2. If you do this on a production setup, keep in mind that the dump might contain sensitive data and the TLS keys can be used to decrypt all TLS traffic of this Pod!
 3. In case the product uses HTTP 2 (or newer), you need to use a Wireshark filter such as `http2.headers.path == "/nifi-api/flow/current-user"`

only-dev-antora-playbook.yml

@@ -10,6 +10,10 @@ urls:
   # This replaces the component version in the URL of the latest stable version with 'stable'
   # i.e. /commons-operator/stable/index.html instead of /commons-operator/0.3/index.html
   latest_version_segment: stable
+antora:
+  extensions:
+    - require: '@sntke/antora-mermaid-extension'
+      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs
 content:
   sources:
     - url: ./
@@ -99,8 +103,6 @@ asciidoc:
     - '@asciidoctor/tabs'
   attributes:
     base-repo: https://github.com/stackabletech
-    plantuml-server-url: http://www.plantuml.com/plantuml
-    kroki-fetch-diagram: true
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
     external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
 # the default caching directory is ./.cache/antora

package-lock.json

@@ -6,7 +6,8 @@
   },
   "dependencies": {
     "@antora/lunr-extension": "^1.0.0-alpha.8",
-    "@asciidoctor/tabs": "^1.0.0-beta.6"
+    "@asciidoctor/tabs": "^1.0.0-beta.6",
+    "@sntke/antora-mermaid-extension": "0.0.8"
   },
   "workspaces": [
     "ui"

package.json

@@ -10,6 +10,10 @@ urls:
   # This replaces the component version in the URL of the latest stable version with 'stable'
   # i.e. /commons-operator/stable/index.html instead of /commons-operator/0.3/index.html
   latest_version_segment: stable
+antora:
+  extensions:
+    - require: '@sntke/antora-mermaid-extension'
+      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs
 content:
   sources:
     - url: ./
@@ -64,8 +68,6 @@ asciidoc:
     - '@asciidoctor/tabs'
   attributes:
     base-repo: https://github.com/stackabletech
-    plantuml-server-url: http://www.plantuml.com/plantuml
-    kroki-fetch-diagram: true
     # an external icon. Create a link opening in a new tab like this: http://my-url.com[Text {external-link-icon}^]
     external-link-icon: "<i class=\"fa-solid fa-arrow-up-right-from-square fa-xs\" style=\"margin-left: 3px; vertical-align: baseline;\"></i>"
 # the default caching directory is ./.cache/antora