Merge branch 'main' into feat/rel-notes-secret-lifetime

Author: razvan

.github/PULL_REQUEST_TEMPLATE/release-notes.md

@@ -0,0 +1,42 @@
+<!--
+    DO NOT REMOVE THIS COMMENT. It is intended for people who might copy/paste from the previous release issue.
+    This was created by an PR template: https://github.com/stackabletech/documentation/tree/main/.github/PULL_REQUEST_TEMPLATE/release-notes.md.
+-->
+
+<!-- Release placeholders YY.M.X should be replaced. -->
+# Release Notes for SDP YY.M.X
+
+> [!CAUTION]
+> Please assign the applicable `scheduled-for/YY.M.X` label.
+
+> [!TIP]
+> - Use the commented out template headings in [release-notes][template].
+> - Begin each sentence on a new line. This helps with review suggestions and diffing.
+> - Use xrefs for links to other parts of the documentation so that they remain valid across versions.
+
+[template]: https://github.com/stackabletech/documentation/blob/8dc93f28ac6d20a587f54d0a697c71fe47e8643a/modules/ROOT/pages/release-notes.adoc?plain=1#L11-L56
+
+```[tasklist]
+#### Release note compilation tasks
+- [ ] Check [Issues](https://github.com/search?q=org%3Astackabletech+label%3Arelease-note%2Crelease-note%2Faction-required+label%3Arelease%YY.M.X%2Cscheduled-for%YY.M.X&type=issues) for Product and Platform release notes
+- [ ] Check [PRs](https://github.com/search?q=org%3Astackabletech+label%3Arelease-note%2Crelease-note%2Faction-required+label%3Arelease%YY.M.X%2Cscheduled-for%YY.M.X&type=pullrequests) for Product and Platform release notes
+- [ ] Optionally check the [Changelogs](https://github.com/search?q=org%3Astackabletech+path%3A*CHANGELOG.md+%22YY.M.X%22&type=code) in case release notes were missed
+- [ ] Compile list of new product versions that are supported and compile a list of new product features to include in the Release Highlights
+- [ ] Upgrade guide: Document how to use stackablectl to uninstall all and install new release
+- [ ] Upgrade guide: Document how to use helm to uninstall all and install new release
+- [ ] Upgrade guide: Every breaking change of all our operators
+- [ ] Upgrade guide: List removed product versions (if there are any)
+- [ ] Upgrade guide: List removed operators (if there are any)
+- [ ] Upgrade guide: List supported Kubernetes versions
+```
+
+Each of the following tasks focuses on a specific goal and should be done once the items above have been completed.
+
+```[tasklist]
+#### Release note review tasks
+- [ ] Check overall document structure
+- [ ] Check spelling, grammar, and correct wording
+- [ ] Check that internal links are xrefs
+- [ ] Check that rendered links are valid
+- [ ] Check that each sentence begins on a new line
+```

.github/workflows/build.yml

@@ -2,6 +2,10 @@ name: Build site
 
 on:
   pull_request:
