From 21db477e8a1ad44c13c511eba14889a42abf762a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Mon, 30 Jun 2025 14:48:58 +0200 Subject: [PATCH 1/5] Try to clarify the purpose --- docs/modules/secret-operator/pages/index.adoc | 11 ++++++----- docs/modules/secret-operator/pages/secretclass.adoc | 7 +++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/modules/secret-operator/pages/index.adoc b/docs/modules/secret-operator/pages/index.adoc index 4461f0e5..ac071150 100644 --- a/docs/modules/secret-operator/pages/index.adoc +++ b/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]. diff --git a/docs/modules/secret-operator/pages/secretclass.adoc b/docs/modules/secret-operator/pages/secretclass.adoc index 9bfbc8a3..10fb54a1 100644 --- a/docs/modules/secret-operator/pages/secretclass.adoc +++ b/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: From 0aae47c066f3161348ac0955d5d1379577d2568e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Mon, 30 Jun 2025 14:53:52 +0200 Subject: [PATCH 2/5] Fix usage example referring to a different SecretClass than it defines --- docs/modules/secret-operator/examples/usage-pod.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/secret-operator/examples/usage-pod.yaml b/docs/modules/secret-operator/examples/usage-pod.yaml index 897737c9..6b96f3fe 100644 --- a/docs/modules/secret-operator/examples/usage-pod.yaml +++ b/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 From 6a79d5bf99eb0250e7b2514a8b7377c8e127e616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Mon, 30 Jun 2025 14:54:17 +0200 Subject: [PATCH 3/5] Fix usage documentation still referring to ephemeral CSI volumes --- docs/modules/secret-operator/pages/usage.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/secret-operator/pages/usage.adoc b/docs/modules/secret-operator/pages/usage.adoc index e25dc423..bf0f238d 100644 --- a/docs/modules/secret-operator/pages/usage.adoc +++ b/docs/modules/secret-operator/pages/usage.adoc @@ -1,6 +1,6 @@ = 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`. A minimal secret-consuming Pod looks like this: From 03bb5ff75929e42b7f242d255b96eecf762415e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Mon, 30 Jun 2025 14:54:41 +0200 Subject: [PATCH 4/5] Clarify that the usage page is not really for end users --- docs/modules/secret-operator/pages/usage.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/modules/secret-operator/pages/usage.adoc b/docs/modules/secret-operator/pages/usage.adoc index bf0f238d..417d6628 100644 --- a/docs/modules/secret-operator/pages/usage.adoc +++ b/docs/modules/secret-operator/pages/usage.adoc @@ -2,6 +2,8 @@ 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:home:stacklet.adoc[stacklet] should use the stacklet's secret class field instead. + A minimal secret-consuming Pod looks like this: [source,yaml] From ad05f5c1258550133ba939d422b8a8ed2339fab1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Mon, 30 Jun 2025 15:13:52 +0200 Subject: [PATCH 5/5] Fix the stacklet page link --- docs/modules/secret-operator/pages/usage.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/secret-operator/pages/usage.adoc b/docs/modules/secret-operator/pages/usage.adoc index 417d6628..d076bf3c 100644 --- a/docs/modules/secret-operator/pages/usage.adoc +++ b/docs/modules/secret-operator/pages/usage.adoc @@ -2,7 +2,7 @@ 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:home:stacklet.adoc[stacklet] should use the stacklet's secret class field instead. +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: