diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 5f9eedcd4573..8f04c9554f7b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3713,6 +3713,17 @@ Topics: Topics: - Name: Restoring applications File: restoring-applications + - Name: OADP Self-Service + Dir: oadp-self-service + Topics: + - Name: OADP Self-Service + File: oadp-self-service + - Name: OADP Self-Service cluster admin use cases + File: oadp-self-service-cluster-admin-use-cases + - Name: OADP Self-Service namespace admin use cases + File: oadp-self-service-namespace-admin-use-cases + - Name: OADP Self-Service troubleshooting + File: oadp-self-service-troubleshooting - Name: OADP and ROSA Dir: oadp-rosa Topics: diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/_attributes b/backup_and_restore/application_backup_and_restore/oadp-self-service/_attributes new file mode 120000 index 000000000000..bf7c2529fdb4 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/_attributes @@ -0,0 +1 @@ +../../../_attributes/ \ No newline at end of file diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/images b/backup_and_restore/application_backup_and_restore/oadp-self-service/images new file mode 120000 index 000000000000..4399cbb3c0f3 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/images @@ -0,0 +1 @@ +../../../images/ \ No newline at end of file diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/modules b/backup_and_restore/application_backup_and_restore/oadp-self-service/modules new file mode 120000 index 000000000000..36719b9de743 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc new file mode 100644 index 000000000000..9f22e641ecd4 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc @@ -0,0 +1,29 @@ +:_mod-docs-content-type: ASSEMBLY +[id="oadp-self-service-cluster-admin-use-cases"] += {oadp-short} Self-Service cluster admin use cases +include::_attributes/common-attributes.adoc[] +:context: oadp-self-service-cluster-admin-use-cases + +toc::[] + +As a cluster administrator, you can use the Self-Service feature in the following scenarios: + +* Enable or disable {oadp-short} Self-Service. +* Approve or reject the NABSL custom resource (CR). +* Enforce template policies in the `DataProtectionApplication` (DPA) CR. + +include::modules/oadp-self-service-admin-enable-disable.adoc[leveloffset=+1] + +include::modules/oadp-self-service-enabling-nabsl-approval.adoc[leveloffset=+1] + +include::modules/oadp-self-service-approving-nabsl.adoc[leveloffset=+1] + +include::modules/oadp-self-service-rejecting-nabsl.adoc[leveloffset=+1] + +include::modules/oadp-self-service-admin-spec-enforcement.adoc[leveloffset=+1] + +include::modules/oadp-self-service-admin-spec-enforce-nabsl.adoc[leveloffset=+1] + +include::modules/oadp-self-service-admin-spec-enforce-nab.adoc[leveloffset=+1] + +include::modules/oadp-self-service-admin-spec-enforce-nar.adoc[leveloffset=+1] diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc new file mode 100644 index 000000000000..76931dcc6dad --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: ASSEMBLY +[id="oadp-self-service-namespace-admin-use-cases"] += {oadp-short} Self-Service namespace admin use cases +include::_attributes/common-attributes.adoc[] +:context: oadp-self-service-namespace-admin-use-cases + +toc::[] + +As a namespace admin user, you can use the Self-Service feature in the following scenarios: + +* Create a backup storage location in your authorized namespace. +* Create a `NonAdminBackup` (NAB) custom resource (CR). +* Create a `NonAdminRestore` (NAR) CR. +* Review NAB and NAR logs. + +include::modules/oadp-self-service-creating-nabsl.adoc[leveloffset=+1] + +include::modules/oadp-self-service-creating-nab.adoc[leveloffset=+1] + +include::modules/oadp-self-service-creating-nar.adoc[leveloffset=+1] + +include::modules/oadp-self-service-about-nadr.adoc[leveloffset=+1] + +include::modules/oadp-self-service-nab-nar-logs.adoc[leveloffset=+1] diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-troubleshooting.adoc b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-troubleshooting.adoc new file mode 100644 index 000000000000..2241d0d88193 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-troubleshooting.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="oadp-self-service-troubleshooting"] += {oadp-short} Self-Service troubleshooting +include::_attributes/common-attributes.adoc[] +:context: oadp-self-service-troubleshooting + +toc::[] + +You can use the following sections to troubleshoot common errors when using {oadp-short} Self-Service. + +include::modules/oadp-self-service-troubleshoot-nabsl-same-ns.adoc[leveloffset=+1] + +include::modules/oadp-self-service-troubleshoot-nabsl-default.adoc[leveloffset=+1] \ No newline at end of file diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc new file mode 100644 index 000000000000..699c5e0fdc86 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc @@ -0,0 +1,30 @@ +:_mod-docs-content-type: ASSEMBLY +[id="oadp-self-service"] += {oadp-short} Self-Service +include::_attributes/common-attributes.adoc[] +:context: oadp-self-service + +toc::[] + +{oadp-full} ({oadp-short}) 1.5.0 introduces a new feature named {oadp-short} Self-Service, enabling namespace admin users to back up and restore applications on {product-title}. + +include::modules/oadp-self-service-overview.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#configuring-htpasswd-identity-provider[Configuring an htpasswd identity provider] + +include::modules/oadp-self-service-components.adoc[leveloffset=+1] + +include::modules/oadp-self-service-how-it-works.adoc[leveloffset=+1] + +include::modules/oadp-self-service-prerequisites.adoc[leveloffset=+1] + +include::modules/oadp-self-service-namespace-permissions.adoc[leveloffset=+1] + +include::modules/oadp-self-service-unsupported-features.adoc[leveloffset=+1] + +include::modules/oadp-self-service-phases.adoc[leveloffset=+1] + +include::modules/oadp-self-service-about-nabsl.adoc[leveloffset=+1] diff --git a/backup_and_restore/application_backup_and_restore/oadp-self-service/snippets b/backup_and_restore/application_backup_and_restore/oadp-self-service/snippets new file mode 120000 index 000000000000..ce62fd7c41e2 --- /dev/null +++ b/backup_and_restore/application_backup_and_restore/oadp-self-service/snippets @@ -0,0 +1 @@ +../../../snippets/ \ No newline at end of file diff --git a/images/oadp-self-service.svg b/images/oadp-self-service.svg new file mode 100644 index 000000000000..8b7d650eb75d --- /dev/null +++ b/images/oadp-self-service.svg @@ -0,0 +1,576 @@ + + + + + + + + + + User + + + + + + + + + + + + + Storage stack, repo, database + + + + + + + + + + + + + + + + + + + + + + + + User namespace + + + + + + + + + + + + + + + + + + + + + + + NonAdminBackup(NAB) + NonAdminController(NAC) + Velero backup object + + + 1 + + + + 2 + + + + 3 + + + + 4 + + + + + 5 + + + Namespaceadmin user + Installs + OADP Operator deployment + + + OADP Operator namespace + + diff --git a/modules/oadp-self-service-about-nabsl.adoc b/modules/oadp-self-service-about-nabsl.adoc new file mode 100644 index 000000000000..4b6f13a66cf3 --- /dev/null +++ b/modules/oadp-self-service-about-nabsl.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-about-nabsl_{context}"] += About NonAdminBackupStorageLocation CR + +A namespace administrator can create a `NonAdminBackupStorageLocation` (NABSL) custom resource (CR) to store the backup data. + +To ensure that the NABSL CR is created and used securely, use cluster administrator controls. The cluster administrator manages the NABSL CR to comply with company policies, and compliance requirements. + +You can create a NABSL CR by using one of the following workflows: + +* *Administrator creation workflow*: In this workflow, the cluster administrator creates the NABSL CR for the namespace admin user. The namespace admin user then references the NABSL in the `NonAdminBackup` CR. +* *Administrator approval workflow*: The cluster administrator must explicitly enable this opt-in feature in the DPA by setting the `nonAdmin.requireApprovalForBSL` field to `true`. The cluster administrator approval process works as follows: +.. A namespace admin user creates a NABSL CR. Because the administrator has enforced an approval process in the DPA, it triggers the creation of a `NonAdminBackupStorageLocationRequest` CR in the `openshift-adp` namespace. +.. The cluster administrator reviews the request and either approves or rejects the request. +** If approved, a `Velero` `BackupStorageLocation` (BSL) is created in the `openshift-adp` namespace, and the NABSL CR status is updated to reflect the approval. +** If rejected, the status of the NABSL CR is updated to reflect the rejection. +.. The cluster administrator can also revoke a previously approved NABSL CR. The `approve` field is set back to `pending` or `reject`. This results in the deletion of the `Velero` BSL, and the namespace admin user is notified of the rejection. +* *Automatic approval workflow*: In this workflow, the cluster administrator has not enforced an approval process for the NABSL CR by setting the `nonAdmin.requireApprovalForBSL` field in the DPA to `false`. The default value of this field is `false`. Not setting the field results in an automatic approval of the NABSL. Therefore, the namespace admin user can create the NABSL CR from their authorized namespace. + +[IMPORTANT] +==== +For security purposes, use either the administrator creation or the administrator approval workflow. The automatic approval workflow is less secure as it does not require administrator review. +==== \ No newline at end of file diff --git a/modules/oadp-self-service-about-nadr.adoc b/modules/oadp-self-service-about-nadr.adoc new file mode 100644 index 000000000000..873c5c0d93f1 --- /dev/null +++ b/modules/oadp-self-service-about-nadr.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-about-nadr_{context}"] += About NonAdminDownloadRequest CR + +As a namespace admin user, you can use the `NonAdminDownloadRequest` (NADR) custom resource (CR) to access detailed information about your backups and restores for troubleshooting. + +This CR provides information that is equivalent to what a cluster administrator can access by using the `velero backup describe --details` command. + +After the NADR CR request is validated, a secure download URL is generated to access the requested information. + +You can download the following NADR resources: + +.NADR resources +|=== +| *Resource type* | *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` +|=== \ No newline at end of file diff --git a/modules/oadp-self-service-admin-enable-disable.adoc b/modules/oadp-self-service-admin-enable-disable.adoc new file mode 100644 index 000000000000..5c9e307cbcd1 --- /dev/null +++ b/modules/oadp-self-service-admin-enable-disable.adoc @@ -0,0 +1,90 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-admin-enable-disable_{context}"] += Enabling and disabling {oadp-short} Self-Service + +You must be a cluster administrator to enable the {oadp-short} Self-Service feature. You can use the `spec.nonAdmin.enable` section of the `DataProtectionApplication` (DPA) custom resource (CR) to enable and disable the Self-Service feature. + +Enabling the Self-Service feature installs the `NonAdminController` (NAC) CR in the {oadp-short} Operator namespace. + +[NOTE] +==== +You can install only one instance of the `NonAdminController` (NAC) CR in the cluster. If you install multiple instances of the NAC CR, you get the following error: + +.Example error +[source,terminal] +---- +message: only a single instance of Non-Admin Controller can be installed across the entire cluster. Non-Admin controller is already configured and installed in openshift-adp namespace. +---- +==== + +.Prerequisites + +* You are logged in to the cluster with the `cluster-admin` role. +* You have installed the {oadp-short} Operator. +* You have configured the DPA. + +.Procedure + +* To enable {oadp-short} Self-Service, edit the DPA CR to configure the `nonAdmin.enable` section. See the following example configuration: ++ +.Example `DataProtectionApplication` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: DataProtectionApplication +metadata: + name: oadp-backup + namespace: openshift-adp +spec: + configuration: + nodeAgent: + enable: true + uploaderType: kopia + velero: + defaultPlugins: + - aws + - openshift + - csi + defaultSnapshotMoveData: true + nonAdmin: # <1> + enable: true # <2> + backupLocations: + - velero: + config: + profile: "default" + region: noobaa + s3Url: https://s3.openshift-storage.svc + s3ForcePathStyle: "true" + insecureSkipTLSVerify: "true" + provider: aws + default: true + credential: + key: cloud + name: + objectStorage: + bucket: + prefix: oadp +---- +<1> Add the `nonAdmin.enable` section in the `spec` section of the DPA. +<2> Set the `enable` field to `true`. To disable the Self-Service feature, set the `enable` field to `false`. + +.Verification + +* To verify that the `NonAdminController` (NAC) pod is running in the {oadp-short} namespace, run the following command: ++ +[source,terminal] +---- +$ oc get pod -n openshift-adp -l control-plane=non-admin-controller +---- ++ +.Example output ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +non-admin-controller-5d....f5-p..9p 1/1 Running 0 99m +---- \ No newline at end of file diff --git a/modules/oadp-self-service-admin-spec-enforce-nab.adoc b/modules/oadp-self-service-admin-spec-enforce-nab.adoc new file mode 100644 index 000000000000..940d47ec0945 --- /dev/null +++ b/modules/oadp-self-service-admin-spec-enforce-nab.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-admin-spec-enforce-nab_{context}"] += Self-Service administrator spec enforcement for NAB + +As a cluster administrator, you can enforce the following fields for a `NonAdminBackup` (NAB) CR: + +* `csiSnapshotTimeout` +* `itemOperationTimeout` +* `resourcePolicy` +* `includedResources` +* `excludedResources` +* `orderedResources` +* `includeClusterResources` +* `excludedClusterScopedResources` +* `excludedNamespaceScopedResources` +* `includedNamespaceScopedResources` +* `labelSelector` +* `orLabelSelectors` +* `snapshotVolumes` +* `ttl` +* `snapshotMoveData` +* `uploaderConfig.parallelFilesUpload` + +If you want to enforce a `ttl` value and a Data Mover backup for a namespace admin user, you can set up the `DataProtectionApplication` (DPA) CR as shown in the following example: + +.Example `DataProtectionApplication` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: DataProtectionApplication +... +spec: + nonAdmin: + enable: true + enforceBackupSpec: # <1> + snapshotMoveData: true # <2> + ttl: 158h0m0s # <3> +---- +<1> Add the `enforceBackupSpec` section. +<2> Enforce Data Mover by setting the `snapshotMoveData` field to `true`. +<3> Enforce the `ttl` value by setting the field to `158h0m0s`. + +When a namespace admin user creates a NAB CR, they must follow the template set up in the DPA. Otherwise, the `status.phase` field on the NAB CR is set to `BackingOff` and the NAB CR fails to create. \ No newline at end of file diff --git a/modules/oadp-self-service-admin-spec-enforce-nabsl.adoc b/modules/oadp-self-service-admin-spec-enforce-nabsl.adoc new file mode 100644 index 000000000000..4a4522485938 --- /dev/null +++ b/modules/oadp-self-service-admin-spec-enforce-nabsl.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-admin-spec-enforce-nabsl_{context}"] += Self-Service administrator spec enforcement for NABSL + +As a cluster administrator, you can enforce the following fields for a `NonAdminBackupStorageLocation` (NABSL) custom resource (CR): + +* `objectStorage` +* `credential` +* `config` +* `accessMode` +* `validationFrequency` + +For example, if you want to enforce a namespace admin user to use a specific storage bucket, you can set up the `DataProtectionApplication` (DPA) CR as following: + +.Example `DataProtectionApplication` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: DataProtectionApplication +... +spec: + nonAdmin: + enable: true + enforceBSLSpec: # <1> + config: # <2> + checksumAlgorithm: "" + profile: default + region: us-west-2 + objectStorage: # <3> + bucket: my-company-bucket + prefix: velero + provider: aws +---- +<1> Add the `enforceBSLSpec` section. +<2> Enforce the `config` section of a NABSL to use an {aws-short} S3 bucket in the `us-west-2` region. +<3> Enforce the `objectStorage` section of a NABSL to use a company bucket named `my-company-bucket`. + +When a namespace admin user creates a NABSL, they must follow the template set up in the DPA. Otherwise, the `status.phase` field on the NABSL CR is set to `BackingOff` and the NABSL fails to create. diff --git a/modules/oadp-self-service-admin-spec-enforce-nar.adoc b/modules/oadp-self-service-admin-spec-enforce-nar.adoc new file mode 100644 index 000000000000..c441e0baa2da --- /dev/null +++ b/modules/oadp-self-service-admin-spec-enforce-nar.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-admin-spec-enforce-nar_{context}"] += Self-Service administrator spec enforcement for NAR + +As a cluster administrator, you can enforce the following fields for a `NonAdminRestore` (NAR) custom resource (CR): + +* `itemOperationTimeout` +* `uploaderConfig` +* `includedResources` +* `excludedResources` +* `restoreStatus` +* `includeClusterResources` +* `labelSelector` +* `orLabelSelectors` +* `restorePVs` +* `preserveNodePorts` \ No newline at end of file diff --git a/modules/oadp-self-service-admin-spec-enforcement.adoc b/modules/oadp-self-service-admin-spec-enforcement.adoc new file mode 100644 index 000000000000..bd301f4e5d7c --- /dev/null +++ b/modules/oadp-self-service-admin-spec-enforcement.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-admin-spec-enforcement_{context}"] += {oadp-short} Self-Service administrator DPA spec enforcement + +As a cluster administrator, you can enforce policies in the `DataProtectionApplication` (DPA) spec template. The spec enforcement applies to Self-Service custom resources (CRs) such as `NonAdminBackup`, `NonAdminRestore`, and `NonAdminBackupStorageLocation`. + +The cluster administrator can enforce a company, or a compliance policy by using the following fields in the `DataProtectionApplication` (DPA) CR: + +`enforceBSLSpec`:: To enforce a policy on the `NonAdminBackupStorageLocation` CR. +`enforceBackupSpec`:: To enforce a policy on the `NonAdminBackup` CR. +`enforceRestoreSpec`:: To enforce a policy on the `NonAdminRestore` CR. + +By using the enforceable fields, administrators can ensure that the NABSL, NAB, and NAR CRs created by a namespace admin user, comply with the administrator defined policy. diff --git a/modules/oadp-self-service-approving-nabsl.adoc b/modules/oadp-self-service-approving-nabsl.adoc new file mode 100644 index 000000000000..0f673ad00c45 --- /dev/null +++ b/modules/oadp-self-service-approving-nabsl.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-approving-nabsl_{context}"] += Approving a NonAdminBackupStorageLocation request + +As a cluster administrator, to approve a `NonAdminBackupStorageLocation` (NABSL) CR request, you can edit the `NonAdminBackupStorageLocationRequest` CR and set the `approvalDecision` field to `approve`. + +.Prerequisites + +* You are logged in to the cluster with the `cluster-admin` role. +* You have installed the {oadp-short} Operator. +* You have enabled {oadp-short} Self-Service in the `DataProtectionApplication` (DPA) CR. +* You have enabled the NABSL CR approval workflow in the DPA. + +.Procedure + +. To see the NABSL CR requests that are in queue for administrator approval, run the following command: ++ +[source,terminal] +---- +$ oc -n openshift-adp get NonAdminBackupStorageLocationRequests +---- ++ +.Example output +[source,terminal] +---- +NAME REQUEST-PHASE REQUEST-NAMESPACE REQUEST-NAME AGE +non-admin-bsl-test-.....175 Approved non-admin-bsl-test incorrect-bucket-nabsl 4m57s +non-admin-bsl-test-.....196 Approved non-admin-bsl-test perfect-nabsl 5m26s +non-admin-bsl-test-s....e1a Rejected non-admin-bsl-test suspicious-sample 2m56s +non-admin-bsl-test-.....5e0 Pending non-admin-bsl-test waitingapproval-nabsl 4m20s +---- + +. To approve the NABSL CR request, set the `approvalDecision` field to `approve` by running the following command: ++ +[source,terminal] +---- +$ oc patch nabslrequest -n openshift-adp --type=merge -p '{"spec": {"approvalDecision": "approve"}}' # <1> +---- +<1> Specify the name of the `NonAdminBackupStorageLocationRequest` CR. + + +.Verification + +* Verify that the Velero backup storage location is created and the phase is `Available` by running the following command: ++ +[source,terminal] +---- +$ oc get velero.io.backupstoragelocation +---- ++ +.Example output + +[source,terminal] +---- +NAME PHASE LAST VALIDATED AGE DEFAULT +test-nac-test-bsl-cd...930 Available 62s 62s +---- \ No newline at end of file diff --git a/modules/oadp-self-service-components.adoc b/modules/oadp-self-service-components.adoc new file mode 100644 index 000000000000..50bbb8914605 --- /dev/null +++ b/modules/oadp-self-service-components.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-custom-resources_{context}"] += {oadp-short} Self-Service custom resources + +The {oadp-short} Self-Service feature has the following new custom resources (CRs) to perform the backup and restore operations for a namespace admin user: + +.Custom resources +|=== +|*CR* |*Description* +|`NonAdminController` (NAC)| Controls and orchestrates the Self-Service operations. +|`NonAdminBackup` (NAB)| Manages namespace-scoped backup operations. +|`NonAdminRestore` (NAR)| Manages namespace-scoped restore operations. +|`NonAdminBackupStorageLocation` (NABSL)| Defines user-specific backup storage location. +|`NonAdminDownloadRequest` (NADR)| Manages namespace-scoped download request operations. +|=== \ No newline at end of file diff --git a/modules/oadp-self-service-creating-nab.adoc b/modules/oadp-self-service-creating-nab.adoc new file mode 100644 index 000000000000..429b92ea0722 --- /dev/null +++ b/modules/oadp-self-service-creating-nab.adoc @@ -0,0 +1,160 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-creating-nab_{context}"] += Creating a NonAdminBackup CR + +As a namespace admin user, you can create a `NonAdminBackup` (NAB) custom resource (CR) to back up your application from your authorized namespace. NAB is an {product-title} CR that securely facilitates the creation of a `Velero` backup object. The `Velero` backup object reports the status back to the NAB CR that ultimately updates the `status.phase` field. + +After you create a NAB CR, the CR undergoes the following phases: + +* The initial phase for the CR is `New`. +* The CR creation request goes to the `NonAdminController` (NAC) for reconciliation and validation. +* Upon successful validation and creation of the `Velero` backup object, the `status.phase` field of the NAB CR is updated to the next phase, which is, `Created`. + +Review the following important points when creating a NAB CR: + +* The `NonAdminBackup` CR creates the `Velero` backup object securely so that other namespace admin users cannot access the CR. +* As a namespace admin user, you can only specify your authorized namespace in the NAB CR. You get an error when you specify a namespace you are not authorized to use. + +.Prerequisites + +* You are logged in to the cluster as a namespace admin user. +* The cluster administrator has installed the {oadp-short} Operator. +* The cluster administrator has configured the `DataProtectionApplication` (DPA) CR to enable {oadp-short} Self-Service. +* The cluster administrator has created a namespace for you and has authorized you to operate from that namespace. +* Optional: You can create and use a `NonAdminBackupStorageLocation` (NABSL) CR to store the backup data. If you do not use a NABSL CR, then the backup is stored in the default backup storage location configured in the DPA. + +.Procedure + +. To create a `NonAdminBackup` CR, create a YAML manifest file with the following configuration: ++ +.Example `NonAdminBackup` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackup +metadata: + name: test-nab # <1> +spec: + backupSpec: + defaultVolumesToFsBackup: true # <2> + snapshotMoveData: false # <3> + storageLocation: test-bsl # <4> +---- +<1> Specify a name for the NAB CR, for example, `test-nab`. +<2> To use File System Backup (FSB), set `defaultVolumesToFsBackup` to `true`. +<3> If you want to backup your data volumes by using the Data Mover, set the `snapshotMoveData` to `true`. This example uses the FSB for backup. +<4> Optionally, set a NABSL CR as a storage location. If you do not set a `storageLocation`, then the default backup storage location configured in the DPA is used. + +. To apply the NAB CR configuration, run the following command: ++ +[source,terminal] +---- +$ oc apply -f # <1> +---- +<1> Specify the file name containing the NAB CR configuration. + +.Verification + +* To verify that the NAB CR is successfully created, run the following command: ++ +[source,terminal] +---- +$ oc get nab test-nab -o yaml +---- ++ +.Example output + ++ +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackup +metadata: + creationTimestamp: "2025-03-06T10:02:56Z" + finalizers: + - nonadminbackup.oadp.openshift.io/finalizer + generation: 2 + name: test-nab + namespace: test-nac-ns # <1> + resourceVersion: "134316" + uid: c5...4c8a8 +spec: + backupSpec: + csiSnapshotTimeout: 0s + defaultVolumesToFsBackup: true + hooks: {} + itemOperationTimeout: 0s + metadata: {} + storageLocation: test-bsl + ttl: 0s +status: + conditions: + - lastTransitionTime: "202...56Z" + message: backup accepted # <2> + reason: BackupAccepted + status: "True" + type: Accepted + - lastTransitionTime: "202..T10:02:56Z" + message: Created Velero Backup object + reason: BackupScheduled + status: "True" + type: Queued + dataMoverDataUploads: {} + fileSystemPodVolumeBackups: # <3> + completed: 2 + total: 2 + phase: Created # <4> + queueInfo: + estimatedQueuePosition: 0 # <5> + veleroBackup: + nacuuid: test-nac-test-nab-d2...a9b14 # <6> + name: test-nac-test-nab-d2...b14 # <7> + namespace: openshift-adp + spec: + csiSnapshotTimeout: 10m0s + defaultVolumesToFsBackup: true + excludedResources: + - nonadminbackups + - nonadminrestores + - nonadminbackupstoragelocations + - securitycontextconstraints + - clusterroles + - clusterrolebindings + - priorityclasses + - customresourcedefinitions + - virtualmachineclusterinstancetypes + - virtualmachineclusterpreferences + hooks: {} + includedNamespaces: + - test-nac-ns + itemOperationTimeout: 4h0m0s + metadata: {} + snapshotMoveData: false + storageLocation: test-nac-test-bsl-bf..02b70a + ttl: 720h0m0s + status: # <8> + completionTimestamp: "2025-0..3:13Z" + expiration: "2025..2:56Z" + formatVersion: 1.1.0 + hookStatus: {} + phase: Completed # <9> + progress: + itemsBackedUp: 46 + totalItems: 46 + startTimestamp: "2025-..56Z" + version: 1 + warnings: 1 +---- +<1> The namespace name that the `NonAdminController` CR sets on the `Velero` backup object to back up. +<2> The NAC has reconciled and validated the NAB CR and has created the `Velero` backup object. +<3> The `fileSystemPodVolumeBackups` field indicates the number of volumes that are backed up by using FSB. +<4> The NAB CR is in the `Created` phase. +<5> This field indicates the queue position of the backup object. There can be multiple backups in process, and each backup object is assigned a queue position. When the backup is complete, the queue position is set to `0`. +<6> The NAC creates the `Velero` backup object and sets the value for the `nacuuid` field. +<7> The name of the associated `Velero` backup object. +<8> The status of the `Velero` backup object. +<9> The `Velero` backup object is in the `Completed` phase and the backup is successful. \ No newline at end of file diff --git a/modules/oadp-self-service-creating-nabsl.adoc b/modules/oadp-self-service-creating-nabsl.adoc new file mode 100644 index 000000000000..68ffca6ed555 --- /dev/null +++ b/modules/oadp-self-service-creating-nabsl.adoc @@ -0,0 +1,165 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-creating-nabsl_{context}"] += Creating a NonAdminBackupStorageLocation CR + +You can create a `NonAdminBackupStorageLocation` (NABSL) custom resource (CR) in your authorized namespace. After the cluster administrator approves the NABSL CR request, you can use the NABSL CR in the `NonAdminBackup` CR spec. + +.Prerequisites + +* You are logged in to the cluster as a namespace admin user. +* The cluster administrator has installed the {oadp-short} Operator. +* The cluster administrator has configured the `DataProtectionApplication` (DPA) CR to enable {oadp-short} Self-Service. +* The cluster administrator has created a namespace for you and has authorized you to operate from that namespace. + +.Procedure + +. Create a `Secret` CR by using the cloud credentials file content for your cloud provider. Run the following command: ++ +[source,terminal] +---- +$ oc create secret generic cloud-credentials -n test-nac-ns --from-file = # <1> +---- +<1> In this example, the `Secret` name is `cloud-credentials` and the authorized namespace name is `test-nac-ns`. Replace `` and `` with your cloud key name and the cloud credentials file name, respectively. + +. To create a `NonAdminBackupStorageLocation` CR, create a YAML manifest file with the following configuration: ++ +.Example `NonAdminBackupStorageLocation` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackupStorageLocation +metadata: + name: test-nabsl + namespace: test-nac-ns # <1> +spec: + backupStorageLocationSpec: + config: + profile: default + region: # <2> + credential: + key: cloud + name: cloud-credentials + objectStorage: + bucket: # <3> + prefix: velero + provider: aws +---- +<1> Specify the namespace you are authorized to operate from. For example, `test-nac-ns`. +<2> Replace `` with a region name. +<3> Replace `` with a bucket name. + +. To apply the NABSL CR configuration, run the following command: ++ +[source,terminal] +---- +$ oc apply -f # <1> +---- +<1> Replace `` with the file name containing the NABSL CR configuration. + + +.Verification + +. To verify that the NABSL CR is in the `New` phase and is pending administrator approval, run the following command: ++ +[source,terminal] +---- +$ oc get nabsl test-nabsl -o yaml +---- ++ +.Example output + +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackupStorageLocation +... +status: + conditions: + - lastTransitionTime: "2025-02-26T09:07:15Z" + message: NonAdminBackupStorageLocation spec validation successful + reason: BslSpecValidation + status: "True" + type: Accepted + - lastTransitionTime: "2025-02-26T09:07:15Z" + message: NonAdminBackupStorageLocationRequest approval pending # <1> + reason: BslSpecApprovalPending + status: "False" + type: ClusterAdminApproved + phase: New # <2> + veleroBackupStorageLocation: + nacuuid: test-nac-test-bsl-c...d4389a1930 + name: test-nac-test-bsl-cd....1930 + namespace: openshift-adp +---- +<1> Defines that the `status.conditions.message` field contains the `NonAdminBackupStorageLocationRequest approval pending` message . +<2> Defines that the status of a phase is `New`. + +. After the cluster administrator approves the `NonAdminBackupStorageLocationRequest` CR request, verify that the NABSL CR is successfully created by running the following command: ++ +[source,terminal] +---- +$ oc get nabsl test-nabsl -o yaml +---- ++ +.Example output + ++ +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackupStorageLocation +metadata: + creationTimestamp: "2025-02-19T09:30:34Z" + finalizers: + - nonadminbackupstoragelocation.oadp.openshift.io/finalizer + generation: 1 + name: test-nabsl + namespace: test-nac-ns + resourceVersion: "159973" + uid: 4a..80-3260-4ef9-a3..5a-00...d1922 +spec: + backupStorageLocationSpec: + credential: + key: cloud + name: cloud-credentials + objectStorage: + bucket: oadp...51rrdqj + prefix: velero + provider: aws +status: + conditions: + - lastTransitionTime: "2025-02-19T09:30:34Z" + message: NonAdminBackupStorageLocation spec validation successful # <1> + reason: BslSpecValidation + status: "True" + type: Accepted + - lastTransitionTime: "2025-02-19T09:30:34Z" + message: Secret successfully created in the OADP namespace # <2> + reason: SecretCreated + status: "True" + type: SecretSynced + - lastTransitionTime: "2025-02-19T09:30:34Z" + message: BackupStorageLocation successfully created in the OADP namespace # <3> + reason: BackupStorageLocationCreated + status: "True" + type: BackupStorageLocationSynced + phase: Created + veleroBackupStorageLocation: + nacuuid: test-nac-..f933a-4ec1-4f6a-8099-ee...b8b26 # <4> + name: test-nac-test-nabsl-36...11ab8b26 # <5> + namespace: openshift-adp + status: + lastSyncedTime: "2025-02-19T11:47:10Z" + lastValidationTime: "2025-02-19T11:47:31Z" + phase: Available # <6> +---- +<1> The NABSL `spec` is validated and approved by the cluster administrator. +<2> The `secret` object is successfully created in the `openshift-adp` namespace. +<3> The associated `Velero` `BackupStorageLocation` is successfully created in the `openshift-adp` namespace. +<4> The `nacuuid` NAC is orchestrating the NABSL CR. +<5> The name of the associated `Velero` backup storage location object. +<6> The `Available` phase indicates that the NABSL is ready for use. \ No newline at end of file diff --git a/modules/oadp-self-service-creating-nar.adoc b/modules/oadp-self-service-creating-nar.adoc new file mode 100644 index 000000000000..207b277c2a97 --- /dev/null +++ b/modules/oadp-self-service-creating-nar.adoc @@ -0,0 +1,114 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-creating-nar_{context}"] += Creating a NonAdminRestore CR + +As a namespace admin user, to restore a backup, you can create a `NonAdminRestore` (NAR) custom resource (CR). The backup is restored to your authorized namespace. + +.Prerequisites + +* You are logged in to the cluster as a namespace admin user. +* The cluster administrator has installed the {oadp-short} Operator. +* The cluster administrator has configured the `DataProtectionApplication` (DPA) CR to enable {oadp-short} Self-Service. +* The cluster administrator has created a namespace for you and has authorized you to operate from that namespace. +* You have a backup of your application by creating a `NonAdminBackup` (NAB) CR. + +.Procedure + +. To create a `NonAdminRestore` CR, create a YAML manifest file with the following configuration: ++ +.Example `NonAdminRestore` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminRestore +metadata: + name: test-nar # <1> +spec: + restoreSpec: + backupName: test-nab # <2> +---- +<1> Defines a name for the NAR CR, for example, `test-nar`. +<2> Defines the name of the NAB CR you want to restore from. For example, `test-nab`. + +. To apply the NAR CR configuration, run the following command: ++ +[source,terminal] +---- +$ oc apply -f # <1> +---- +<1> Replace `` with the file name containing the NAR CR configuration. + +.Verification + +. To verify that the NAR CR is successfully created, run the following command: ++ +[source,terminal] +---- +$ oc get nar test-nar -o yaml +---- ++ +.Example output + ++ +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminRestore +metadata: + creationTimestamp: "2025-..:15Z" + finalizers: + - nonadminrestore.oadp.openshift.io/finalizer + generation: 2 + name: test-nar + namespace: test-nac-ns + resourceVersion: "156517" + uid: f9f5...63ef34 +spec: + restoreSpec: + backupName: test-nab + hooks: {} + itemOperationTimeout: 0s +status: + conditions: + - lastTransitionTime: "2025..15Z" + message: restore accepted # <1> + reason: RestoreAccepted + status: "True" + type: Accepted + - lastTransitionTime: "2025-03-06T11:22:15Z" + message: Created Velero Restore object + reason: RestoreScheduled + status: "True" + type: Queued + dataMoverDataDownloads: {} + fileSystemPodVolumeRestores: # <2> + completed: 2 + total: 2 + phase: Created # <3> + queueInfo: + estimatedQueuePosition: 0 # <4> + veleroRestore: + nacuuid: test-nac-test-nar-c...1ba # <5> + name: test-nac-test-nar-c7...1ba # <6> + namespace: openshift-adp + status: + completionTimestamp: "2025...22:44Z" + hookStatus: {} + phase: Completed # <7> + progress: + itemsRestored: 28 + totalItems: 28 + startTimestamp: "2025..15Z" + warnings: 7 +---- +<1> The `NonAdminController` (NAC) CR has reconciled and validated the NAR CR. +<2> The `fileSystemPodVolumeRestores` field indicates the number of volumes that are restored. +<3> The NAR CR is in the `Created` phase. +<4> This field indicates the queue position of the restore object. There can be multiple restores in process, and each restore is assigned a queue position. When the restore is complete, the queue position is set to `0`. +<5> The NAC creates the `Velero` restore object and sets the value as `nacuuid`. +<6> The name of the associated `Velero` restore object. +<7> The `Velero` restore object is in the `Completed` phase and the restore is successful. diff --git a/modules/oadp-self-service-enabling-nabsl-approval.adoc b/modules/oadp-self-service-enabling-nabsl-approval.adoc new file mode 100644 index 000000000000..384dcc77decf --- /dev/null +++ b/modules/oadp-self-service-enabling-nabsl-approval.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-enabling-nabsl-approval_{context}"] += Enabling NonAdminBackupStorageLocation administrator approval workflow + +The `NonAdminBackupStorageLocation` (NABSL) custom resource (CR) administrator approval workflow is an opt-in feature. As a cluster administrator, you must explicitly enable the feature in the `DataProtectionApplication` (DPA) CR by setting the `nonAdmin.requireApprovalForBSL` field to `true`. + +You also need to set the `noDefaultBackupLocation` field in the DPA CR to `true`. This setting indicates that, there is no default backup storage location configured in the DPA CR and the namespace admin user can create a NABSL CR and send the CR request for approval. + +.Prerequisites + +* You are logged in to the cluster with the `cluster-admin` role. +* You have installed the {oadp-short} Operator. +* You have enabled {oadp-short} Self-Service in the `DataProtectionApplication` CR. + +.Procedure + +* To enable the NABSL administrator approval workflow, edit the DPA CR by using the following example configuration: ++ +.Example `DataProtectionApplication` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: DataProtectionApplication +metadata: + name: oadp-backup + namespace: openshift-adp +spec: + configuration: + nodeAgent: + enable: true + uploaderType: kopia + velero: + defaultPlugins: + - aws + - openshift + - csi + noDefaultBackupLocation: true # <1> + nonAdmin: + enable: true + requireApprovalForBSL: true # <2> +---- +<1> Add the `noDefaultBackupLocation` field and set it to `true`. +<2> Add the `requireApprovalForBSL` field and set it to `true`. \ No newline at end of file diff --git a/modules/oadp-self-service-how-it-works.adoc b/modules/oadp-self-service-how-it-works.adoc new file mode 100644 index 000000000000..27012a1001e6 --- /dev/null +++ b/modules/oadp-self-service-how-it-works.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-how-it-works_{context}"] += How {oadp-short} Self-Service works + +The following diagram describes how {oadp-short} Self-Service works at a high level. The diagram describes the following workflow: + +. A namespace admin user creates a `NonAdminBackup` (NAB) custom resource (CR) request. +. The `NonAdminController` (NAC) CR receives the NAB CR request. +. The NAC validates the request and updates the NAB CR about the request. +. The NAC creates the `Velero` backup object. +. The NAC monitors the `Velero` backup object and cascades the status back to the NAB CR. + +.How {oadp-short} Self-Service works +image::oadp-self-service.svg[{oadp-short} Self-Service] \ No newline at end of file diff --git a/modules/oadp-self-service-nab-nar-logs.adoc b/modules/oadp-self-service-nab-nar-logs.adoc new file mode 100644 index 000000000000..f56375a14213 --- /dev/null +++ b/modules/oadp-self-service-nab-nar-logs.adoc @@ -0,0 +1,146 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-nab-nar-logs_{context}"] += Reviewing NAB and NAR logs + +As a namespace admin user, you can review the logs for the NAB and NAR custom resources (CRs) by creating a `NonAdminDownloadRequest` (NADR) CR. + +[NOTE] +==== +You can review the NAB logs only if you are using a `NonAdminBackupStorageLocation` (NABSL) CR as a backup storage location for the backup. +==== + +.Prerequisites + +* You are logged in to the cluster as a namespace admin user. +* The cluster administrator has installed the {oadp-short} Operator. +* The cluster administrator has configured the `DataProtectionApplication` (DPA) CR to enable {oadp-short} Self-Service. +* The cluster administrator has created a namespace for you and has authorized you to operate from that namespace. +* You have a backup of your application by creating a `NonAdminBackup` (NAB) CR. +* You have restored the application by creating a `NonAdminRestore` (NAR) CR. + +.Procedure + +. To review NAB CR logs, create a `NonAdminDownloadRequest` CR and specify the NAB CR name as shown in the following example: ++ +.Example `NonAdminDownloadRequest` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminDownloadRequest +metadata: + name: test-nadr-backup +spec: + target: + kind: BackupLog # <1> + name: test-nab # <2> +---- +<1> Specify `BackupLog` as the value for the `kind` field of the NADR CR. +<2> Specify the name of the NAB CR. + +. Verify that the NADR CR is processed by running the following command. ++ +[source,terminal] +---- +$ oc get nadr test-nadr-backup -o yaml +---- ++ +.Example output + +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminDownloadRequest +metadata: + creationTimestamp: "2025-03-06T10:05:22Z" + generation: 1 + name: test-nadr-backup + namespace: test-nac-ns + resourceVersion: "134866" + uid: 520...8d9 +spec: + target: + kind: BackupLog + name: test-nab +status: + conditions: + - lastTransitionTime: "202...5:22Z" + message: "" + reason: Success + status: "True" + type: Processed + phase: Created + velero: + status: + downloadURL: https://... # <1> + expiration: "202...22Z" + phase: Processed # <2> +---- +<1> The `status.downloadURL` field contains the download URL of the NAB logs. You can use the `downloadURL` to download and review the NAB logs. +<2> The `status.phase` is `Processed`. + +. Download and analyze the backup information by using the `status.downloadURL` URL. + +. To review NAR CR logs, create a `NonAdminDownloadRequest` CR and specify the NAR CR name as shown in the following example: ++ +.Example `NonAdminDownloadRequest` CR +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminDownloadRequest +metadata: + name: test-nadr-restore +spec: + target: + kind: RestoreLog # <1> + name: test-nar # <2> +---- +<1> Specify `RestoreLog` as the value for the `kind` field of the NADR CR. +<2> Defines the name of the NAR CR. + +. Verify that the NADR CR is processed by running the following command. ++ +[source,terminal] +---- +$ oc get nadr test-nadr-restore -o yaml +---- ++ +.Example output + +[source,yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminDownloadRequest +metadata: + creationTimestamp: "2025-03-06T11:26:01Z" + generation: 1 + name: test-nadr-restore + namespace: test-nac-ns + resourceVersion: "157842" + uid: f3e...7862f +spec: + target: + kind: RestoreLog + name: test-nar +status: + conditions: + - lastTransitionTime: "202..:01Z" + message: "" + reason: Success + status: "True" + type: Processed + phase: Created + velero: + status: + downloadURL: https://... # <1> + expiration: "202..:01Z" + phase: Processed # <2> + +---- +<1> The `status.downloadURL` field contains the download URL of the NAR logs. You can use the `downloadURL` to download and review the NAR logs. +<2> The `status.phase` is `Processed`. + +. Download and analyze the restore information by using the `status.downloadURL` URL. \ No newline at end of file diff --git a/modules/oadp-self-service-namespace-permissions.adoc b/modules/oadp-self-service-namespace-permissions.adoc new file mode 100644 index 000000000000..33d5de230bfb --- /dev/null +++ b/modules/oadp-self-service-namespace-permissions.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: REFERENCE +[id="oadp-self-service-namespace-permissions_{context}"] += {oadp-short} Self-Service namespace permissions + +As a cluster administrator, ensure that a namespace admin user has editor roles assigned for the following list of objects in their namespace. These objects ensure that a namespace admin user can perform the backup and restore operations in their namespace. + +* `nonadminbackups.oadp.openshift.io` +* `nonadminbackupstoragelocations.oadp.openshift.io` +* `nonadminrestores.oadp.openshift.io` +* `nonadmindownloadrequests.oadp.openshift.io` + +For more details on the namespace `admin` role, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/authentication_and_authorization/using-rbac#default-roles_using-rbac[Default cluster roles]. + +A cluster administrator can also define their own specifications so that users can have rights similar to `project` or namespace `admin` roles. + +[id="oadp-self-service-yaml-backup-operation_{context}"] +== Example RBAC YAML for backup operation + +See the following RBAC YAML file example with namespace permissions for a namespace `admin` user to perform a backup operation. + +.Example RBAC +[source,yaml] +---- +... +- apiGroups: + - oadp.openshift.io + resources: + - nonadminbackups + - nonadminrestores + - nonadminbackupstoragelocations + - nonadmindownloadrequests + verbs: + - create + - delete + - get + - list + - patch + - update + - watch + - apiGroups: + - oadp.openshift.io + resources: + - nonadminbackups/status + - nonadminrestores/status + verbs: + - get +---- \ No newline at end of file diff --git a/modules/oadp-self-service-overview.adoc b/modules/oadp-self-service-overview.adoc new file mode 100644 index 000000000000..f40b9aad542c --- /dev/null +++ b/modules/oadp-self-service-overview.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-overview_{context}"] += About {oadp-short} Self-Service + +From {oadp-short} 1.5.0 onward, you do not need the `cluster-admin` role to perform the backup and restore operations. You can use {oadp-short} with the namespace `admin` role. The namespace `admin` role has administrator access only to the namespace the user is assigned to. + +You can use the Self-Service feature only after the cluster administrator installs the {oadp-short} Operator and provides the necessary permissions. + +The {oadp-short} Self-Service feature provides secure self-service data protection capabilities for users without `cluster-admin` privileges while maintaining proper access controls. + +The {oadp-short} cluster administrator creates a user with the namespace `admin` role and provides the necessary Role Based Access Controls (RBAC) to the user to perform {oadp-short} Self-Service actions. As this user has limited access compared to the `cluster-admin` role, this user is referred to as a namespace admin user. + +As a namespace admin user, you can back up and restore applications deployed in your authorized namespace on the cluster. + +{oadp-short} Self-Service offers the following benefits: + +* As a cluster administrator: +** You allow namespace-scoped backup and restore operations to a namespace admin user. This means, a namespace admin user cannot access a namespace that they are not authorized to. +** You keep administrator control over non-administrator operations through `DataProtectionApplication` configuration and policies. + +* As a namespace admin user: +** You can create backup and restore custom resources for your authorized namespace. +** You can create dedicated backup storage locations in your authorized namespace. +** You have secure access to backup logs and status information. + +[id="oadp-self-service-overview-namespace-scope_{context}"] += What namespace-scoped backup and restore means + +{oadp-short} Self-Service ensures that namespace admin users can only operate within their authorized namespace. For example, if you do not have access to a namespace, as a namespace admin user, you cannot back up that namespace. + +A namespace admin user cannot access backup and restore data of other users. + +The cluster administrator enforces the access control through custom resources (CRs) that securely manage the backup and restore operations. + +Additionally, the cluster administrator can control the allowed options within the CRs, restricting certain operations for added security by using `spec` enforcements in the `DataProtectionApplication` (DPA) CR. + +Namespace `admin` users can perform the following Self-Service operations: + +* Create and manage backups of their authorized namespaces. +* Restore data to their authorized namespaces. +* Configure their own backup storage locations. +* Check backup and restore status. +* Request retrieval of relevant logs. diff --git a/modules/oadp-self-service-phases.adoc b/modules/oadp-self-service-phases.adoc new file mode 100644 index 000000000000..100e9338d4e7 --- /dev/null +++ b/modules/oadp-self-service-phases.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-phases_{context}"] += {oadp-short} Self-Service backup and restore phases + +The `status.phase` field of a `NonAdminBackup` (NAB) CR and a `NonAdminRestore` (NAR) CR provide an overview of the current state of the CRs. Review the values for the NAB and NAR phases in the following table. + +The phase of the CRs only progress forward. Once a phase transitions to the next phase, it cannot revert to a previous phase. + +.Phases +|=== +|*Value* |*Description* +|New|A creation request of the NAB or NAR CR is accepted by the NAC, but it has not yet been validated by the NAC. +|BackingOff|NAB or NAR CR is invalidated by the NAC CR because of an invalid `spec` of the NAB or NAR CR. + +The namespace admin user can update the NAB or NAR `spec` to comply with the policies set by the administrator. After the namespace admin user edits the CRs, the NAC reconciles the CR again. +|Created|NAB or NAR CR is validated by the NAC, and the `Velero` backup or restore object is created. +|Deletion|NAB or NAR CR is marked for deletion. The NAC deletes the corresponding `Velero` backup or restore object. When the `Velero` object is deleted, the NAB or NAR CR is also deleted. +|=== \ No newline at end of file diff --git a/modules/oadp-self-service-prerequisites.adoc b/modules/oadp-self-service-prerequisites.adoc new file mode 100644 index 000000000000..436a514c225e --- /dev/null +++ b/modules/oadp-self-service-prerequisites.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-prerequisites_{context}"] += {oadp-short} Self-Service prerequisites + +Before you start using {oadp-short} Self-Service as a namespace `admin` user, ensure you meet the following prerequisites: + +* The cluster administrator has configured the {oadp-short} `DataProtectionApplication` (DPA) CR to enable Self-Service. +* The cluster administrator has completed the following tasks: +** Created a namespace `admin` user account. +** Created a namespace for the namespace `admin` user. +** Assigned appropriate privileges for the namespace admin user's namespace. This ensures that the namespace admin user is authorized to access and perform backup and restore operations in their assigned namespace. +* Optionally, the cluster administrator can create a `NonAdminBackupStorageLocation` (NABSL) CR for the namespace `admin` user. \ No newline at end of file diff --git a/modules/oadp-self-service-rejecting-nabsl.adoc b/modules/oadp-self-service-rejecting-nabsl.adoc new file mode 100644 index 000000000000..8e2e3db4e47b --- /dev/null +++ b/modules/oadp-self-service-rejecting-nabsl.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-cluster-admin-use-cases.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-rejecting-nabsl_{context}"] += Rejecting a NonAdminBackupStorageLocation request + +As a cluster administrator, to reject a `NonAdminBackupStorageLocation` (NABSL) custom resource (CR) request, you can edit the `NonAdminBackupStorageLocationRequest` CR and set the `approvalDecision` field to `reject`. + +.Prerequisites + +* You are logged in to the cluster with the `cluster-admin` role. +* You have installed the {oadp-short} Operator. +* You have enabled {oadp-short} Self-Service in the `DataProtectionApplication` (DPA) CR. +* You have enabled the NABSL CR approval workflow in the DPA. + +.Procedure + +. To see the NABSL CR requests that are in queue for administrator approval, run the following command: ++ +[source,terminal] +---- +$ oc -n openshift-adp get NonAdminBackupStorageLocationRequests +---- ++ +.Example output + +[source,terminal] +---- +$ oc get nabslrequest +NAME REQUEST-PHASE REQUEST-NAMESPACE REQUEST-NAME AGE +non-admin-bsl-test-.....175 Approved non-admin-bsl-test incorrect-bucket-nabsl 4m57s +non-admin-bsl-test-.....196 Approved non-admin-bsl-test perfect-nabsl 5m26s +non-admin-bsl-test-s....e1a Rejected non-admin-bsl-test suspicious-sample 2m56s +non-admin-bsl-test-.....5e0 Pending non-admin-bsl-test waitingapproval-nabsl 4m20s +---- + +. To reject the NABSL CR request, set the `approvalDecision` field to `reject` by running the following command: ++ +[source,terminal] +---- +$ oc patch nabslrequest -n openshift-adp --type=merge -p '{"spec": {"approvalDecision": "reject"}}' # <1> +---- +<1> Specify the name of the `NonAdminBackupStorageLocationRequest` CR. \ No newline at end of file diff --git a/modules/oadp-self-service-troubleshoot-nabsl-default.adoc b/modules/oadp-self-service-troubleshoot-nabsl-default.adoc new file mode 100644 index 000000000000..0c0a9e698a96 --- /dev/null +++ b/modules/oadp-self-service-troubleshoot-nabsl-default.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-troubleshooting.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-troubleshoot-nabsl-default_{context}"] += NonAdminBackupStorageLocation cannot be set as default + +As a non-admin user, if you have created a `NonAdminBackupStorageLocation` (NABSL) custom resource (CR) in your authorized namespace, you cannot set the NABSL CR as the default backup storage location. + +In such a scenario, the NABSL CR fails to validate and the `NonAdminController` (NAC) gives an error message. + +.Example NABSL error + +[source, yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackupStorageLocation +metadata: + creationTimestamp: "20...:03Z" + generation: 1 + name: nabsl1 + namespace: test-nac-1 + resourceVersion: "11...9" + uid: 8d2fc....c9b6c4401 +spec: + backupStorageLocationSpec: + credential: + key: cloud + name: cloud-credentials-gcp + default: true # <1> + objectStorage: + bucket: oad..7l8 + prefix: velero + provider: gcp +status: + conditions: + - lastTransitionTime: "20...:27:03Z" + message: NonAdminBackupStorageLocation cannot be used as a default BSL # <2> + reason: BslSpecValidation + status: "False" + type: Accepted + phase: BackingOff +---- +<1> The value of the `default` field is set to `true`. +<2> The error message reported by NAC. + +.Solution + +To successfully validate and reconcile the NABSL CR, ensure that the `default` field is set to `false` in the NABSL CR. \ No newline at end of file diff --git a/modules/oadp-self-service-troubleshoot-nabsl-same-ns.adoc b/modules/oadp-self-service-troubleshoot-nabsl-same-ns.adoc new file mode 100644 index 000000000000..5277fdf13411 --- /dev/null +++ b/modules/oadp-self-service-troubleshoot-nabsl-same-ns.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-troubleshooting.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-troubleshoot-nabsl-same-ns_{context}"] += Error NonAdminBackupStorageLocation not found in the namespace + +Consider the following scenario of a namespace `admin` backup: + +* You have created two `NonAdminBackupStorageLocations` (NABLs) custom resources (CRs) in two different namespaces, for example, `nabsl-1` in `namespace-1` and `nabsl-2` in `namespace-2`. +* You are taking a backup of `namespace-1` and use `nabsl-2` in the `NonAdminBackup` (NAB) CR. + +In this scenario, after creating the NAB CR, you get the following error: + +[source,text] +---- +NonAdminBackupStorageLocation not found in the namespace: NonAdminBackupStorageLocation.oadp.openshift.io +---- + +The cause of the error is that the NABSL CR does not belong to the namespace that you are trying to back up. + +.Error + +[source, yaml] +---- +apiVersion: oadp.openshift.io/v1alpha1 +kind: NonAdminBackup +... +status: + conditions: + - lastTransitionTime: "2025-02-20T10:13:00Z" + message: 'NonAdminBackupStorageLocation not found in the namespace: NonAdminBackupStorageLocation.oadp.openshift.io + "nabsl2" not found' + reason: InvalidBackupSpec + status: "False" + type: Accepted + phase: BackingOff +---- + +.Solution + +Use the NABSL that belongs to the same namespace that you are trying to back up. + +In this scenario, you must use `nabsl-1` in the NAB CR to back up `namespace-1`. + \ No newline at end of file diff --git a/modules/oadp-self-service-troubleshooting.adoc b/modules/oadp-self-service-troubleshooting.adoc new file mode 100644 index 000000000000..5fdf9ec3a95a --- /dev/null +++ b/modules/oadp-self-service-troubleshooting.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// + +:_mod-docs-content-type: PROCEDURE +[id="oadp-self-service-troubleshooting_{context}"] += Troubleshooting {oadp-short} Self-Service + +.Error `pods is forbidden` + +If you are a non-admin user trying to access a namespace that you do not have access to, you get the following error: + +[source, terminal] +---- +Error from server (Forbidden): pods is forbidden: User "nac-user" cannot list resource "pods" in API group "" in the namespace "openshift-adp" +---- + +The cluster administrator has not authorized the non-admin user to access the namespace. + +.Solution + +The cluster administrator must authorize the non-admin user to access the namespace. + diff --git a/modules/oadp-self-service-unsupported-features.adoc b/modules/oadp-self-service-unsupported-features.adoc new file mode 100644 index 000000000000..629261b756d4 --- /dev/null +++ b/modules/oadp-self-service-unsupported-features.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service.adoc + +:_mod-docs-content-type: CONCEPT +[id="oadp-self-service-unsupported-features_{context}"] += {oadp-short} Self-Service unsupported features + +The following features are not supported by {oadp-short} Self-Service: + +* Cross cluster backup and restore, or migrations are not supported. These {oadp-short} operations are supported for the cluster administrator. + +* A namespace `admin` user cannot create a `VolumeSnapshotLocation` (VSL) CR. The cluster administrator creates and configures the VSL in the `DataProtectionApplication` (DPA) CR for a namespace `admin` user. + +* The `ResourceModifiers` CR and volume policies are not supported for a namespace `admin` user. + +* A namespace `admin` user can request backup or restore logs by using the `NonAdminDownloadRequest` CR, only if the backup or restore is created by a user through the `NonAdminBackupStorageLocation` CR and not the cluster-wide default backup storage location. + +* To ensure secure backup and restore, {oadp-short} Self-Service automatically excludes the following CRs from being backed up or restored: + +** `NonAdminBackup` +** `NonAdminRestore` +** `NonAdminBackupStorageLocation` +** `SecurityContextConstraints` +** `ClusterRole` +** `ClusterRoleBinding` +** `CustomResourceDefinition` +** `PriorityClasses` +** `VirtualMachineClusterInstanceTypes` +** `VirtualMachineClusterPreferences` \ No newline at end of file