docs: Document the CA certificate retirement

Author: siegfriedweber

docs/modules/secret-operator/pages/secretclass.adoc

@@ -88,17 +88,18 @@ In case an operator sets a higher lifetime, a tracking issue must be created to
 Users can use xref:concepts:overrides.adoc#pod-overrides[podOverrides] to extend the certificate lifetime by adding volume annotations.
 Native support for customizing certificate lifetimes in Stacklet CRDs might be added in the future.
 
+[#ca-rotation]
 ==== Certificate Authority rotation
 
 Certificate authorities also have a limited lifetime, and need to be rotated before they expire to avoid cluster disruption.
 
-// TODO Adapt this section
-If configured to provision its own CA (`autoTls.ca.autoGenerate`), the Secret Operator will create CA certificates that are valid for 365 days (≃ 1 year, configurable via `autoTls.ca.caCertificateLifetime`), and initiate rotation once less than half of that time remains.
+If configured to provision its own CA (`autoTls.ca.autoGenerate`), the Secret Operator will create CA certificates that are valid for 365 days (≃ 1 year, configurable via `autoTls.ca.caCertificateLifetime`).
+The CA certificate is retired one hour before its expiration (configurable via `autoTls.ca.caCertificateRetirementDuration`), to avoid that an almost expired certificate must be deployed, which causes problems in some products, e.g. OpenSearch.
+Once less than half of the active lifetime (= lifetime - retirement duration) remains, the rotation is initiated.
 
 To avoid disruption and let the new CA propagate through the cluster, the Secret Operator will prefer using the oldest CA that will last for the entire lifetime of the issued certificate.
 
-NOTE: Expired CA certificates will currently not be deleted automatically.
-They should be cleaned up manually.
+NOTE: Expired and retired CA certificates will not be deployed.
 
 ==== Reference
 
@@ -113,6 +114,7 @@ spec:
           namespace: default
         autoGenerate: true
         caCertificateLifetime: 700d
+        caCertificateRetirementDuration: 1d
         keyGeneration:
           rsa:
             length: 4096
@@ -132,6 +134,7 @@ spec:
                       and `ca.key` respectively.
 `autoTls.ca.autoGenerate`:: Whether the certificate authority should be provisioned and managed by the Secret Operator.
 `autoTls.ca.caCertificateLifetime` :: The lifetime of the certificate authority's root certificate.
+`autoTls.ca.caCertificateRetirementDuration` :: Duration at the end of the CA certificate lifetime where no signed certificate will exist.
 `autoTls.ca.keyGeneration`:: Configures how keys should be generated.
 `autoTls.ca.keyGeneration.rsa`:: Declares that keys should be generated using the RSA algorithm.
 `autoTls.ca.keyGeneration.rsa.length`:: The amount of bits used for generating the RSA key pair. Currently, `2048`, `3072` and `4096` are supported. Defaults to `2048` bits.

docs/modules/secret-operator/pages/truststore.adoc

@@ -20,5 +20,7 @@ include::example$truststore-tls.yaml[]
 This will create a ConfigMap (or `Secret` based on `targetKind`) named `truststore-pem` containing a `ca.crt` with the trust root certificates.
 It can then either be mounted into a Pod or retrieved and used from outside of Kubernetes.
 
+Expired or retired (see xref:secretclass.adoc#ca-rotation[Certificate Authority rotation]) certificates will not be published, because they should not be needed and some products, e.g. OpenSearch, have problems if they are present at startup.
+
 NOTE: Make sure to have a procedure for updating the retrieved certificates.
       The Secret Operator will automatically rotate the xref:secretclass.adoc#backend-autotls[autoTls] certificate authority as needed, but all trust roots will require some form of update occasionally.