Add concepts page on temporary credentials lifetime (#689)

* Add concepts page on temporary credentials lifetime

Co-authored-by: Razvan-Daniel Mihai <[email protected]>

* Apply suggestions from code review

Co-authored-by: Razvan-Daniel Mihai <[email protected]>

* typo

* Better explain checking the lifetime

* fix rendering

* Rename section to Pod lifetime annotations

---------

Co-authored-by: Razvan-Daniel Mihai <[email protected]>
Co-authored-by: Razvan-Daniel Mihai <[email protected]>

Author: sbernauer

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.