docs: namespace labeling for tenant owners

docs/operator/use-cases/namespace-labels-and-annotations.md

@@ -0,0 +1,64 @@
+# Assign Pod Security Policies
+
+By default, capsule allows tenant owners to add only `capsule.clastix.io/tenant` label on their namespaces in order to support [multiple tenants owned by a single owner](./multiple-tenants.md). This is a necessary security measure in shared multi-tenant environments to protect tenant resources from different malicious attacks.
+
+But there are some scenarios, where organization have a set of defined and well-known labels or annotations, which must be set on a tenant namespaces.
+
+Bill, the cluster admin, can allow Alice to add specific labels and annotations on namespaces:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - name: alice
+    kind: User
+  namespaceOptions:
+    userLabels:
+      allowedLabels:
+        allowed:
+        - foo.acme.net
+        allowedRegex: .*.acme.net
+    userAnnotations:
+      allowedAnnotations:
+        allowed:
+        - foo.acme.net
+        allowedRegex: .*.acme.net
+EOF
+```
+Bill can also protect some labels or annotations from being able to be set by Alice:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - name: alice
+    kind: User
+  namespaceOptions:
+    userLabels:
+      allowedLabels:
+        allowedRegex: .*.acme.net
+      protectedLabels:
+        protected:
+          - foo.acme.net
+    userAnnotations:
+      allowedAnnotations:
+        allowedRegex: .*.acme.net
+      protectedAnnotations:
+        protected:
+        - foo.acme.net
+EOF
+```
+
+
+# What’s next
+This ends our tour in Capsule use cases. As we improve Capsule, more use cases about multi-tenancy, policy admission control, and cluster governance will be covered in the future.
+
+Stay tuned!

docs/operator/use-cases/overview.md

@@ -40,6 +40,7 @@ Use Capsule to address any of the following scenarios:
 * [Cordon Tenants](./cordoning-tenant.md)
 * [Disable Service Types](./service-type.md)
 * [Taint Services](./taint-services.md)
+* [Allow adding labels and annotations on namespaces](./namespace-labels-and-annotations.md)
 * [Velero Backup Restoration](./velero-backup-restoration.md)
 
 > NB: as we improve Capsule, more use cases about multi-tenancy and cluster governance will be covered.

docs/operator/use-cases/taint-services.md

@@ -25,6 +25,4 @@ EOF
 When Alice creates a service in a namespace, this will inherit the given label and/or annotation.
 
 # What’s next
-This ends our tour in Capsule use cases. As we improve Capsule, more use cases about multi-tenancy, policy admission control, and cluster governance will be covered in the future.
-
-Stay tuned!
+See how Bill, the cluster admin, can allow Alice to use specific labels or annotations. [Allow adding labels and annotations on namespaces](./namespace-labels-and-annotations.md).