docs: document CA-only SecretClass for TLS server verification

Author: lfrancke

docs/modules/secret-operator/examples/secretclass-byo-ca.yaml

@@ -0,0 +1,13 @@
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: ldap-tls-ca
+spec:
+  backend:
+    autoTls:
+      ca:
+        secret:
+          name: ldap-tls-ca # <1>
+          namespace: default
+        autoGenerate: false # <2>

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

@@ -40,6 +40,31 @@ CAUTION: Attributes of the certificate (such as the expiration date, fingerprint
 
 xref:scope.adoc[Scopes] are used to populate the claims (such as `subjectAlternateName`) of the provisioned certificates.
 
+[#backend-autotls-byo-ca]
+==== Providing your own certificate authority
+
+Instead of letting the Secret Operator generate a certificate authority, you can provide your own.
+A common reason to do this is verifying the TLS certificate of an external service such as an LDAP or S3 server: you create a SecretClass that holds that service's CA certificate and reference it from the product CRD (see xref:concepts:tls-server-verification.adoc[]).
+
+Store the CA certificate (in PEM format) in a Secret under the key `ca.crt`:
+
+[source,bash]
+----
+kubectl create secret generic ldap-tls-ca --from-file=ca.crt=/path/to/ca.crt
+----
+
+Then reference that Secret from a SecretClass and set `autoGenerate: false`:
+
+[source,yaml]
+----
+include::example$secretclass-byo-ca.yaml[]
+----
+<1> The Secret created above. It must contain the CA certificate under the key `ca.crt`.
+<2> Disable CA generation so that the provided CA is used as-is instead of generating a new one.
+
+When the SecretClass is only used to *verify* servers and does not issue any certificates, the Secret needs nothing but `ca.crt`, the `ca.key` entry can be omitted.
+If you also want the Secret Operator to issue certificates signed by this CA, the Secret must additionally contain the private key under `ca.key`.
+
 [#backend-tls-certificate-key-pair-generation]
 ==== `TLS certificate key pair generation`
 
@@ -132,6 +157,7 @@ spec:
 `autoTls.ca`:: Configures the certificate authority used to issue `Pod` certificates.
 `autoTls.ca.secret`:: Reference (`name` and `namespace`) to a K8s `Secret` object where the CA certificate and key is stored in the keys `ca.crt`
                       and `ca.key` respectively.
+                      When the SecretClass is only used to verify servers (see xref:#backend-autotls-byo-ca[]), only `ca.crt` is required and `ca.key` may be omitted.
 `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.