Clarify documentation with an actual example for Server verification (#860)

* Clarify documentation with an actual example for Server verification

* Use k8sSearch backend for CA-only server verification

The autoTls backend always issues and signs per-pod certificates and
therefore requires the CA private key (ca.key); it cannot be used to
just publish an existing CA certificate. Use the k8sSearch backend
instead, which mounts the ca.crt from a labeled Secret into the Pod.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: lfrancke

modules/concepts/examples/secret-server-verification-ca.yaml

@@ -0,0 +1,12 @@
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: openldap-tls-ca
+  labels:
+    secrets.stackable.tech/class: openldap-tls-ca # <1>
+stringData:
+  ca.crt: | # <2>
+    -----BEGIN CERTIFICATE-----
+    ...
+    -----END CERTIFICATE-----

modules/concepts/examples/secretclass-server-verification-ca.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: openldap-tls-ca # <1>
+spec:
+  backend:
+    k8sSearch:
+      searchNamespace:
+        pod: {} # <2>

modules/concepts/pages/tls-server-verification.adoc

@@ -38,16 +38,40 @@ This can be useful when you e.g. use public AWS S3 or other public available ser
 include::example$tls-server-verification-webpki.yaml[]
 ----
 
-This example will use TLS and verify the server using the provided ca certificate.
-For this to work you need to create a xref:secret-operator:secretclass.adoc[] that - at least - contains the ca certificate.
-Note that a SecretClass does not need to have a key but can also work with just a ca cert.
-So if you were provided with a ca cert but do not have access to the key you can still use this method.
+This example will use TLS and verify the server using the provided CA certificate.
+The product CRD references a SecretClass that provides the CA certificate to verify the server against:
 
 [source,yaml]
 ----
 include::example$tls-server-verification-custom-ca.yaml[]
 ----
 
+The referenced `openldap-tls-ca` SecretClass does not exist yet, you have to create it.
+For server verification you only need to make the CA certificate available to the product as-is, so you use the xref:secret-operator:secretclass.adoc#backend-k8ssearch[`k8sSearch` backend], which mounts the contents of a Kubernetes Secret into the Pod.
+A SecretClass used only for server verification needs nothing but the CA certificate, it does not need a key.
+So if you were provided with a CA certificate but do not have access to its key, you can still use this method.
+
+First, store the CA certificate (in PEM format) that you were given in a Secret.
+The Secret must carry the label `secrets.stackable.tech/class` matching the SecretClass name, and the CA certificate must be stored under the key `ca.crt`:
+
+[source,yaml]
+----
+include::example$secret-server-verification-ca.yaml[]
+----
+
+<1> This label must match the name of the SecretClass created below.
+<2> The CA certificate in PEM format.
+
+Then create the SecretClass that uses the `k8sSearch` backend to find that Secret:
+
+[source,yaml]
+----
+include::example$secretclass-server-verification-ca.yaml[]
+----
+
+<1> The name of the SecretClass, this is what `caCert.secretClass` above refers to. It must match the Secret's `secrets.stackable.tech/class` label.
+<2> The backend looks for the labeled Secret in the same namespace as the Pod that consumes the certificate.
+
 === Mutual verification
 This example will use TLS and verify both - the server and the client using certificates.
 For this to work you need to create a xref:secret-operator:secretclass.adoc[] containing the ca certificate and a key to create new client-certificates.