A working draft of self-service docs for the OADP docs team #234

weshayutin · 2025-02-25T22:14:40Z

Why the changes were made

First pass at draft documentation that may or may not exist in the oadp-non-admin git repo in the long term. The purpose of this draft to get a working draft into the hands of the docs team, qe and others ASAP.

How to test the changes made

Just read :)

https://github.com/weshayutin/oadp-non-admin/blob/draft_docs/docs/draft_production_docs/oadp-self-service.md

https://github.com/weshayutin/oadp-non-admin/blob/draft_docs/docs/draft_production_docs/sequenceDiagram.md

openshift-ci · 2025-02-25T22:14:47Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: weshayutin
Once this PR has been reviewed and has the lgtm label, please assign mrnold for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

docs/draft_production_docs/oadp-self-service.md

shubham-pampattiwar · 2025-02-28T17:37:35Z

docs/draft_production_docs/oadp-self-service.md

+## 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.


(Namespace Admin users)

@shubham-pampattiwar so a regular user w/ the appropriate rbac could create nabs/nars right? I'm a little hesitant to doc "namespace admin". Yes namespace admin will work, but other combinations would as well iiuc.

docs/draft_production_docs/oadp-self-service.md

shubham-pampattiwar

@weshayutin Please refer the tables and special case notes from #151 (comment)
Thank you !

mateusoliveira43 · 2025-03-05T19:27:35Z

docs/draft_production_docs/sequenceDiagram.md

should it be like this?

i.e. When velero backup status updates, NAC sees it and updates NAB status

the way it it can it pass wrong message that velero updates NAB?

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-->>NAC: Status updates NAC-->>NAB: updates status NAB-->>User: View backup status

Loading

mateusoliveira43 · 2025-03-05T20:19:09Z

docs/draft_production_docs/oadp-self-service.md

+| `itemOperationTimeout`                     | ✅ 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                |


Admin Enforceable ❌ no. Ref https://github.com/openshift/oadp-operator/blob/14827fa839dce3ef68dbe63970588dfcf66d1aca/internal/controller/validator.go#L216

mateusoliveira43 · 2025-03-05T20:20:17Z

docs/draft_production_docs/oadp-self-service.md

+| `csiSnapshotTimeout`                       | ✅ Yes       |                          |                 |
+| `itemOperationTimeout`                     | ✅ 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.                 |


special case column should be empty here?

mateusoliveira43 · 2025-03-05T20:22:27Z

docs/draft_production_docs/oadp-self-service.md

+| `orLabelSelectors`                         | ✅ Yes       |                          |                 |
+| `snapshotVolumes`                          | ✅ Yes       |                          |                 |
+| `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 |


Admin Enforceable ❌ no. Ref https://github.com/openshift/oadp-operator/blob/14827fa839dce3ef68dbe63970588dfcf66d1aca/internal/controller/validator.go#L208

Should have Restricted column Yes?

oadp-non-admin/internal/common/function/function.go

Line 153 in af1bbcd

if nonAdminBackup.Spec.BackupSpec.VolumeSnapshotLocations != nil {

mateusoliveira43 · 2025-03-05T20:23:12Z

docs/draft_production_docs/oadp-self-service.md

+| `labelSelector`                            | ✅ Yes       |                          |                 |
+| `orLabelSelectors`                         | ✅ Yes       |                          |                 |
+| `snapshotVolumes`                          | ✅ Yes       |                          |                 |
+| `storageLocation`                          |              |                          | ⚠️ Can be empty (implying default BSL usage) or needs to be an existing NABSL |


Admin Enforceable ❌ no. Ref https://github.com/openshift/oadp-operator/blob/14827fa839dce3ef68dbe63970588dfcf66d1aca/internal/controller/validator.go#L204

mateusoliveira43 · 2025-03-05T20:26:47Z

docs/draft_production_docs/oadp-self-service.md

+
+| **NABSL Field**            | **Admin Enforceable** | **Restricted** | **special case** |
+|----------------------------|-----------------|----------------|-----------------|
+| `backupSyncPeriod`         |                 |                | ⚠️ Must be set lower than the DPA.backupSyncPeriod and lower than the garbage collection period |


Must be set lower than the DPA spec.nonAdmin.backupSyncPeriod

mateusoliveira43 · 2025-03-05T20:31:09Z

docs/draft_production_docs/oadp-self-service.md

+| `includedResources`                        | ✅ Yes       |                          |                 |
+| `excludedResources`                        | ✅ Yes       |                          |                 |
+| `orderedResources`                         | ✅ Yes       |                          |                 |
+| `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.  |


should have Restricted column Yes?

oadp-non-admin/internal/common/function/function.go

Line 118 in af1bbcd