+    paths-ignore:
+      - .github/PULL_REQUEST_TEMPLATES/**
+      - .github/ISSUE_TEMPLATES/**
+      - scripts/**
 
 jobs:
 

.markdownlint.yaml

@@ -18,3 +18,9 @@ MD013:
 MD024:
   # Only check sibling headings
   siblings_only: true
+
+# MD032/blanks-around-lists
+MD032: false
+
+# MD028/no-blanks-blockquote
+MD028: false

modules/ROOT/pages/quickstart.adoc

@@ -1,5 +1,5 @@
 = Quickstart
-:latest-release: https://github.com/stackabletech/stackable-cockpit/releases/tag/stackablectl-1.0.0-rc2
+:latest-release: https://github.com/stackabletech/stackable-cockpit/releases/tag/stackablectl-24.11.1
 :cockpit-releases: https://github.com/stackabletech/stackable-cockpit/releases
 :description: Quickstart guide for Stackable: Install stackablectl, set up a demo, and connect to services like Superset and Trino with easy commands and links.
 
@@ -17,9 +17,9 @@ rename the file to `stackablectl`. You can also use the following command:
 
 [source,console]
 ----
-wget -O stackablectl https://github.com/stackabletech/stackable-cockpit/releases/download/stackablectl-1.0.0-rc2/stackablectl-x86_64-unknown-linux-gnu
+wget -O stackablectl https://github.com/stackabletech/stackable-cockpit/releases/download/stackablectl-24.11.1/stackablectl-x86_64-unknown-linux-gnu
 # or
-curl -L -o stackablectl https://github.com/stackabletech/stackable-cockpit/releases/download/stackablectl-1.0.0-rc2/stackablectl-x86_64-unknown-linux-gnu
+curl -L -o stackablectl https://github.com/stackabletech/stackable-cockpit/releases/download/stackablectl-24.11.1/stackablectl-x86_64-unknown-linux-gnu
 ----
 
 Mark the binary as executable:

modules/concepts/nav.adoc

@@ -20,6 +20,7 @@
 *** xref:operations/pod_disruptions.adoc[]
 *** xref:operations/pod_placement.adoc[]
 *** xref:operations/graceful_shutdown.adoc[]
+*** xref:operations/temporary_credentials_lifetime.adoc[]
 ** Observability
 *** xref:labels.adoc[]
 *** xref:logging.adoc[]

modules/concepts/pages/index.adoc

@@ -30,7 +30,7 @@ It also includes xref:tls-server-verification.adoc[].
 == Operations
 
 The xref:operations/index.adoc[operations] section is directed at platform maintainers.
-It covers xref:operations/cluster_operations.adoc[starting, stopping and restarts] of products, xref:operations/graceful_shutdown.adoc[] and other topics related to maintenance and ensuring stability of the platform operation.
+It covers xref:operations/cluster_operations.adoc[starting, stopping and restarts] of products, xref:operations/graceful_shutdown.adoc[] and other topics related to maintenance and ensuring stability and availability of the platform operation.
 
 == Observability
 

modules/concepts/pages/operations/cluster_operations.adoc

@@ -123,4 +123,4 @@ You can add more labels to make finer grained restarts.
 == Automatic restarts
 
 The Commons Operator of the Stackable Platform may restart Pods automatically, for purposes such as ensuring that TLS certificates are up-to-date.
-For details, see the xref:commons-operator:index.adoc[Commons Operator documentation].
+For details, see xref:operations/temporary_credentials_lifetime.adoc[] as well as the xref:commons-operator:index.adoc[Commons Operator documentation].

modules/concepts/pages/operations/index.adoc

@@ -11,21 +11,23 @@ Make sure to go through the following checklist to achieve the maximum level of
 1. Make setup highly available (HA): In case the product supports running in an HA fashion, our operators will automatically configure it for you.
    You only need to make sure that you deploy a sufficient number of replicas.
    Please note that some products don't support HA.
-2. Reduce the number of simultaneous pod disruptions (unavailable replicas).
+2. Reduce the number of simultaneous pod disruptions (unavailable replicas):
    The Stackable operators write defaults based upon knowledge about the fault tolerance of the product, which should cover most of the use-cases.
    For details have a look at xref:operations/pod_disruptions.adoc[].
 3. Reduce impact of pod disruptions:
    Many HA capable products offer a way to gracefully shut down the service running within the Pod.
    The flow is as follows: Kubernetes wants to shut down the Pod and calls a hook into the Pod, which in turn interacts with the product, signaling it to gracefully shut down.
    The final deletion of the Pod is then blocked until the product has successfully migrated running workloads away from the Pod that is to be shut down.
    Details covering the graceful shutdown mechanism are described in xref:operations/graceful_shutdown.adoc[] as well as the actual operator documentation.
-+
-WARNING: Graceful shutdown is not implemented for all products yet. Please check the documentation specific to the product operator to see if it is supported (such as e.g. xref:trino:usage-guide/operations/graceful-shutdown.adoc[the documentation for Trino].
-
 4. Spread workload across multiple Kubernetes nodes, racks, datacenter rooms or datacenters to guarantee availability
    in the case of e.g. power outages or fire in parts of the datacenter. All of this is supported by
    configuring an https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/[antiAffinity] as documented in
    xref:operations/pod_placement.adoc[]
+5. Reduce the frequency of disruptions:
+   Although we try our best to reduce the impact of disruptions, some tools simply don't support HA setups.
+   One example is the Trino coordinator - if you restart it, all running queries will fail.
+   Many products use temporary credentials (such as TLS certificates), which have a short lifetime by default for maximum security.
+   The xref:operations/temporary_credentials_lifetime.adoc[] page describes how you can increase the lifetime of this temporary credentials too avoid frequent restarts.
 
 == Maintenance actions
 

modules/concepts/pages/operations/temporary_credentials_lifetime.adoc

@@ -0,0 +1,92 @@
+= Temporary credentials lifetime
+:description: Customize the lifetime of temporary credentials.
+
+== Usages
+
+=== TLS certificates
+
+Currently the only temporary credentials are TLS certificates.
+
+Many products use TLS to secure the communications, often times customers use the xref:secret-operator:secretclass.adoc#backend-autotls[secret-operator autoTls] backend to create TLS certificates for the Pods on the fly.
+To increase security, these temporary credentials have a short lifetime by default, which will result in e.g. Trino coordinator Pods restarting every ~24 hours (minus some safety buffer) to avoid using expired certificates.
+
+== Configure the lifetime
+
+In high load production environments, restarting Pods can be a costly operation, as it can disrupt services and in some cases even lead to data loss.
+To avoid frequent restarts, the lifetime of all temporary credentials (such as the TLS certificates) can be increased as needed.
+
+Here is an example for configuring the temporary credentials lifetime to 7 days in a HDFS stacklet.
+It should result in the HDFS Pods restarting weekly instead of daily:
+
+[source,yaml]
+----
+---
+apiVersion: hdfs.stackable.tech/v1alpha1
+kind: HdfsCluster
+metadata:
+  name: hdfs
+spec:
+  nameNodes:
+    config:
+      requestedSecretLifetime: 7d # <1>
+    roleGroups:
+      default:
+        replicas: 2
+  dataNodes:
+    config:
+      requestedSecretLifetime: 7d # <2>
+    roleGroups:
+      default:
+        replicas: 2
+  journalNodes:
+    roleGroups:
+      default:
+        replicas: 3
+        config:
+          requestedSecretLifetime: 7d # <3>
+----
+<1> The lifetime of the TLS certificates for *all* NameNode roleGroups is set to 7 days.
+<2> The lifetime of the TLS certificates for *all* DataNode roleGroups is set to 7 days.
+<3> The lifetime of the TLS certificates for the `default` JournalNode group is set to 7 days.
+
+NOTE: The configuration for the JournalNodes is done at roleGroup level for demonstration purposes.
+
+=== TLS certificate lifetimes
+
+Even though operators allow setting this property to a value of your choice, the xref:secret-operator:index.adoc[secret-operator] will not exceed the `maxCertificateLifetime` value specified in SecretClass creating the TLS certificates (see xref:secret-operator/secretclass.adoc#certificate_lifetime).
+
+=== Operator support
+
+Similar to the example above, users can configure the lifetime of temporary credentials for the following operators:
+
+* Apache Druid
+* Apache Hadoop
+* Apache HBase
+* Apache NiFi
+* Apache Spark
+* Apache Zookeeper
+* Trino
+
+== Pod lifetime annotations
+
+After configuring the lifetime as described above you could simply observe your stacklet for a week/month (or whatever your new lifetime is), to see if your changes take effect.
+However, it's much quicker to check at what point of time your Pods will be restarted next.
+
+Pods are not restarted "randomly" by Stackable operators, but in a predicable manner.
+When a temporary credential is added to a Pod, an annotation is added as well.
+It starts with `restarter.stackable.tech/expires-at.` and instructs the xref:commons-operator:restarter.adoc[restart-controller] to restart the Pod once the specified point in time is reached.
+
+Given the following Pod
+
+[source,yaml]
+----
+kind: Pod
+metadata:
+  annotations:
+    restarter.stackable.tech/expires-at.b887492af14bfe84f10cb2ff1b60acb0: "2024-12-05T14:03:47.131570189+00:00"
+    restarter.stackable.tech/expires-at.ea77192c1184326d33e8ee32cfe921ea: "2024-12-05T15:49:10.043722965+00:00"
+----
+
+You can always determine the instant the Pod will be restarted by the xref:commons-operator:restarter.adoc[restart-controller] by taking the earliest timestamp, `2024-12-05T14:03:47.131570189+00:00` in this case.
+
+You can use this timestamp to check if your changes have been applied as intended.

modules/contributor/pages/adr/ADR029-database-connection.adoc

@@ -15,6 +15,8 @@ v0.1, 2022-12-08
 
 Technical Story: https://github.com/stackabletech/issues/issues/238
 
+NOTE: We might want to incorporate changes to address https://github.com/stackabletech/issues/issues/681, maybe as V2?
+
 == Context and Problem Statement
 
 Many products supported by the Stackable Data Platform require databases to store metadata. Currently there is no uniform, consistent way to define database connections. In addition, some Stackable operators define database credentials to be provided inline and in plain text in the cluster definitions.