Skip to content

Some handover documentation #615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nightkr merged 5 commits into from
Jul 1, 2025
Merged

Some handover documentation #615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
21db477
Try to clarify the purpose
nightkr Jun 30, 2025
0aae47c
Fix usage example referring to a different SecretClass than it defines
nightkr Jun 30, 2025
6a79d5b
Fix usage documentation still referring to ephemeral CSI volumes
nightkr Jun 30, 2025
03bb5ff
Clarify that the usage page is not really for end users
nightkr Jun 30, 2025
ad05f5c
Fix the stacklet page link
nightkr Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/modules/secret-operator/examples/usage-pod.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 6 additions & 5 deletions docs/modules/secret-operator/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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].
7 changes: 3 additions & 4 deletions docs/modules/secret-operator/pages/secretclass.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
4 changes: 3 additions & 1 deletion docs/modules/secret-operator/pages/usage.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand Down