Add some documentation on how to add elements to clustergroup

Author: Martin Jackson

README.md

@@ -8,3 +8,24 @@ The main purpose of this collections are to:
 loading local secrets files into VP secrets stores.
 
 2. Help manage imperative and other utility functions of the cluster
+
+## SS CSI workload auth notes
+
+`vault_utils` can read `ssCsiWorkloadAuth` entries from clustergroup values and
+create Vault Kubernetes auth roles for hub and spoke workloads.
+
+At the application level (`clusterGroup.applications.<app>`), the relevant
+inputs are:
+
+- `ssCsiWorkloadAuth` (list)
+- `ssCsiWorkloadAuth[].serviceAccount` (required)
+- `ssCsiWorkloadAuth[].namespace` (optional)
+- `ssCsiWorkloadAuth[].cluster` (optional)
+- `ssCsiWorkloadAuth[].roleSlug` / `role_slug` (optional)
+- application `namespace` (optional default for entry namespace)
+
+CA material management for SS CSI is not handled in this collection anymore.
+Provide CA distribution using a separate chart or platform mechanism.
+
+For the complete flow and task ordering, see
+`secrets-initialization-and-vault-unseal.md`.

roles/vault_utils/README.md

@@ -54,6 +54,38 @@ This role configures four secret paths in vault:
    be used with ESO's `PushSecrets` so you can push an existing secret from one namespace, to the vault under this path and
    then it can be retrieved by an `ExternalSecret` either in a different namespace *or* from an entirely different cluster.
 
+## SS CSI workload auth
+
+This role can create Vault Kubernetes auth roles from
+`clusterGroup.applications.*.ssCsiWorkloadAuth` and
+`clusterGroup.managedClusterGroups.*.applications.*.ssCsiWorkloadAuth`.
+
+For each `ssCsiWorkloadAuth` entry:
+
+- required: `serviceAccount`
+- optional: `namespace`, `cluster`, `roleSlug` (or `role_slug`)
+
+Application-level `namespace` is used as the default when an entry does not set
+`namespace`.
+
+Example:
+
+```yaml
+clusterGroup:
+  applications:
+    my-app:
+      namespace: my-app-namespace
+      ssCsiWorkloadAuth:
+        - serviceAccount: my-app-sa
+          cluster: hub
+```
+
+SS CSI CA material management is external to this role. Use a separate chart or
+platform CA distribution workflow for Vault route trust.
+
+For a detailed end-to-end description of `vault.yml` task order and SS CSI
+behavior, see `secrets-initialization-and-vault-unseal.md` in this repository.
+
 ## Values secret file format
 
 Currently this role supports two formats: version 1.0 (which is the assumed