if nonAdminBackup.Spec.BackupSpec.IncludeClusterResources != nil && *nonAdminBackup.Spec.BackupSpec.IncludeClusterResources {

mateusoliveira43 · 2025-03-05T20:31:37Z

docs/draft_production_docs/oadp-self-service.md

+| `orderedResources`                         | ✅ Yes       |                          |                 |
+| `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       |                          | ⚠️ This spec is restricted and non-enforceable, only empty list is acceptable  |


Should have Restricted column Yes?

oadp-non-admin/internal/common/function/function.go

Line 122 in af1bbcd

if len(nonAdminBackup.Spec.BackupSpec.IncludedClusterScopedResources) > 0 {

kaovilai

https://github.com/migtools/oadp-non-admin/blob/master/internal/controller/nonadmindownloadrequest_controller.go is missing from this branch.. although no conflict, a rebase would be appreciated

kaovilai · 2025-04-17T07:09:25Z

docs/draft_production_docs/oadp-self-service.md

+      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)
+


Here's doc for NADR

Suggested change

### Troubleshooting with NonAdminDownloadRequest (NADR)

NonAdminDownloadRequest (NADR) provides non-admin users with a way to access detailed information about their backups and restores for troubleshooting purposes. This functionality is equivalent to what cluster administrators can access using the `velero backup describe --details` command.

NADR allows users to securely retrieve various types of information that can help diagnose issues with backup and restore operations. The NADR controller validates the request and creates a secure download URL for users to access the requested information.

#### Using NADR for Backup Troubleshooting

The following example shows how to create a NADR object to retrieve detailed information about a backup:

```yaml

apiVersion: oadp.openshift.io/v1alpha1

kind: NonAdminDownloadRequest

metadata:

name: backup-details

namespace: nacuser1

spec:

target:

kind: BackupResourceList # See other kinds below

name: mybackup-1 # The name of your NAB

```

Once processed, the NADR status will contain a secure URL where you can download the requested information:

```yaml

apiVersion: oadp.openshift.io/v1alpha1

kind: NonAdminDownloadRequest

metadata:

name: backup-details

namespace: nacuser1

spec:

target:

kind: BackupResourceList

name: mybackup-1

status:

phase: Processed

velero:

status:

downloadURL: https://storage-url.example.com/path-to-your-download?signed-token

expiration: "2025-03-23T20:57:35Z"

phase: Processed

```

#### Available Information Types

The NADR resource supports retrieving different kinds of information:

| Target Kind | Description | Equivalent to |

|-------------|-------------|--------------|

| `BackupResourceList` | List of resources included in the backup | `velero backup describe --details` (resource listing) |

| `BackupContents` | Contents of files backed up | Part of backup details |

| `BackupLog` | Logs from the backup operation | `velero backup logs` |

| `BackupVolumeSnapshots` | Information about volume snapshots | `velero backup describe --details` (snapshots section) |

| `BackupItemOperations` | Information about item operations performed during backup | `velero backup describe --details` (operations section) |

| `RestoreLog` | Logs from the restore operation | `velero restore logs` |

| `RestoreResults` | Detailed results of the restore | `velero restore describe --details` |

#### Troubleshooting Example Workflow

1. **Create a backup**

```

oc create -f nab.yaml

```

2. **Check if the backup completed successfully**

```

oc get nonadminbackup mybackup-1 -n nacuser1

```

3. **If issues are detected, create a NADR to get more details**

```

oc create -f nadr-backup-details.yaml

```

4. **Wait for the NADR to be processed and get the download URL**

```

oc get nonadmindownloadrequest backup-details -n nacuser1 -o jsonpath='{.status.velero.status.downloadURL}'

```

5. **Download and analyze the information using the URL**

This workflow provides non-admin users the ability to troubleshoot their backup operations with the same level of detail that cluster administrators can access with the `velero backup describe --details` command.

> **Note:** Backup and restore logs via NonAdminDownloadRequest are not supported for default BSLs. If you need access to logs, ask your cluster administrator to create a NonAdminBackupStorageLocation for your namespace.

weshayutin added 18 commits February 7, 2025 14:16

draft of docs for doc team

36b3f48

update enforcements

dd5d702

nit

55a99d2

nit

002ac63

add examples

a5be845

add nab and nar example

1095581

link to restore crd def

cdb6c48

update for clarity

78ae082

update for organizatoin

801d0bd

reorg of glossary

e18cc63

add details regarding permissions

f22e9e6

nit clarity

540ca8e

add note about openshift console

6dec1b4

update on unsupported and security implications

52deb74

add note about cluster scoped resources

ae246ab

add notes on restricted crd's and other updates

2657e16

clean up nabsl workflow

5fba4f1

update unsupported bits

91141ed

openshift-ci bot requested review from mpryc and shubham-pampattiwar February 25, 2025 22:14

weshayutin changed the title ~~Draft docs~~ A working draft of self-service docs for the OADP docs team Feb 25, 2025

mateusoliveira43 reviewed Feb 26, 2025

View reviewed changes

docs/draft_production_docs/oadp-self-service.md Outdated Show resolved Hide resolved

mateusoliveira43 reviewed Feb 26, 2025

View reviewed changes

docs/draft_production_docs/oadp-self-service.md Show resolved Hide resolved

mpryc requested changes Feb 27, 2025

View reviewed changes

shubham-pampattiwar reviewed Feb 28, 2025

View reviewed changes

weshayutin added 3 commits March 1, 2025 18:21

updates from review

b9206d7

update from shubham's review

92d56d2

fix permissions spec

8a0600c

mateusoliveira43 reviewed Mar 5, 2025

View reviewed changes

kaovilai reviewed Apr 17, 2025

View reviewed changes

kaovilai requested changes Apr 17, 2025

View reviewed changes

kaovilai mentioned this pull request Apr 17, 2025

OADP-4001 Self-Service openshift/openshift-docs#89043

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A working draft of self-service docs for the OADP docs team #234

A working draft of self-service docs for the OADP docs team #234

weshayutin commented Feb 25, 2025 •

edited by mateusoliveira43

Loading

openshift-ci bot commented Feb 25, 2025

shubham-pampattiwar Feb 28, 2025

weshayutin Mar 3, 2025

shubham-pampattiwar left a comment

mateusoliveira43 Mar 5, 2025

kaovilai Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

mateusoliveira43 Mar 5, 2025

kaovilai left a comment

kaovilai Apr 17, 2025

+### Troubleshooting with NonAdminDownloadRequest (NADR)
+NonAdminDownloadRequest (NADR) provides non-admin users with a way to access detailed information about their backups and restores for troubleshooting purposes. This functionality is equivalent to what cluster administrators can access using the `velero backup describe --details` command.
+NADR allows users to securely retrieve various types of information that can help diagnose issues with backup and restore operations. The NADR controller validates the request and creates a secure download URL for users to access the requested information.
+#### Using NADR for Backup Troubleshooting
+The following example shows how to create a NADR object to retrieve detailed information about a backup:
+```yaml
+apiVersion: oadp.openshift.io/v1alpha1
+kind: NonAdminDownloadRequest
+metadata:
+  name: backup-details
+  namespace: nacuser1
+spec:
+  target:
+    kind: BackupResourceList  # See other kinds below
+    name: mybackup-1  # The name of your NAB
+```
+Once processed, the NADR status will contain a secure URL where you can download the requested information:
+```yaml
+apiVersion: oadp.openshift.io/v1alpha1
+kind: NonAdminDownloadRequest
+metadata:
+  name: backup-details
+  namespace: nacuser1
+spec:
+  target:
+    kind: BackupResourceList
+    name: mybackup-1
+status:
+  phase: Processed
+  velero:
+    status:
+      downloadURL: https://storage-url.example.com/path-to-your-download?signed-token
+      expiration: "2025-03-23T20:57:35Z"
+      phase: Processed
+```
+#### Available Information Types
+The NADR resource supports retrieving different kinds of information:
+| Target Kind | Description | Equivalent to |
+|-------------|-------------|--------------|
+| `BackupResourceList` | List of resources included in the backup | `velero backup describe --details` (resource listing) |
+| `BackupContents` | Contents of files backed up | Part of backup details |
+| `BackupLog` | Logs from the backup operation | `velero backup logs` |
+| `BackupVolumeSnapshots` | Information about volume snapshots | `velero backup describe --details` (snapshots section) |
+| `BackupItemOperations` | Information about item operations performed during backup | `velero backup describe --details` (operations section) |
+| `RestoreLog` | Logs from the restore operation | `velero restore logs` |
+| `RestoreResults` | Detailed results of the restore | `velero restore describe --details` |
+#### Troubleshooting Example Workflow
+. **Create a backup**
+   ```
+   oc create -f nab.yaml
+   ```
+. **Check if the backup completed successfully**
+   ```
+   oc get nonadminbackup mybackup-1 -n nacuser1
+   ```
+. **If issues are detected, create a NADR to get more details**
+   ```
+   oc create -f nadr-backup-details.yaml
+   ```
+. **Wait for the NADR to be processed and get the download URL**
+   ```
+   oc get nonadmindownloadrequest backup-details -n nacuser1 -o jsonpath='{.status.velero.status.downloadURL}'
+   ```
+. **Download and analyze the information using the URL**
+This workflow provides non-admin users the ability to troubleshoot their backup operations with the same level of detail that cluster administrators can access with the `velero backup describe --details` command.
+> **Note:** Backup and restore logs via NonAdminDownloadRequest are not supported for default BSLs. If you need access to logs, ask your cluster administrator to create a NonAdminBackupStorageLocation for your namespace.

A working draft of self-service docs for the OADP docs team #234

Are you sure you want to change the base?

A working draft of self-service docs for the OADP docs team #234

Conversation

weshayutin commented Feb 25, 2025 • edited by mateusoliveira43 Loading

Why the changes were made

How to test the changes made

openshift-ci bot commented Feb 25, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shubham-pampattiwar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaovilai left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weshayutin commented Feb 25, 2025 •

edited by mateusoliveira43

Loading