From 05b2beb3e70d2bd629274169e462f71ace3c791b Mon Sep 17 00:00:00 2001
From: Razvan-Daniel Mihai <84674+razvan@users.noreply.github.com>
Date: Wed, 4 Dec 2024 16:26:57 +0100
Subject: [PATCH] doc: describe self signed certificate lifetime configuration

---
 modules/guides/nav.adoc                   |  1 +
 modules/guides/pages/secret-lifetime.adoc | 53 +++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 modules/guides/pages/secret-lifetime.adoc

diff --git a/modules/guides/nav.adoc b/modules/guides/nav.adoc
index 12e65a172..48d8730e4 100644
--- a/modules/guides/nav.adoc
+++ b/modules/guides/nav.adoc
@@ -5,3 +5,4 @@
 ** xref:viewing-and-verifying-sboms.adoc[]
 ** xref:enabling-verification-of-image-signatures.adoc[]
 ** xref:kubernetes-cluster-domain.adoc[]
+** xref:secret-lifetime.adoc[]
diff --git a/modules/guides/pages/secret-lifetime.adoc b/modules/guides/pages/secret-lifetime.adoc
new file mode 100644
index 000000000..913e2fda0
--- /dev/null
+++ b/modules/guides/pages/secret-lifetime.adoc
@@ -0,0 +1,53 @@
+= Self signed certificate lifetime
+:description: Customize the lifetime of self signed certificates.
+
+Self signed certificates generated by the xref:secret-operator:index.adoc[secret operator] usually have a short lifetime of 24 hours.
+In practice this means that Pods have to be restarted daily in order to avoid using expired certificates.
+But in high load production environments, reloading Pods can be a costly operation.
+It can disrupt services and in some cases even lead to data loss.
+To avoid frequent restarts, the lifetime of the self signed certificates can be increased as needed.
+Here is an example for configuring the lifetime of self signed certificates to 7 days in a HDFS stacklet:
+
+[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 self signed certificates for *all* NameNode groups is set to 7 days.
+<2> The lifetime of the self signed certificates for *all* DataNode groups is set to 7 days.
+<3> The lifetime of the self signed certificates for the `default` JournalNode group is set to 7 days.
+
+NOTE: The configuration for the journal nodes is done at group level for demonstration purposes.
+
+Even though operators allow setting this property to a value of your choice, the secret operator will not exceed the `maxCertificateLifetime` value specifed in the referenced secret class.
+
+Similarly to the example above, users can configure the lifetime of self signed certificates for the following product Stacklets:
+* Apache Druid
+* Apache Hadoop
+* Apache HBase
+* Apache Nifi
+* Apache Spark
+* Apache Zookeeper
+* Trino