Some handover documentation (#615)

* Try to clarify the purpose

* Fix usage example referring to a different SecretClass than it defines

* Fix usage documentation still referring to ephemeral CSI volumes

* Clarify that the usage page is not really for end users

* Fix the stacklet page link

Author: nightkr

docs/modules/secret-operator/examples/usage-pod.yaml

@@ -10,7 +10,7 @@ spec:
         volumeClaimTemplate:
           metadata:
             annotations:
-              secrets.stackable.tech/class: secret
+              secrets.stackable.tech/class: tls
               secrets.stackable.tech/scope: node,pod,service=secret-consumer-nginx
           spec:
             storageClassName: secrets.stackable.tech

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

@@ -7,11 +7,12 @@
 * {github}[GitHub {external-link-icon}^]
 * {crd}[CRD documentation {external-link-icon}^]
 
-This is an operator for Kubernetes that provisions and injects secrets into Kubernetes Pods.
+This is an operator for Kubernetes that provisions and injects credentials (such as TLS certificates and Kerberos keytabs) into Kubernetes Pods, so that they can authenticate each others' identities.
 
-Kubernetes Secret objects contain sensitive payloads such as passwords, tokens or keys.
+Kubernetes Secrets contain sensitive payloads such as passwords, tokens or keys.
 These objects are usually self-contained and static in the sense that their contents remain unchanged as long as their owners do not update them.
+Kubernetes also has little-to-no built-in support for dealing with Secrets that have to vary depending on details of the target Pod, such as its assigned Node or the individual Pod identity (when created from a template controller, such as a Deployment or StatefulSet).
 
-The Stackable Secret Operator enhances the functionality of Kubernetes Secrets by introducing the concept of a SecretClass.
-A SecretClass represents a reference to a source of sensitive data.
-In addition to Kubernetes Secret objects, the operator can provision Pods with TLS Certificates, Kerberos keytabs or authentication tokens from external services.
+The Stackable Secret Operator introduces a new mechanism to mount secrets depending on different xref:scope.adoc[aspects] of the target Pod.
+It also allows administrators to dictate cluster-wide xref:secretclass.adoc[policies] for how these credentials are provisioned.
+For example, TLS certificates can be provisioned xref:secretclass.adoc#backend-k8ssearch[manually] (but with the ability to _select_ the correct certificate automatically), xref:secretclass.adoc#backend-autotls[by a built-in certificate authority], or by delegating to xref:secretclass.adoc#backend-certmanager[cert-manager].

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

@@ -2,11 +2,10 @@
 :description: A SecretClass in Kubernetes defines secret categories, handling certificate provision and secret management via multiple backends.
 :cert-manager: https://cert-manager.io/
 
-A _SecretClass_ is a cluster-global Kubernetes resource that defines a category of secrets that the Secret Operator knows how to provision.
+A _SecretClass_ is a cluster-global Kubernetes resource that defines a source of credentials that the Secret Operator knows how to provision.
 
-This is intended to provide an abstraction between how the secret is used ("I need a certificate for my cluster's TLS PKI") and how
-it is provisioned (automatically and generated by the operator's internal CA, provisioned by the cluster administrator, or provisioned by an
-external service such as Hashicorp Vault).
+This is intended to provide an abstraction between how the secret is used ("I need a certificate for my cluster's TLS PKI"),
+and the policy for how it is provisioned (automatically and generated by the operator's internal CA, provisioned by the cluster administrator, or provisioned by an external service such as Hashicorp Vault).
 
 A SecretClass looks like this:
 

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

@@ -1,6 +1,8 @@
 = Usage
 
-The operator injects secret data into xref:volume.adoc[] mounts that declare a CSI volume with `driver: secrets.stackable.tech`.
+The operator injects secret data into xref:volume.adoc[] mounts that declare an ephemeral volume with `storageClassName: secrets.stackable.tech`.
+
+NOTE: This page is only relevant for developers deploying their own Pods. Users deploying a Stackable Data Platform xref:concepts:stacklet.adoc[stacklet] should use the stacklet's secret class field instead.
 
 A minimal secret-consuming Pod looks like this: