From 36b3f483a88940238814269a33b4d1f85f432730 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Fri, 7 Feb 2025 14:16:10 -0700 Subject: [PATCH 01/21] draft of docs for doc team --- .../oadp-self-service.md | 115 ++++++++++++++++++ docs/draft_production_docs/sequenceDiagram.md | 16 +++ 2 files changed, 131 insertions(+) create mode 100644 docs/draft_production_docs/oadp-self-service.md create mode 100644 docs/draft_production_docs/sequenceDiagram.md diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md new file mode 100644 index 00000000..c24bfc24 --- /dev/null +++ b/docs/draft_production_docs/oadp-self-service.md @@ -0,0 +1,115 @@ +# OADP Self Service Documentation + +## Overview + +OADP Self Service enables non-administrator users to perform backup and restore operations in their authorized namespaces without requiring cluster-wide administrator privileges. This feature provides secure self-service data protection capabilities while maintaining proper access controls. + +### Key Benefits + +- Allows namespace-scoped backup and restore operations +- Provides secure access to backup logs and status information +- Enables users to create dedicated backup storage locations +- Maintains cluster administrator control over non-administrator operations through templates and policies + +### Components + +The self-service functionality is implemented through several custom resources: + +- NonAdminBackup (NAB) - Manages namespace-scoped backup operations +- NonAdminRestore (NAR) - Handles namespace-scoped restore operations +- NonAdminBackupStorageLocation (NABSL) - Defines user-specific backup storage locations +- NonAdminController (NAC) - Controls and orchestrates the self-service operations + +## OADP Self Service + +Previously, the OADP (OpenShift API for Data Protection) Operator required cluster administrator privileges to perform any backup and restore operations. With OADP self-service, regular users can now safely perform backup and restore operations within namespaces where they have appropriate permissions. +OADP self-service enables regular OpenShift users to perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. Users can: + +- Create and manage backups of their authorized namespaces +- Restore data to their authorized namespaces +- Monitor backup and restore status +- Access relevant logs and descriptions +- Configure their own backup storage locations + +The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. + +## Glossary of terms +* NAB - Non Admin Backup +* NAR - Non Admin Restore +* NAC - Non Admin Controller +* NABSL - Non Admin Backup Storage Location + + +## Cluster Administrator Setup + +Install and configure the OADP operator according to the documentation and your requirements. + +To enable OADP Self-Service the DPA spec must have these 2 things: + +``` + nonAdmin: + enable: true + unsupportedOverrides: + tech-preview-ack: "true" +``` + +Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. + +The Openshift users without cluster admin rights can create NAB objects in their namespace to create a backup. + +## OpenShift User Instructions + +Prior to OpenShift users taking advantage of OADP self-service feature the OpenShift cluster administrator must have completed the following prerequisite steps: + +* The OADP DPA has been configured to support self-service +* The cluster administrator has created the users + * account + * namespace + * namespace admin privileges + +Non Cluster Administrators can utilize OADP self-service by creating NonAdminBackup (NAB) and NonAdminRestore (NAR) objects in the namespace to be backed up or restored. A NonAdminBackup is an OpenShift custom resource that securely facilitates the creation, status and lifecycle of a Velero Backup custom resource. + +```mermaid +sequenceDiagram + participant User + participant NAB as NonAdminBackup + participant NAC as NonAdminController + participant VB as Velero Backup + + User->>NAB: Creates NonAdminBackup CR + NAB->>NAC: Detected by controller + NAC-->>NAB: Validates backup request + NAC->>VB: Creates Velero Backup CR + VB-->>NAB: Status updates + NAB-->>User: View backup status +``` + +![nab-backup-workflow](https://hackmd.io/_uploads/BJz4bEbKyx.jpg) + +For the most part one can think of a NonAdminBackup and a Velero Backup in very much the same way. Both objects specify a velero backup and how the backup should be executed. There are a few differences to keep in mind when creating a NonAdminBackup. + +1. The NonAdminBackup creates the Velero Backup CR instance in a secure way that limits the users access. +2. A user cannot specify the namespace that will be backed up. The namespace from which the NAB object is created is the defined namespace to be backed up. +3. In addition to the creation of the Velero Backup the NonAdminBackup object's main purpose is to track the status of the Velero Backup in a secure and clear way. + + +### NAB / NAR Status + +#### Phase +The phase field is a simple one high-level summary of the lifecycle of the objects, that only moves forward. Once a phase changes, it can not return to the previous value. + +| **Value** | **Description** | +|-----------|-----------------| +| New | *NonAdminBackup/NonAdminRestore* resource was accepted by the NAB/NAR Controller, but it has not yet been validated by the NAB/NAR Controller | +| BackingOff | *NonAdminBackup/NonAdminRestore* resource was invalidated by the NAB/NAR Controller, due to invalid Spec. NAB/NAR Controller will not reconcile the object further, until user updates it | +| Created | *NonAdminBackup/NonAdminRestore* resource was validated by the NAB/NAR Controller and Velero *Backup/restore* was created. The Phase will not have additional information about the *Backup/Restore* run | +| Deletion | *NonAdminBackup/NonAdminRestore* resource has been marked for deletion. The NAB/NAR Controller will delete the corresponding Velero *Backup/Restore* if it exists. Once this deletion completes, the *NonAdminBackup/NonAdminRestore* object itself will also be removed | + + + + + + + + + diff --git a/docs/draft_production_docs/sequenceDiagram.md b/docs/draft_production_docs/sequenceDiagram.md new file mode 100644 index 00000000..0cbe79cc --- /dev/null +++ b/docs/draft_production_docs/sequenceDiagram.md @@ -0,0 +1,16 @@ +# test + +```mermaid +sequenceDiagram + participant User + participant NAB as NonAdminBackup + participant NAC as NonAdminController + participant VB as Velero Backup + + User->>NAB: Creates NonAdminBackup CR + NAB->>NAC: Detected by controller + NAC-->>NAB: Validates backup request + NAC->>VB: Creates Velero Backup CR + VB-->>NAB: Status updates + NAB-->>User: View backup status +``` From dd5d70295842a5ee148f4e1a38ee066c259d5fa6 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Thu, 20 Feb 2025 20:08:50 -0700 Subject: [PATCH 02/21] update enforcements --- .../oadp-self-service.md | 119 +++++++++++++++++- 1 file changed, 113 insertions(+), 6 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index c24bfc24..70b20307 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -38,19 +38,18 @@ The self-service functionality is implemented in a way that ensures users can on * NAR - Non Admin Restore * NAC - Non Admin Controller * NABSL - Non Admin Backup Storage Location +* NADR - Non Admin Download Request ## Cluster Administrator Setup Install and configure the OADP operator according to the documentation and your requirements. -To enable OADP Self-Service the DPA spec must have these 2 things: +To enable OADP Self-Service the DPA spec must the spec.nonAdmin.enable field to true. ``` nonAdmin: enable: true - unsupportedOverrides: - tech-preview-ack: "true" ``` Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. @@ -65,7 +64,7 @@ Prior to OpenShift users taking advantage of OADP self-service feature the OpenS * The cluster administrator has created the users * account * namespace - * namespace admin privileges + * namespace privileges, e.g. namespace admin. Non Cluster Administrators can utilize OADP self-service by creating NonAdminBackup (NAB) and NonAdminRestore (NAR) objects in the namespace to be backed up or restored. A NonAdminBackup is an OpenShift custom resource that securely facilitates the creation, status and lifecycle of a Velero Backup custom resource. @@ -106,10 +105,118 @@ The phase field is a simple one high-level summary of the lifecycle of the objec | Deletion | *NonAdminBackup/NonAdminRestore* resource has been marked for deletion. The NAB/NAR Controller will delete the corresponding Velero *Backup/Restore* if it exists. Once this deletion completes, the *NonAdminBackup/NonAdminRestore* object itself will also be removed | +## Advanced Cluster Administrator Features +### Restricted NonAdminBackupStorageLocation +Cluster administrators can gain efficiencies by delegating backup and restore operations to OpenShift users. It is recommended that cluster administrators carefully manage the NABSL to conform to any company policies, compliance requirements, etc. There are two ways cluster administrators can manage the NABSL's. +1. Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. +``` + nonAdmin: + enable: true + requireAdminApprovalForBSL: true +``` - - +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NABSLApprovalRequest +metadata: + name: nabsl-hash-name + namespace: openshift-adp +spec: + nabslName: nabsl-name + nabslNamespace: nac-user-ns + creationApproved: false # Tracks approval for creation + updateApproved: false # Tracks approval for updates + lastApprovedSpec: {} # Stores last approved NABSL spec +``` + This ensures the cluster administrator has reviewed the NABSL to ensure the correct object storage location options are used. + +### Cluster Administrator Enforceable Spec Fields + +Cluster administrators may also enforce templated NABSL's, NAB's and NAR's that require fields values to be set and conform to the administrator defined policy. Admin Enforceable fields are fields that the cluster administrator can enforce non cluster admin users to use. Restricted fields are automatically managed by OADP and cannot be modified by either administrators or users. + +#### NABSL +The following NABSL fields are currently supported for template enforcement: + +| **NABSL Field** | **Admin Enforceable** | **Restricted** | +|----------------------------|-----------------|----------------| +| `backupSyncPeriod` | ⚠️ special case | | +| `provider` | ⚠️ special case | | +| `objectStorage` | ✅ Yes | | +| `credential` | ✅ Yes | | +| `config` | ✅ Yes | | +| `accessMode` | ✅ Yes | | +| `validationFrequency` | ✅ Yes | | + + +TODO need example NABSL enforcement + +#### Restricted NonAdminBackups + +In the same sense as the NABSL, cluster administrators can also restrict the NonAdminBackup spec fields to ensure the backup request conforms to the administrator defined policy. Most of the backup spec fields can be restricted by the cluster administrator, below is a table of reference for the current implementation. + + +| **Backup Spec Field** | **Admin Enforceable** | **Restricted** | +|--------------------------------------------|--------------|--------------------------| +| `csiSnapshotTimeout` | ✅ Yes | | +| `itemOperationTimeout` | ✅ Yes | | +| `resourcePolicy` | ✅ Yes | ⚠️ special case | +| `includedNamespaces` | ❌ No | ✅ Yes | +| `excludedNamespaces` | ✅ Yes | ✅ Yes | +| `includedResources` | ✅ Yes | | +| `excludedResources` | ✅ Yes | | +| `orderedResources` | ✅ Yes | | +| `includeClusterResources` | ✅ Yes | ⚠️ special case | +| `excludedClusterScopedResources` | ✅ Yes | | +| `includedClusterScopedResources` | ✅ Yes | ⚠️ special case | +| `excludedNamespaceScopedResources` | ✅ Yes | | +| `includedNamespaceScopedResources` | ✅ Yes | | +| `labelSelector` | ✅ Yes | | +| `orLabelSelectors` | ✅ Yes | | +| `snapshotVolumes` | ✅ Yes | | +| `storageLocation` | ⚠️ special case | | +| `volumeSnapshotLocations` | ⚠️ special case | | +| `ttl` | ✅ Yes | | +| `defaultVolumesToFsBackup` | ✅ Yes | | +| `snapshotMoveData` | ✅ Yes | | +| `datamover` | ✅ Yes | | +| `uploaderConfig.parallelFilesUpload` | ✅ Yes | | +| `hooks` | ⚠️ special case | | + + + +#### Restricted NonAdminRestore NAR + +NonAdminRestores spec fields can also be restricted by the cluster administrator. The following NAR spec fields are currently supported for template enforcement: + +| **Field** | **Admin Enforceable** | **Restricted** | +|-------------------------------|--------------|--------------------| +| `backupName` | ❌ No | | +| `scheduleName` | ❌ No | ✅ Yes | +| `itemOperationTimeout` | ✅ Yes | | +| `uploaderConfig` | ✅ Yes | | +| `includedNamespaces` | ❌ No | ✅ Yes | +| `excludedNamespaces` | ❌ No | ✅ Yes | +| `includedResources` | ✅ Yes | | +| `excludedResources` | ✅ Yes | | +| `restoreStatus` | ✅ Yes | | +| `includeClusterResources` | ✅ Yes | | +| `labelSelector` | ✅ Yes | | +| `orLabelSelectors` | ✅ Yes | | +| `namespaceMapping` | ❌ No | ✅ Yes | +| `restorePVs` | ✅ Yes | | +| `preserveNodePorts` | ✅ Yes | | +| `existingResourcePolicy` | ✅ Yes | | +| `resourceModifier` | ⚠️ special case | | +| `hooks` | ⚠️ special case | | + + + +## TODO +* add a section that describes which backup spec fields can be restricted by the cluster administrator https://github.com/migtools/oadp-non-admin/issues/151 +* Document limited non-admin console use - via + * administrator -> Home -> API Explorer -> Filter on NonAdminBackup or NonAdminRestore -> Instances -> Create NonAdminBackup or NonAdminRestore + \ No newline at end of file From 55a99d29d8a373207765e7ac4b031a0497866937 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Thu, 20 Feb 2025 20:12:04 -0700 Subject: [PATCH 03/21] nit --- docs/draft_production_docs/oadp-self-service.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 70b20307..8b464e8e 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -52,9 +52,7 @@ To enable OADP Self-Service the DPA spec must the spec.nonAdmin.enable field to enable: true ``` -Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. - -The Openshift users without cluster admin rights can create NAB objects in their namespace to create a backup. +Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. The Openshift users without cluster admin rights will now be able to create NAB or NAR objects in their namespace to create a backup or restore. ## OpenShift User Instructions From 002ac63d825e6e07b2c8239378bad1bea83aa77e Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Thu, 20 Feb 2025 20:13:34 -0700 Subject: [PATCH 04/21] nit --- docs/draft_production_docs/oadp-self-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 8b464e8e..49fd6ff0 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -109,7 +109,7 @@ The phase field is a simple one high-level summary of the lifecycle of the objec Cluster administrators can gain efficiencies by delegating backup and restore operations to OpenShift users. It is recommended that cluster administrators carefully manage the NABSL to conform to any company policies, compliance requirements, etc. There are two ways cluster administrators can manage the NABSL's. -1. Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. +Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. ``` nonAdmin: From a5be845234972b6a6525718cdd0ed4a6dbc3996f Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Thu, 20 Feb 2025 20:37:32 -0700 Subject: [PATCH 05/21] add examples --- .../oadp-self-service.md | 29 +++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 49fd6ff0..36ffc9d5 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -134,7 +134,7 @@ spec: ### Cluster Administrator Enforceable Spec Fields -Cluster administrators may also enforce templated NABSL's, NAB's and NAR's that require fields values to be set and conform to the administrator defined policy. Admin Enforceable fields are fields that the cluster administrator can enforce non cluster admin users to use. Restricted fields are automatically managed by OADP and cannot be modified by either administrators or users. +Cluster administrators may also enforce company or compliance policy by utilizing templated NABSL's, NAB's and NAR's that require fields values to be set and conform to the administrator defined policy. Admin Enforceable fields are fields that the cluster administrator can enforce non cluster admin users to use. Restricted fields are automatically managed by OADP and cannot be modified by either administrators or users. #### NABSL The following NABSL fields are currently supported for template enforcement: @@ -149,8 +149,24 @@ The following NABSL fields are currently supported for template enforcement: | `accessMode` | ✅ Yes | | | `validationFrequency` | ✅ Yes | | +For example if the cluster administrator wanted to mandate that all NABSL's used a particular aws s3 bucket. -TODO need example NABSL enforcement +``` +spec: + config: + checksumAlgorithm: "" + profile: default + region: us-west-2 + credential: + key: cloud + name: cloud-credentials + default: true + objectStorage: + bucket: my-company-bucket <--- + prefix: velero + provider: aws +``` +The DPA spec must be set in the following way: TODO GET NABSL ENFORCEMENT EXAMPLE #### Restricted NonAdminBackups @@ -184,7 +200,16 @@ In the same sense as the NABSL, cluster administrators can also restrict the Non | `uploaderConfig.parallelFilesUpload` | ✅ Yes | | | `hooks` | ⚠️ special case | | +An example enforcement set in the DPA spec to enforce the + * ttl to be set to "158h0m0s" + * snapshotMoveData to be set to true +``` + nonAdmin: + enable: true + enforcedBackupSpec.ttl: "158h0m0s" + enforcedBackupSpec.snapshotMoveData: true +``` #### Restricted NonAdminRestore NAR From 10955811ac6fc52609acd2105923fc48ab64a24d Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Fri, 21 Feb 2025 14:16:27 -0700 Subject: [PATCH 06/21] add nab and nar example --- .../oadp-self-service.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 36ffc9d5..2572e7b2 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -89,6 +89,139 @@ For the most part one can think of a NonAdminBackup and a Velero Backup in very 2. A user cannot specify the namespace that will be backed up. The namespace from which the NAB object is created is the defined namespace to be backed up. 3. In addition to the creation of the Velero Backup the NonAdminBackup object's main purpose is to track the status of the Velero Backup in a secure and clear way. +### NonAdminBackup NAB Example: + +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackup +metadata: + name: mybackup-1 + namespace: nacuser1 +spec: + backupSpec: + snapshotMoveData: true +``` + +Once created the NAB will look similar to the following: + +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackup +metadata: + creationTimestamp: "2025-02-21T20:57:35Z" + finalizers: + - nonadminbackup.oadp.openshift.io/finalizer + generation: 2 + name: mybackup-1 + namespace: nacuser1 <--- The namespace is set by the NAC controller + resourceVersion: "20714121" + uid: 93effb39-9762-4d04-8e9e-194ebe6b9b31 +spec: + backupSpec: + snapshotMoveData: true +status: + conditions: + - lastTransitionTime: "2025-02-21T20:57:35Z" + message: backup accepted <--- The NAC controller reconciled the NAB object and created the Velero Backup object + reason: BackupAccepted + status: "True" + type: Accepted + - lastTransitionTime: "2025-02-21T20:57:35Z" + message: Created Velero Backup object + reason: BackupScheduled + status: "True" + type: Queued + phase: Created <--- The NAB object is in the Created phase + queueInfo: + estimatedQueuePosition: 0 <--- The NAB object status in the queue, once complete it is set to 0 + veleroBackup: + nacuuid: nacuser1-mybackup-1-588ce989-387e-4352-b04a-1fd6b7712370 <--- The NAC controller created the Velero Backup object and set the nacuuid + name: nacuser1-mybackup-1-588ce989-387e-4352-b04a-1fd6b7712370 <--- The associated Velero Backup name + namespace: openshift-adp + status: <--- The status of the Velero backup object displayed by the NAB object + backupItemOperationsAttempted: 3 + backupItemOperationsCompleted: 3 + completionTimestamp: "2025-02-21T20:59:28Z" + expiration: "2025-03-23T20:57:35Z" + formatVersion: 1.1.0 + hookStatus: {} + phase: Completed <--- The Velero backup object is in the Completed phase, successful + progress: + itemsBackedUp: 57 + totalItems: 57 + startTimestamp: "2025-02-21T20:57:35Z" + version: 1 +``` +The complete nonAdminBackup resource definition can be found here: [NonAdminBackup CRD](https://github.com/openshift/oadp-operator/blob/master/bundle/manifests/oadp.openshift.io_nonadminbackups.yaml) + +### NonAdminRestore NAR Example: + +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminRestore +metadata: + name: example + namespace: nacuser1 +spec: + restoreSpec: + backupName: mybackup-1 +``` + +Once created the NAR will look similar to the following: + +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminRestore +metadata: + creationTimestamp: "2025-02-21T21:12:54Z" + finalizers: + - nonadminrestore.oadp.openshift.io/finalizer + generation: 2 + name: example + namespace: nacuser1 + resourceVersion: "20719136" + uid: 0f1d8346-d8be-4621-8d67-0877f15e82fb +spec: + restoreSpec: + backupName: mybackup-1 + hooks: {} + itemOperationTimeout: 0s +status: + conditions: + - lastTransitionTime: "2025-02-21T21:12:54Z" + message: restore accepted <--- The NAC controller reconciled the NAR object and created the Velero Restore object + reason: RestoreAccepted + status: "True" + type: Accepted + - lastTransitionTime: "2025-02-21T21:12:54Z" + message: Created Velero Restore object <--- The NAC controller created the Velero Restore object + reason: RestoreScheduled + status: "True" + type: Queued + phase: Created <--- The NAR object is in the Created phase + queueInfo: + estimatedQueuePosition: 0 <--- The NAR object status in the queue, once complete it is set to 0 + veleroRestore: + nacuuid: nacuser1-example-b844be97-7ee4-4702-91b8-ffc84697675a <--- The NAC controller created the Velero Restore object and set the nacuuid + name: nacuser1-example-b844be97-7ee4-4702-91b8-ffc84697675a <--- The associated Velero Restore name + namespace: openshift-adp + status: + completionTimestamp: "2025-02-21T21:12:57Z" + hookStatus: {} + phase: Completed <--- The Velero restore object is in the Completed phase, successful + progress: + itemsRestored: 54 + totalItems: 54 + startTimestamp: "2025-02-21T21:12:55Z" + warnings: 0 +``` + + + + + + + ### NAB / NAR Status From cdb6c487ea4c27933067a829339f944a4eb2498d Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 14:54:26 -0700 Subject: [PATCH 07/21] link to restore crd def --- docs/draft_production_docs/oadp-self-service.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 2572e7b2..dc629b6a 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -215,10 +215,7 @@ status: startTimestamp: "2025-02-21T21:12:55Z" warnings: 0 ``` - - - - +The complete nonAdminRestore resource definition can be found here: [NonAdminRestore CRD](https://github.com/openshift/oadp-operator/blob/master/bundle/manifests/oadp.openshift.io_nonadminrestores.yaml) From 78ae082f28f5c5d3d137386b9f4133d09e623c77 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:08:15 -0700 Subject: [PATCH 08/21] update for clarity --- .../oadp-self-service.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index dc629b6a..3919cdeb 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -1,4 +1,4 @@ -# OADP Self Service Documentation +# OADP Self Service Overview ## Overview @@ -9,7 +9,8 @@ OADP Self Service enables non-administrator users to perform backup and restore - Allows namespace-scoped backup and restore operations - Provides secure access to backup logs and status information - Enables users to create dedicated backup storage locations -- Maintains cluster administrator control over non-administrator operations through templates and policies +- Maintains cluster administrator control over non-administrator operations through +templates and policies ### Components @@ -20,18 +21,10 @@ The self-service functionality is implemented through several custom resources: - NonAdminBackupStorageLocation (NABSL) - Defines user-specific backup storage locations - NonAdminController (NAC) - Controls and orchestrates the self-service operations -## OADP Self Service +## OADP Self Service Details -Previously, the OADP (OpenShift API for Data Protection) Operator required cluster administrator privileges to perform any backup and restore operations. With OADP self-service, regular users can now safely perform backup and restore operations within namespaces where they have appropriate permissions. -OADP self-service enables regular OpenShift users to perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. Users can: - -- Create and manage backups of their authorized namespaces -- Restore data to their authorized namespaces -- Monitor backup and restore status -- Access relevant logs and descriptions -- Configure their own backup storage locations - -The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. +OADP self-service introduces a significant change to backup and restore operations in OpenShift. Previously, only cluster administrators could perform these operations. +Now, regular OpenShift users can perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. ## Glossary of terms * NAB - Non Admin Backup From 801d0bdff53652d568d14301359e7f87177f2735 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:09:36 -0700 Subject: [PATCH 09/21] update for organizatoin --- .../oadp-self-service.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 3919cdeb..63799916 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -12,29 +12,30 @@ OADP Self Service enables non-administrator users to perform backup and restore - Maintains cluster administrator control over non-administrator operations through templates and policies -### Components - -The self-service functionality is implemented through several custom resources: - -- NonAdminBackup (NAB) - Manages namespace-scoped backup operations -- NonAdminRestore (NAR) - Handles namespace-scoped restore operations -- NonAdminBackupStorageLocation (NABSL) - Defines user-specific backup storage locations -- NonAdminController (NAC) - Controls and orchestrates the self-service operations ## OADP Self Service Details OADP self-service introduces a significant change to backup and restore operations in OpenShift. Previously, only cluster administrators could perform these operations. Now, regular OpenShift users can perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. -## Glossary of terms +### Glossary of terms * NAB - Non Admin Backup * NAR - Non Admin Restore * NAC - Non Admin Controller * NABSL - Non Admin Backup Storage Location * NADR - Non Admin Download Request +### Components + +The self-service functionality is implemented through several custom resources: + +- NonAdminBackup (NAB) - Manages namespace-scoped backup operations +- NonAdminRestore (NAR) - Handles namespace-scoped restore operations +- NonAdminBackupStorageLocation (NABSL) - Defines user-specific backup storage locations +- NonAdminController (NAC) - Controls and orchestrates the self-service operations + -## Cluster Administrator Setup +### Cluster Administrator Setup Install and configure the OADP operator according to the documentation and your requirements. From e18cc636178cf8b21d1cb9b68280e664b1582249 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:26:20 -0700 Subject: [PATCH 10/21] reorg of glossary --- .../oadp-self-service.md | 23 ++++++------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 63799916..0e02a224 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -6,8 +6,8 @@ OADP Self Service enables non-administrator users to perform backup and restore ### Key Benefits -- Allows namespace-scoped backup and restore operations -- Provides secure access to backup logs and status information +- Allows users to perform namespace-scoped backup and restore operations +- Provides users with secure access to backup logs and status information - Enables users to create dedicated backup storage locations - Maintains cluster administrator control over non-administrator operations through templates and policies @@ -19,21 +19,12 @@ OADP self-service introduces a significant change to backup and restore operatio Now, regular OpenShift users can perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. ### Glossary of terms -* NAB - Non Admin Backup -* NAR - Non Admin Restore -* NAC - Non Admin Controller -* NABSL - Non Admin Backup Storage Location -* NADR - Non Admin Download Request - -### Components - -The self-service functionality is implemented through several custom resources: - -- NonAdminBackup (NAB) - Manages namespace-scoped backup operations -- NonAdminRestore (NAR) - Handles namespace-scoped restore operations -- NonAdminBackupStorageLocation (NABSL) - Defines user-specific backup storage locations -- NonAdminController (NAC) - Controls and orchestrates the self-service operations +* **NAB** - NonAdminBackup. A custom resource that users directly create to request a velero backup of the namespace from which the NAB object is created. +* **NAR** - NonAdminRestore. A custom resource that users directly create to request a velero restore of the namespace from which the NAR object is created. +* **NAC** - NonAdminController. A controller that validates the NAB and NAR objects and creates the velero backup and restore objects. The NAC is essentially a proxy between non admin users and velero. +* **NABSL** - NonAdminBackupStorageLocation. A custom resource that users directly create to request a velero backup storage location. Users can use object storage that is specifically created for their project, deliniated from other users and projects. +* **NADR** - NonAdminDownloadRequest. A custom resource that users directly create to request a velero backup download. Users will be provided with a secured URL to download details regarding the backup or restore. ### Cluster Administrator Setup From f22e9e643421f0ecef0469f6064f27c7b714ea28 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:37:11 -0700 Subject: [PATCH 11/21] add details regarding permissions --- .../oadp-self-service.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 0e02a224..4886134f 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -49,6 +49,59 @@ Prior to OpenShift users taking advantage of OADP self-service feature the OpenS * namespace * namespace privileges, e.g. namespace admin. +### OpenShift self-service required permissions: + +Ensure users have appropriate permissions in its namespace. Users must have editor roles for the following objects in their namespace. + * nonadminbackups.oadp.openshift.io + * nonadminbackupstoragelocations.oadp.openshift.io + * nonadminrestores.oadp.openshift.io + + For example + ```yaml + # config/rbac/nonadminbackup_editor_role.yaml + - apiGroups: + - oadp.openshift.io + resources: + - nonadminbackups + - nonadminrestores + - nonadminbackupstoragelocations + verbs: + - create + - delete + - get + - list + - patch + - update + - watch + - apiGroups: + - oadp.openshift.io + resources: + - nonadminbackups/status + verbs: + - get + # config/rbac/nonadminrestore_editor_role.yaml + - apiGroups: + - oadp.openshift.io + resources: + - nonadminrestores + verbs: + - create + - delete + - get + - list + - patch + - update + - watch + - apiGroups: + - oadp.openshift.io + resources: + - nonadminrestores/status + verbs: + - get + ``` + + **note** users will not be able to edit the NABSL's. Users will only be able to create NABSL's. + Non Cluster Administrators can utilize OADP self-service by creating NonAdminBackup (NAB) and NonAdminRestore (NAR) objects in the namespace to be backed up or restored. A NonAdminBackup is an OpenShift custom resource that securely facilitates the creation, status and lifecycle of a Velero Backup custom resource. ```mermaid From 540ca8e8e68882faa0e6c77e26ad67d129340235 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:38:35 -0700 Subject: [PATCH 12/21] nit clarity --- docs/draft_production_docs/oadp-self-service.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 4886134f..5564a41d 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -102,6 +102,8 @@ Ensure users have appropriate permissions in its namespace. Users must have edi **note** users will not be able to edit the NABSL's. Users will only be able to create NABSL's. +## Self-Service workflow + Non Cluster Administrators can utilize OADP self-service by creating NonAdminBackup (NAB) and NonAdminRestore (NAR) objects in the namespace to be backed up or restored. A NonAdminBackup is an OpenShift custom resource that securely facilitates the creation, status and lifecycle of a Velero Backup custom resource. ```mermaid From 6dec1b43de5c6d421fa17f6cba60833a05e62c10 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sun, 23 Feb 2025 15:55:09 -0700 Subject: [PATCH 13/21] add note about openshift console --- .../oadp-self-service.md | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 5564a41d..da132644 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -408,8 +408,18 @@ NonAdminRestores spec fields can also be restricted by the cluster administrator -## TODO -* add a section that describes which backup spec fields can be restricted by the cluster administrator https://github.com/migtools/oadp-non-admin/issues/151 -* Document limited non-admin console use - via - * administrator -> Home -> API Explorer -> Filter on NonAdminBackup or NonAdminRestore -> Instances -> Create NonAdminBackup or NonAdminRestore - \ No newline at end of file +## OpenShift Console and OADP Self-Service + +At the time of writing OADP self-service objects can only be created in the OpenShift Console via the API Explorer. + +Navigate to: Administrator -> Home -> API Explorer -> Filter on `NonAdmin`. Choose the object you wish to create. + + * NonAdminBackup + * NonAdminRestore + * NonAdminBackupStorageLocation + +Click on instances and the create button. + + + + From 52deb7410f867baedba64d2707ee42fef94b1a0b Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Mon, 24 Feb 2025 08:27:34 -0700 Subject: [PATCH 14/21] update on unsupported and security implications --- docs/draft_production_docs/oadp-self-service.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index da132644..a8861516 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -420,6 +420,22 @@ Navigate to: Administrator -> Home -> API Explorer -> Filter on `NonAdmin`. Choo Click on instances and the create button. + +## Unsupported features of OADP regarding self-service + * non-admin VSL's are not supported. The VSL created by the cluster-admin in DPA would be the only VSL non-admin users can employ. + * Resource policy and volume policy is not supported for non-admin user backup and restore operations. + * Backup and restore logs via NonAdminDownloadRequest is not supported for default BSL's. If the cluster administrator would like users to have access to logs, NonAdminBackupStorageLocation's must be created for the non-admin users. + + +## Security Considerations for Cluster Administrators + + * By enabling self-service, cluster administrators will expose the name of the namespace where OADP is running. non-admin users are NOT granted any access to the OADP operator namespace. + + + + + + From ae246ab77c8c350f8f68d0b47f08d985d91de274 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Mon, 24 Feb 2025 09:42:50 -0700 Subject: [PATCH 15/21] add note about cluster scoped resources --- docs/draft_production_docs/oadp-self-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index a8861516..c8737f1b 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -430,7 +430,7 @@ Click on instances and the create button. ## Security Considerations for Cluster Administrators * By enabling self-service, cluster administrators will expose the name of the namespace where OADP is running. non-admin users are NOT granted any access to the OADP operator namespace. - + * The nonadmin controller will not allow users to set includeClusterResources in a backup or restore. This is to prevent a scenario where a non-admin user would attempt to restore a cluster scoped resource to a namespace. OADP's backup policy is to automatically include cluster scoped resources like PV's that are associated with the namespace being backed up. Additionally cluster administrators can template an enforcement to `excludedClusterScopedResources` to prevent cluster scoped resources from being backed up. From 2657e16e56247f3650704426eb84d380d491ec5a Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Tue, 25 Feb 2025 14:53:57 -0700 Subject: [PATCH 16/21] add notes on restricted crd's and other updates --- .../oadp-self-service.md | 197 +++++++++++------- 1 file changed, 117 insertions(+), 80 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index c8737f1b..d8ff158c 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -48,6 +48,7 @@ Prior to OpenShift users taking advantage of OADP self-service feature the OpenS * account * namespace * namespace privileges, e.g. namespace admin. + * optionally the cluster administrator can create a NABSL for the user. ### OpenShift self-service required permissions: @@ -257,6 +258,58 @@ status: ``` The complete nonAdminRestore resource definition can be found here: [NonAdminRestore CRD](https://github.com/openshift/oadp-operator/blob/master/bundle/manifests/oadp.openshift.io_nonadminrestores.yaml) +### NonAdminBackupStorageLocation NABSL: +Cluster administrators can gain efficiencies by delegating backup and restore operations to OpenShift users. It is recommended that cluster administrators carefully manage the NABSL to conform to any company policies, compliance requirements, etc. + +Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. A cluster administrator may also choose to create NABSL's for the non-admin users on the cluster. + +If cluster administrators delegate NABSL creation it is recommended to use the NABSLApprovalRequest object to manage the NABSL's. This will allow the cluster administrator to review and approve the NABSL's before they are used. + +``` + nonAdmin: + enable: true + requireApprovalForBSL: true +``` +Cluster administrators can view the NABSLApprovalRequest object in the openshift-adp namespace. + +``` +oc -n openshift-adp get NonAdminBackupStorageLocationRequests +``` +Approval or rejection is accomplished by updating the NABSLApprovalRequest object. + +``` +spec: + approvalDecision: reject [accept, reject] +``` + +If approved both the NABSL and the BSL are created. The NABSL is created in the users namespace, while the BSL is created in the openshift-adp or default namespace. + +### User Creation of NABSL: + +A non-admin user can create a NABSL in their namespace. + +``` +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackupStorageLocation +metadata: + name: nacuser1-nabsl + namespace: nacuser1 +spec: + backupStorageLocationSpec: + config: + checksumAlgorithm: "" + profile: default + region: us-west-2 + credential: + key: cloud + name: cloud-credentials + objectStorage: + bucket: bucket1uswest2 + prefix: velero + provider: aws +``` + +If the cluster administrator has enabled the requireApprovalForBSL flag then the NABSL will be in the Pending state until the cluster administrator approves the NABSL. @@ -273,51 +326,36 @@ The phase field is a simple one high-level summary of the lifecycle of the objec | Deletion | *NonAdminBackup/NonAdminRestore* resource has been marked for deletion. The NAB/NAR Controller will delete the corresponding Velero *Backup/Restore* if it exists. Once this deletion completes, the *NonAdminBackup/NonAdminRestore* object itself will also be removed | -## Advanced Cluster Administrator Features - -### Restricted NonAdminBackupStorageLocation -Cluster administrators can gain efficiencies by delegating backup and restore operations to OpenShift users. It is recommended that cluster administrators carefully manage the NABSL to conform to any company policies, compliance requirements, etc. There are two ways cluster administrators can manage the NABSL's. -Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. -``` - nonAdmin: - enable: true - requireAdminApprovalForBSL: true -``` - -``` -apiVersion: oadp.openshift.io/v1alpha1 -kind: NABSLApprovalRequest -metadata: - name: nabsl-hash-name - namespace: openshift-adp -spec: - nabslName: nabsl-name - nabslNamespace: nac-user-ns - creationApproved: false # Tracks approval for creation - updateApproved: false # Tracks approval for updates - lastApprovedSpec: {} # Stores last approved NABSL spec -``` - This ensures the cluster administrator has reviewed the NABSL to ensure the correct object storage location options are used. +## Advanced Cluster Administrator Features ### Cluster Administrator Enforceable Spec Fields +There are several types of cluster scoped objects that non-admin users should not have access to backup or restore. OADP self-service automatically excludes the following list of cluster scoped resources from being backed up or restored. + +* SCCs +* ClusterRoles +* ClusterRoleBindings +* CRDs +* PriorityClasses +* virtualmachineclusterinstancetypes +* virtualmachineclusterpreferences Cluster administrators may also enforce company or compliance policy by utilizing templated NABSL's, NAB's and NAR's that require fields values to be set and conform to the administrator defined policy. Admin Enforceable fields are fields that the cluster administrator can enforce non cluster admin users to use. Restricted fields are automatically managed by OADP and cannot be modified by either administrators or users. #### NABSL The following NABSL fields are currently supported for template enforcement: -| **NABSL Field** | **Admin Enforceable** | **Restricted** | -|----------------------------|-----------------|----------------| -| `backupSyncPeriod` | ⚠️ special case | | -| `provider` | ⚠️ special case | | -| `objectStorage` | ✅ Yes | | -| `credential` | ✅ Yes | | -| `config` | ✅ Yes | | -| `accessMode` | ✅ Yes | | -| `validationFrequency` | ✅ Yes | | +| **NABSL Field** | **Admin Enforceable** | **Restricted** | **special case** | +|----------------------------|-----------------|----------------|-----------------| +| `backupSyncPeriod` | | | ⚠️ special case | +| `provider` | | | ⚠️ special case | +| `objectStorage` | ✅ Yes | | | +| `credential` | ✅ Yes | | | +| `config` | ✅ Yes | | | +| `accessMode` | ✅ Yes | | | +| `validationFrequency` | ✅ Yes | | | For example if the cluster administrator wanted to mandate that all NABSL's used a particular aws s3 bucket. @@ -343,32 +381,32 @@ The DPA spec must be set in the following way: TODO GET NABSL ENFORCEMENT EXAMP In the same sense as the NABSL, cluster administrators can also restrict the NonAdminBackup spec fields to ensure the backup request conforms to the administrator defined policy. Most of the backup spec fields can be restricted by the cluster administrator, below is a table of reference for the current implementation. -| **Backup Spec Field** | **Admin Enforceable** | **Restricted** | -|--------------------------------------------|--------------|--------------------------| -| `csiSnapshotTimeout` | ✅ Yes | | -| `itemOperationTimeout` | ✅ Yes | | -| `resourcePolicy` | ✅ Yes | ⚠️ special case | -| `includedNamespaces` | ❌ No | ✅ Yes | -| `excludedNamespaces` | ✅ Yes | ✅ Yes | -| `includedResources` | ✅ Yes | | -| `excludedResources` | ✅ Yes | | -| `orderedResources` | ✅ Yes | | -| `includeClusterResources` | ✅ Yes | ⚠️ special case | -| `excludedClusterScopedResources` | ✅ Yes | | -| `includedClusterScopedResources` | ✅ Yes | ⚠️ special case | -| `excludedNamespaceScopedResources` | ✅ Yes | | -| `includedNamespaceScopedResources` | ✅ Yes | | -| `labelSelector` | ✅ Yes | | -| `orLabelSelectors` | ✅ Yes | | -| `snapshotVolumes` | ✅ Yes | | -| `storageLocation` | ⚠️ special case | | -| `volumeSnapshotLocations` | ⚠️ special case | | -| `ttl` | ✅ Yes | | -| `defaultVolumesToFsBackup` | ✅ Yes | | -| `snapshotMoveData` | ✅ Yes | | -| `datamover` | ✅ Yes | | -| `uploaderConfig.parallelFilesUpload` | ✅ Yes | | -| `hooks` | ⚠️ special case | | +| **Backup Spec Field** | **Admin Enforceable** | **Restricted** | **special case** | +|--------------------------------------------|--------------|--------------------------|-----------------| +| `csiSnapshotTimeout` | ✅ Yes | | | +| `itemOperationTimeout` | ✅ Yes | | | +| `resourcePolicy` | ✅ Yes | | ⚠️ special case | +| `includedNamespaces` | ❌ No | ✅ Yes | | +| `excludedNamespaces` | ✅ Yes | ✅ Yes | | +| `includedResources` | ✅ Yes | | | +| `excludedResources` | ✅ Yes | | | +| `orderedResources` | ✅ Yes | | | +| `includeClusterResources` | ✅ Yes | | ⚠️ special case | +| `excludedClusterScopedResources` | ✅ Yes | | | +| `includedClusterScopedResources` | ✅ Yes | | ⚠️ special case | +| `excludedNamespaceScopedResources` | ✅ Yes | | | +| `includedNamespaceScopedResources` | ✅ Yes | | | +| `labelSelector` | ✅ Yes | | | +| `orLabelSelectors` | ✅ Yes | | | +| `snapshotVolumes` | ✅ Yes | | | +| `storageLocation` | | | ⚠️ special case | +| `volumeSnapshotLocations` | | | ⚠️ special case | +| `ttl` | ✅ Yes | | | +| `defaultVolumesToFsBackup` | ✅ Yes | | | +| `snapshotMoveData` | ✅ Yes | | | +| `datamover` | ✅ Yes | | | +| `uploaderConfig.parallelFilesUpload` | ✅ Yes | | | +| `hooks` | | | ⚠️ special case | An example enforcement set in the DPA spec to enforce the * ttl to be set to "158h0m0s" @@ -385,26 +423,25 @@ An example enforcement set in the DPA spec to enforce the NonAdminRestores spec fields can also be restricted by the cluster administrator. The following NAR spec fields are currently supported for template enforcement: -| **Field** | **Admin Enforceable** | **Restricted** | -|-------------------------------|--------------|--------------------| -| `backupName` | ❌ No | | -| `scheduleName` | ❌ No | ✅ Yes | -| `itemOperationTimeout` | ✅ Yes | | -| `uploaderConfig` | ✅ Yes | | -| `includedNamespaces` | ❌ No | ✅ Yes | -| `excludedNamespaces` | ❌ No | ✅ Yes | -| `includedResources` | ✅ Yes | | -| `excludedResources` | ✅ Yes | | -| `restoreStatus` | ✅ Yes | | -| `includeClusterResources` | ✅ Yes | | -| `labelSelector` | ✅ Yes | | -| `orLabelSelectors` | ✅ Yes | | -| `namespaceMapping` | ❌ No | ✅ Yes | -| `restorePVs` | ✅ Yes | | -| `preserveNodePorts` | ✅ Yes | | -| `existingResourcePolicy` | ✅ Yes | | -| `resourceModifier` | ⚠️ special case | | -| `hooks` | ⚠️ special case | | +| **Field** | **Admin Enforceable** | **Restricted** | **special case** | +|-------------------------------|--------------|--------------------|-----------------| +| `backupName` | ❌ No | | | +| `scheduleName` | ❌ No | ✅ Yes | | +| `itemOperationTimeout` | ✅ Yes | | | +| `uploaderConfig` | ✅ Yes | | | +| `includedNamespaces` | ❌ No | ✅ Yes | | +| `excludedNamespaces` | ❌ No | ✅ Yes | | +| `includedResources` | ✅ Yes | | | +| `excludedResources` | ✅ Yes | | | +| `restoreStatus` | ✅ Yes | | | +| `includeClusterResources` | ✅ Yes | | | +| `labelSelector` | ✅ Yes | | | +| `orLabelSelectors` | ✅ Yes | | | +| `namespaceMapping` | ❌ No | ✅ Yes | | +| `restorePVs` | ✅ Yes | | | +| `preserveNodePorts` | ✅ Yes | | | +| `existingResourcePolicy` | | | ⚠️ special case | +| `hooks` | | | ⚠️ special case | From 5fba4f13bcc57d8ae8443ad29db316371e5405fe Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Tue, 25 Feb 2025 15:06:50 -0700 Subject: [PATCH 17/21] clean up nabsl workflow --- docs/draft_production_docs/oadp-self-service.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index d8ff158c..a52e05ca 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -261,10 +261,15 @@ The complete nonAdminRestore resource definition can be found here: [NonAdminRes ### NonAdminBackupStorageLocation NABSL: Cluster administrators can gain efficiencies by delegating backup and restore operations to OpenShift users. It is recommended that cluster administrators carefully manage the NABSL to conform to any company policies, compliance requirements, etc. -Cluster administrators can optionally set an approval policy for any NABSL. This policy will require that any NABSL be approved by the cluster administrator before it can be used. A cluster administrator may also choose to create NABSL's for the non-admin users on the cluster. +1. **Direct Creation**: Cluster administrators can create NABSLs directly for non-admin users. +2. **Approval Workflow**: Cluster administrators can enable an approval process where: + - Users create NABSL's from the user namespace, this creates a NABSLApprovalRequest object in the openshift-adp namespace. + - Administrators review and approve/reject these requests in the openshift-adp namespace. Upon approval the NABSL is created in the users namespace. +3. **Automatic Approval**: Users create NABSL from the user namespace, these are automatically approved. -If cluster administrators delegate NABSL creation it is recommended to use the NABSLApprovalRequest object to manage the NABSL's. This will allow the cluster administrator to review and approve the NABSL's before they are used. +For security purposes it is recommended that cluster administrators use either the direct creation or the approval workflow. The automatic approval option is less secure as it does not require administrator review. +To enable the approval workflow the DPA spec must be set as follows: ``` nonAdmin: enable: true From 91141ed931fe8c2546899ac8a93914bf4f10a402 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Tue, 25 Feb 2025 15:10:44 -0700 Subject: [PATCH 18/21] update unsupported bits --- docs/draft_production_docs/oadp-self-service.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index a52e05ca..e9bd7998 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -464,6 +464,7 @@ Click on instances and the create button. ## Unsupported features of OADP regarding self-service + * Cross Cluster or Migrations are NOT supported by self-service. This type of OADP operation is only supported for the cluster administrator. * non-admin VSL's are not supported. The VSL created by the cluster-admin in DPA would be the only VSL non-admin users can employ. * Resource policy and volume policy is not supported for non-admin user backup and restore operations. * Backup and restore logs via NonAdminDownloadRequest is not supported for default BSL's. If the cluster administrator would like users to have access to logs, NonAdminBackupStorageLocation's must be created for the non-admin users. @@ -471,7 +472,7 @@ Click on instances and the create button. ## Security Considerations for Cluster Administrators - * By enabling self-service, cluster administrators will expose the name of the namespace where OADP is running. non-admin users are NOT granted any access to the OADP operator namespace. + * By enabling self-service, cluster administrators will expose the name of the namespace where OADP is running via the backup logs. non-admin users are NOT granted any access to the OADP operator namespace. * The nonadmin controller will not allow users to set includeClusterResources in a backup or restore. This is to prevent a scenario where a non-admin user would attempt to restore a cluster scoped resource to a namespace. OADP's backup policy is to automatically include cluster scoped resources like PV's that are associated with the namespace being backed up. Additionally cluster administrators can template an enforcement to `excludedClusterScopedResources` to prevent cluster scoped resources from being backed up. From b9206d7461e9bc31cf59cfae0c87cc4eec098340 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Sat, 1 Mar 2025 18:21:46 -0700 Subject: [PATCH 19/21] updates from review --- .../oadp-self-service.md | 77 ++++++++++++------- 1 file changed, 49 insertions(+), 28 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index e9bd7998..49720fe1 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -22,7 +22,7 @@ Now, regular OpenShift users can perform backup and restore operations within th * **NAB** - NonAdminBackup. A custom resource that users directly create to request a velero backup of the namespace from which the NAB object is created. * **NAR** - NonAdminRestore. A custom resource that users directly create to request a velero restore of the namespace from which the NAR object is created. -* **NAC** - NonAdminController. A controller that validates the NAB and NAR objects and creates the velero backup and restore objects. The NAC is essentially a proxy between non admin users and velero. +* **NAC** - NonAdminController. A controller that validates the NAB and NAR objects and creates the velero backup and restore and related objects. The NAC is essentially a proxy between non admin users and velero. * **NABSL** - NonAdminBackupStorageLocation. A custom resource that users directly create to request a velero backup storage location. Users can use object storage that is specifically created for their project, deliniated from other users and projects. * **NADR** - NonAdminDownloadRequest. A custom resource that users directly create to request a velero backup download. Users will be provided with a secured URL to download details regarding the backup or restore. @@ -37,7 +37,7 @@ To enable OADP Self-Service the DPA spec must the spec.nonAdmin.enable field to enable: true ``` -Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. The Openshift users without cluster admin rights will now be able to create NAB or NAR objects in their namespace to create a backup or restore. +Once the OADP DPA is reconciled the cluster administrator should see the non-admin-controller running in the openshift-adp namespace. The Openshift users without cluster admin rights will now be able to create NAB or NAR objects and related objects in their namespace to create a backup or restore. ## OpenShift User Instructions @@ -55,7 +55,8 @@ Prior to OpenShift users taking advantage of OADP self-service feature the OpenS Ensure users have appropriate permissions in its namespace. Users must have editor roles for the following objects in their namespace. * nonadminbackups.oadp.openshift.io * nonadminbackupstoragelocations.oadp.openshift.io - * nonadminrestores.oadp.openshift.io + * nonadminrestores.oadp.openshift.io + * nonadmindownloadrequests.oadp.openshift.io For example ```yaml @@ -101,7 +102,7 @@ Ensure users have appropriate permissions in its namespace. Users must have edi - get ``` - **note** users will not be able to edit the NABSL's. Users will only be able to create NABSL's. + **note** Users will not be able to edit the NABSLs that led to the creation of the BSL. They will only have the ability to create new NABSLs. The NAC controller will disallow such edit and inform user within the condition of the edited NABSL object. ## Self-Service workflow @@ -154,7 +155,7 @@ metadata: - nonadminbackup.oadp.openshift.io/finalizer generation: 2 name: mybackup-1 - namespace: nacuser1 <--- The namespace is set by the NAC controller + namespace: nacuser1 <--- The namespace that NAC controller will set on the Velero Backup object to backup resourceVersion: "20714121" uid: 93effb39-9762-4d04-8e9e-194ebe6b9b31 spec: @@ -205,7 +206,7 @@ metadata: namespace: nacuser1 spec: restoreSpec: - backupName: mybackup-1 + backupName: mybackup-1 <-- references the NAB object, not the Velero backup object ``` Once created the NAR will look similar to the following: @@ -263,11 +264,14 @@ Cluster administrators can gain efficiencies by delegating backup and restore op 1. **Direct Creation**: Cluster administrators can create NABSLs directly for non-admin users. 2. **Approval Workflow**: Cluster administrators can enable an approval process where: - - Users create NABSL's from the user namespace, this creates a NABSLApprovalRequest object in the openshift-adp namespace. - - Administrators review and approve/reject these requests in the openshift-adp namespace. Upon approval the NABSL is created in the users namespace. -3. **Automatic Approval**: Users create NABSL from the user namespace, these are automatically approved. + - Users create a NABSL, which triggers the creation of a NonAdminBackupStorageLocationRequest object in the openshift-adp namespace. + - Administrators review and either approve or reject these requests. Once approved, a Velero BSL is created in the openshift-adp namespace, and the user is notified of the approval on the NABSL status. If rejected, the status of the NABSL is updated to reflect the rejection. + - Administrators can also revoke previously approved NABSL, which results in the removal of the Velero BSL, and the user is notified of the rejection. This is achieved by modifying the approve field back to pending or reject. + - This is an opt-in feature and must be explicitly enabled by the cluster administrator. +3. **Automatic Approval**: Users create NABSL from the user namespace, these are automatically approved when nonAdmin.requireApprovalForBSL is set to false or not set. + +For security purposes it is recommended that cluster administrators use either the direct creation or the approval workflow. The automatic approval option is less secure as it does not require administrator review. It should also be noted that updating the NABSL after the initial creation will NOT change the associated Velero BSL. Updating the NABSL is not supported for non-admin users. -For security purposes it is recommended that cluster administrators use either the direct creation or the approval workflow. The automatic approval option is less secure as it does not require administrator review. To enable the approval workflow the DPA spec must be set as follows: ``` @@ -287,7 +291,7 @@ spec: approvalDecision: reject [accept, reject] ``` -If approved both the NABSL and the BSL are created. The NABSL is created in the users namespace, while the BSL is created in the openshift-adp or default namespace. +If approved both the NABSL and the BSL are created. The NABSL is created in the users namespace, while the BSL is created in the OADP namespace, such as openshift-adp. ### User Creation of NABSL: @@ -354,13 +358,14 @@ The following NABSL fields are currently supported for template enforcement: | **NABSL Field** | **Admin Enforceable** | **Restricted** | **special case** | |----------------------------|-----------------|----------------|-----------------| -| `backupSyncPeriod` | | | ⚠️ special case | +| `backupSyncPeriod` | | | ⚠️ Must be set lower than the DPA.backupSyncPeriod and lower than the garbage collection period | | `provider` | | | ⚠️ special case | | `objectStorage` | ✅ Yes | | | | `credential` | ✅ Yes | | | | `config` | ✅ Yes | | | | `accessMode` | ✅ Yes | | | | `validationFrequency` | ✅ Yes | | | +| `default` | | | ⚠️ Must be false or empty | For example if the cluster administrator wanted to mandate that all NABSL's used a particular aws s3 bucket. @@ -373,13 +378,26 @@ spec: credential: key: cloud name: cloud-credentials - default: true objectStorage: bucket: my-company-bucket <--- prefix: velero provider: aws ``` -The DPA spec must be set in the following way: TODO GET NABSL ENFORCEMENT EXAMPLE +The DPA spec must be set in the following way: + +``` +nonAdmin: + enable: true + enforceBSLSpec: + config: <--- entire config must match expected NaBSL config + checksumAlgorithm: "" + profile: default + region: us-west-2 + objectStorage: <--- all of the objectStorage options must match expected NaBSL options + bucket: my-company-bucket + prefix: velero + provider: aws +``` #### Restricted NonAdminBackups @@ -390,22 +408,22 @@ In the same sense as the NABSL, cluster administrators can also restrict the Non |--------------------------------------------|--------------|--------------------------|-----------------| | `csiSnapshotTimeout` | ✅ Yes | | | | `itemOperationTimeout` | ✅ Yes | | | -| `resourcePolicy` | ✅ Yes | | ⚠️ special case | -| `includedNamespaces` | ❌ No | ✅ Yes | | -| `excludedNamespaces` | ✅ Yes | ✅ Yes | | +| `resourcePolicy` | ✅ Yes | | ⚠️ Non-admin users can specify the config-map that admins created in OADP Operator NS(Admins enforcing this value be a good alternative here), they cannot specify their own configmap as its lifecycle handling is not currently managed by NAC controller | +| `includedNamespaces` | ❌ No | ✅ Yes | ⚠️ Admins cannot enforce this because it does not make sense for a cluster wide non-admin backup setting, we have validations in place such that only the NS admins NS in included in the NAB spec. | +| `excludedNamespaces` | ✅ Yes | ✅ Yes | ⚠️ This spec is restricted for non-admin users and hence not enforceable by admins | | `includedResources` | ✅ Yes | | | | `excludedResources` | ✅ Yes | | | | `orderedResources` | ✅ Yes | | | -| `includeClusterResources` | ✅ Yes | | ⚠️ special case | +| `includeClusterResources` | ✅ Yes | | ⚠️ Non-admin users can only set this spec to false if they want, all other values are restricted, similar rule for admin enforcement regarding this spec value. | | `excludedClusterScopedResources` | ✅ Yes | | | -| `includedClusterScopedResources` | ✅ Yes | | ⚠️ special case | +| `includedClusterScopedResources` | ✅ Yes | | ⚠️ This spec is restricted and non-enforceable, only empty list is acceptable | | `excludedNamespaceScopedResources` | ✅ Yes | | | | `includedNamespaceScopedResources` | ✅ Yes | | | | `labelSelector` | ✅ Yes | | | | `orLabelSelectors` | ✅ Yes | | | | `snapshotVolumes` | ✅ Yes | | | -| `storageLocation` | | | ⚠️ special case | -| `volumeSnapshotLocations` | | | ⚠️ special case | +| `storageLocation` | | | ⚠️ Can be empty (implying default BSL usage) or needs to be an existing NABSL | +| `volumeSnapshotLocations` | | | ⚠️ Not supported for non-admin users, default will be used if needed | | `ttl` | ✅ Yes | | | | `defaultVolumesToFsBackup` | ✅ Yes | | | | `snapshotMoveData` | ✅ Yes | | | @@ -431,22 +449,23 @@ NonAdminRestores spec fields can also be restricted by the cluster administrator | **Field** | **Admin Enforceable** | **Restricted** | **special case** | |-------------------------------|--------------|--------------------|-----------------| | `backupName` | ❌ No | | | -| `scheduleName` | ❌ No | ✅ Yes | | +| `scheduleName` | ❌ No | ✅ Yes | ⚠️ not supported for non-admin users, we don't have non-admin backup schedule API as of now. | | `itemOperationTimeout` | ✅ Yes | | | | `uploaderConfig` | ✅ Yes | | | -| `includedNamespaces` | ❌ No | ✅ Yes | | -| `excludedNamespaces` | ❌ No | ✅ Yes | | -| `includedResources` | ✅ Yes | | | +| `includedNamespaces` | ❌ No | ✅ Yes | ⚠️ restricted for non-admin users and hence non-enforceable by admins | +| `excludedNamespaces` | ❌ No | ✅ Yes | ⚠️ restricted for non-admin users and hence non-enforceable by admins | +| `includedResources` | ✅ Yes | | | | `excludedResources` | ✅ Yes | | | | `restoreStatus` | ✅ Yes | | | | `includeClusterResources` | ✅ Yes | | | | `labelSelector` | ✅ Yes | | | | `orLabelSelectors` | ✅ Yes | | | -| `namespaceMapping` | ❌ No | ✅ Yes | | +| `namespaceMapping` | ❌ No | ✅ Yes | ⚠️ restricted for non-admin users and hence non-enforceable by admins | | `restorePVs` | ✅ Yes | | | | `preserveNodePorts` | ✅ Yes | | | | `existingResourcePolicy` | | | ⚠️ special case | | `hooks` | | | ⚠️ special case | +| `resourceModifers` | | | ⚠️ Non-admin users can specify the config-map that admins created in OADP Operator NS(Admins enforcing this value be a good alternative here), they cannot specify their own configmap as its lifecycle handling is not currently managed by NAC controller | @@ -459,6 +478,7 @@ Navigate to: Administrator -> Home -> API Explorer -> Filter on `NonAdmin`. Choo * NonAdminBackup * NonAdminRestore * NonAdminBackupStorageLocation + * NonAdminDownloadRequest Click on instances and the create button. @@ -466,8 +486,9 @@ Click on instances and the create button. ## Unsupported features of OADP regarding self-service * Cross Cluster or Migrations are NOT supported by self-service. This type of OADP operation is only supported for the cluster administrator. * non-admin VSL's are not supported. The VSL created by the cluster-admin in DPA would be the only VSL non-admin users can employ. - * Resource policy and volume policy is not supported for non-admin user backup and restore operations. - * Backup and restore logs via NonAdminDownloadRequest is not supported for default BSL's. If the cluster administrator would like users to have access to logs, NonAdminBackupStorageLocation's must be created for the non-admin users. + * ResourceModifiers and Volume policies are not supported for non-admin user backup and restore operations. + * Backup and restore logs via NonAdminDownloadRequest is not supported for default BSL's. If the cluster administrator would + like users to have access to logs, NonAdminBackupStorageLocation's must be created for the non-admin users. ## Security Considerations for Cluster Administrators From 92d56d263ceb04fe6211b1d674cd7e0c04699296 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Mon, 3 Mar 2025 12:04:30 -0700 Subject: [PATCH 20/21] update from shubham's review --- docs/draft_production_docs/oadp-self-service.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 49720fe1..98402778 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -2,21 +2,26 @@ ## Overview -OADP Self Service enables non-administrator users to perform backup and restore operations in their authorized namespaces without requiring cluster-wide administrator privileges. This feature provides secure self-service data protection capabilities while maintaining proper access controls. +OADP Self Service enables non-administrator users to perform backup and restore operations in their authorized namespaces without requiring +cluster-wide administrator privileges. This feature provides secure self-service data protection capabilities while maintaining proper administrator +controls, restrictions and enforcements over the user's backup and restore operations. ### Key Benefits - Allows users to perform namespace-scoped backup and restore operations - Provides users with secure access to backup logs and status information -- Enables users to create dedicated backup storage locations +- Enables users to create dedicated backup storage locations with user owned buckets and credentials - Maintains cluster administrator control over non-administrator operations through -templates and policies +restrictions and enforcements ## OADP Self Service Details OADP self-service introduces a significant change to backup and restore operations in OpenShift. Previously, only cluster administrators could perform these operations. -Now, regular OpenShift users can perform backup and restore operations within their authorized namespaces. This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, while cluster administrators maintain overall control through templates and policies. +Now, regular OpenShift users can perform backup and restore operations within their authorized namespaces. +This is achieved through custom resources that securely manage these operations while maintaining proper access controls and visibility. +The self-service functionality is implemented in a way that ensures users can only operate within their assigned namespaces and permissions, +while cluster administrators maintain overall control through restrictions and enforcements. ### Glossary of terms From 8a0600cf9dc4944cf1aa3886e61010d0d92d3822 Mon Sep 17 00:00:00 2001 From: Wesley Hayutin Date: Mon, 3 Mar 2025 12:07:32 -0700 Subject: [PATCH 21/21] fix permissions spec --- docs/draft_production_docs/oadp-self-service.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/draft_production_docs/oadp-self-service.md b/docs/draft_production_docs/oadp-self-service.md index 98402778..8279b6b2 100644 --- a/docs/draft_production_docs/oadp-self-service.md +++ b/docs/draft_production_docs/oadp-self-service.md @@ -72,6 +72,7 @@ Ensure users have appropriate permissions in its namespace. Users must have edi - nonadminbackups - nonadminrestores - nonadminbackupstoragelocations + - nonadmindownloadrequests verbs: - create - delete