docs: add documentation for namespace

Updated the documentation for the namespace annotation for the ReclaimSpace operation. Signed-off-by: Madhu Rajanna <[email protected]>
csi-addons · May 16, 2023 · b79bbd7 · b79bbd7
1 parent a091a17
commit b79bbd7
Showing 1 changed file with 37 additions and 11 deletions.
diff --git a/docs/reclaimspace.md b/docs/reclaimspace.md
@@ -14,9 +14,8 @@ spec:
   retryDeadlineSeconds: 900
 ```
 
-
 + `target` represents volume target on which the operation will be performed.
-    + `persistentVolumeClaim` contains a string indicating the name of `PersistentVolumeClaim`.
+  + `persistentVolumeClaim` contains a string indicating the name of `PersistentVolumeClaim`.
 + `backOfflimit` specifies the number of retries before marking reclaim space operation as failed. If not specified, defaults to 6. Maximum allowed value is 60 and minimum allowed value is 0.
 + `retryDeadlineSeconds` specifies the duration in seconds relative to the start time that the operation may be retried; value must be positive integer. If not specified, defaults to 600 seconds. Maximum allowed value is 1800.
 
@@ -63,7 +62,7 @@ spec:
 
 ## Annotating PerstentVolumeClaims
 
-`ReclaimSpaceCronJob` CR can also be automatically created by adding 
+`ReclaimSpaceCronJob` CR can also be automatically created by adding
 `reclaimspace.csiaddons.openshift.io/schedule: "@midnight"` annotation
 to PersistentVolumeClaim object.
 
@@ -75,7 +74,7 @@ data-pvc  Bound    pvc-f37b8582-4b04-4676-88dd-e1b95c6abf74   1Gi        RWO
 $ kubectl annotate pvc data-pvc "reclaimspace.csiaddons.openshift.io/schedule=@midnight"
 persistentvolumeclaim/data-pvc annotated
 
-$ kubectl get reclaimspacecronjobs.csiaddons.openshift.io 
+$ kubectl get reclaimspacecronjobs.csiaddons.openshift.io
 NAME                    SCHEDULE    SUSPEND   ACTIVE   LASTSCHEDULE   AGE
 data-pvc-1642663516   @midnight                                     3s
 
@@ -87,14 +86,41 @@ NAME                  SCHEDULE    SUSPEND   ACTIVE   LASTSCHEDULE   AGE
 data-pvc-1642664617   */1 * * * *                                   3s
 ```
 
-- Upon adding annotation as shown above, a `ReclaimSpaceCronJob` with name
-  `"<pvc-name>-xxxxxxx"` is created (pvc name suffixed with current time hash when 
-  the job was created). 
-- `schedule` value is in the same [format as Kubernetes CronJobs][batch_cronjob]
++ Upon adding annotation as shown above, a `ReclaimSpaceCronJob` with name
+  `"<pvc-name>-xxxxxxx"` is created (pvc name suffixed with current time hash when
+  the job was created).
++ `schedule` value is in the same [format as Kubernetes CronJobs][batch_cronjob]
   that sets the and/or interval of the recurring operation request.
-- Default schedule value `"@weekly"` is used if `schedule` value is empty or in invalid format. 
-- `ReclaimSpaceCronJob` is recreated when `schedule` is modified and deleted when
++ Default schedule value `"@weekly"` is used if `schedule` value is empty or in invalid format.
++ `ReclaimSpaceCronJob` is recreated when `schedule` is modified and deleted when
   the annotation is removed.
 
 [batch_cronjob]: https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/
-[go_cron]: https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format
+[go_cron]:
+    https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format
+
+## Annotating Namespace
+
+You can create `ReclaimSpaceCronJob` CR automatically by adding the
+`reclaimspace.csiaddons.openshift.io/schedule: "@midnight"` and (optional)
+`reclaimspace.csiaddons.openshift.io/drivers: drivernames` annotations to the
+Namespace object. This will only inspect new PersistentVolumeClaims in the
+Namespace for ReclaimSpace operations. You must restart the controller if you
+want kubernetes-csi-addons to consider existing PersistentVolumeClaims.
+
+`drivernames` can be `,` separated driver names that supports reclaimspace operations.
+
+```
+$ kubectl get namespace default
+NAME      STATUS   AGE
+default   Active   5d2h
+
+$ kubectl annotate namespace default "reclaimspace.csiaddons.openshift.io/schedule=@midnight"
+namespace/default annotated
+```
+
+**Note** Please note that the PersistentVolumeClaim annotation takes priority
+over Namespace annotation. The kubernetes-csi-addons only generate a
+`ReclaimSpaceCronJob` if the annotation exists on the Namespace. If an admin
+needs to modify or delete the annotation on the Namespace, they must perform
+the same action on all the PersistentVolumeClaims within that Namespace.