Skip to content

Commit 5935ff1

Browse files
shdeshpa07shdeshpa07
authored
Merge pull request #97594 from shdeshpa07/OADP-DPT
Data protection test feature docs
2 parents c18ac05 + c33c64d commit 5935ff1

File tree

9 files changed

+437
-0
lines changed

9 files changed

+437
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3815,6 +3815,8 @@ Topics:
38153815
File: backup-and-restore-cr-issues
38163816
- Name: Restic issues
38173817
File: restic-issues
3818+
- Name: OADP Data protection test
3819+
File: oadp-data-protection-test
38183820
- Name: Using the must-gather tool
38193821
File: using-the-must-gather-tool
38203822
- Name: OADP monitoring

‎backup_and_restore/application_backup_and_restore/troubleshooting/oadp-data-protection-test.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="oadp-data-protection-test"]
3+
= OADP Data protection test
4+
:toc:
5+
6+
include::_attributes/common-attributes.adoc[]
7+
:context: oadp-data-protection-test
8+
9+
10+
[role="_abstract"]
11+
The `DataProtectionTest` (DPT) is a custom resource (CR) that provides a framework to validate your {oadp-short} configuration. The DPT CR checks and reports information for the following parameters:
12+
13+
* The upload performance of the backups to the object storage.
14+
* The CSI snapshot readiness for persistent volume claims.
15+
* The storage bucket configuration, such as encryption and versioning.
16+
17+
Using this information in the DPT CR, you can ensure that your data protection environment is properly configured and performing according to the set configuration.
18+
19+
include::modules/oadp-dpt-spec-fields.adoc[leveloffset=+1]
20+
21+
include::modules/oadp-dpt-status-fields.adoc[leveloffset=+1]
22+
23+
include::modules/using-data-protection-test.adoc[leveloffset=+1]
24+
25+
include::modules/oadp-dpt-use-case-bsl-spec.adoc[leveloffset=+1]
26+
27+
include::modules/oadp-dpt-use-case-azure.adoc[leveloffset=+1]
28+
29+
include::modules/oadp-troubleshooting-dpt.adoc[leveloffset=+1]

‎backup_and_restore/application_backup_and_restore/troubleshooting/troubleshooting.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ You can troubleshoot OADP issues by using the following methods:
2626
2727
* Use the available xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#oadp-timeouts[OADP timeouts] to reduce errors, retries, or failures.
2828
29+
* Run the xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-data-protection-test.adoc#oadp-data-protection-test[`DataProtectionTest` (DPT)] custom resource to verify your backup storage bucket configuration and check the CSI snapshot readiness for persistent volume claims.
30+
2931
* Collect logs and CR information by using the xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc#using-the-must-gather-tool[`must-gather` tool].
3032
3133
* Monitor and analyze the workload performance with the help of xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc#oadp-monitoring[OADP monitoring].

‎modules/oadp-dpt-spec-fields.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * backup_and_restore/application_backup_and_restore/oadp-data-protection-test.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="oadp-dpt-spec_{context}"]
7+
= OADP DataProtectionTest CR specification fields
8+
9+
[role="_abstract"]
10+
You can configure the following specification fields in the `DataProtectionTest` (DPT) custom resource (CR).
11+
12+
.DPT CR spec fields
13+
|===
14+
|Field |Type |Description
15+
16+
| `backupLocationName` | string | Name of the `BackupStorageLocation` CR configured in the `DataProtectionApplication` (DPA) CR.
17+
| `backupLocationSpec` | object | Inline specification of the `BackupStorageLocation` CR.
18+
| `uploadSpeedTestConfig` | object | Configuration to run an upload speed test to the object storage.
19+
| `csiVolumeSnapshotTestConfigs` | list | List of persistent volume claims to take a snapshot of and to verify the snapshot readiness.
20+
| `forceRun` | boolean | Re-run the DPT CR even if status is `Complete` or `Failed`.
21+
| `skipTLSVerify` | boolean | Bypasses the TLS certificate validation if set to `true`.
22+
23+
|===

‎modules/oadp-dpt-status-fields.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * backup_and_restore/application_backup_and_restore/oadp-data-protection-test.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="oadp-dpt-status_{context}"]
7+
= OADP DataProtectionTest CR status fields
8+
9+
[role="_abstract"]
10+
You can review the status of the `DataProtectionTest` (DPT) custom resource (CR) by using the following status fields:
11+
12+
.DPT CR status fields
13+
|===
14+
|Field |Type |Description
15+
16+
| `phase` | string | Current phase of the DPT CR. Values are `InProgress`, `Complete`, or `Failed`.
17+
| `lastTested` | timestamp | The timestamp when the DPT CR was last run.
18+
| `uploadTest` | object | Results of the upload speed test.
19+
| `bucketMetadata` | object | Information about the storage bucket encryption and versioning.
20+
| `snapshotTests` | list | Snapshot test results for each persistent volume claim.
21+
| `snapshotSummary` | string | Aggregated pass/fail summary for snapshots. For example, `2/2 passed`.
22+
| `s3Vendor` | string | {aws-short} S3-compatible storage bucket vendors. For example, {aws-short}, MinIO, Ceph.
23+
| `errorMessage` | string | Error message if the DPT CR fails.
24+
25+
|===

‎modules/oadp-dpt-use-case-azure.adoc‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * backup_and_restore/application_backup_and_restore/oadp-data-protection-test.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oadp-dpt-use-case-azure_{context}"]
7+
= Running a data protection test on an Azure object storage
8+
9+
[role="_abstract"]
10+
If you are using {oadp-short} on an Azure object storage, you need to specify the Azure `STORAGE_ACCOUNT_ID` as part of the secret object. Use the following procedure to run a `DataProtectionTest` (DPT) custom resource (CR) on an Azure cluster.
11+
12+
13+
.Prerequisites
14+
15+
* You have logged in to the Azure cluster as a user with the `cluster-admin` role.
16+
* You have installed the OpenShift CLI (`oc`).
17+
* You have installed the {oadp-short} Operator.
18+
* You have configured a bucket to store the backups.
19+
* You have an application with persistent volume claims (PVCs) running in a separate namespace.
20+
21+
22+
.Procedure
23+
24+
. Add the `Storage Blob Data Contributor` role to Azure `storageAccount` object to avoid DPT run failure. Run the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ az role assignment create \
29+
--assignee "$AZURE_CLIENT_ID" \
30+
--role "Storage Blob Data Contributor" \
31+
--scope "/subscriptions/$AZURE_SUBSCRIPTION_ID/resourceGroups/$AZURE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/$AZURE_STORAGE_ACCOUNT_ID"
32+
----
33+
34+
. In your terminal, export the Azure parameters and create a secret credentials file with the parameters as shown in the following example.
35+
+
36+
To run the DPT CR on Azure, you need to specify the `STORAGE_ACCOUNT_ID` parameter in the secret credentials file.
37+
+
38+
[source,terminal]
39+
----
40+
AZURE_SUBSCRIPTION_ID=<subscription-id>
41+
AZURE_TENANT_ID=<tenant-id>
42+
AZURE_CLIENT_ID=<client-id>
43+
AZURE_CLIENT_SECRET=<client-secret>
44+
AZURE_RESOURCE_GROUP=<resource-group>
45+
AZURE_STORAGE_ACCOUNT_ID=<storage-account>
46+
----
47+
48+
. Create the `Secret` CR as shown in the following example:
49+
+
50+
[source,terminal]
51+
----
52+
$ oc create secret generic cloud-credentials-azure -n openshift-adp --from-file cloud=<credentials_file_path>
53+
----
54+
55+
. Create the `DataProtectionApplication` (DPA) CR by using the configuration shown in the following example:
56+
+
57+
[source,yaml]
58+
----
59+
apiVersion: oadp.openshift.io/v1alpha1
60+
kind: DataProtectionApplication
61+
metadata:
62+
name: ts-dpa
63+
namespace: openshift-adp
64+
spec:
65+
configuration:
66+
velero:
67+
defaultPlugins:
68+
- azure
69+
- openshift
70+
backupLocations:
71+
- velero:
72+
config:
73+
resourceGroup: oadp-....-b7q4-rg
74+
storageAccount: oadp...kb7q4
75+
subscriptionId: 53b8f5...fd54c8a
76+
credential:
77+
key: cloud
78+
name: cloud-credentials-azure # <1>
79+
provider: azure
80+
default: true
81+
objectStorage:
82+
bucket: <bucket_name>
83+
prefix: velero
84+
----
85+
<1> Specify the name of the `Secret` object. In this example, the name is `cloud-credentials-azure`.
86+
87+
. Create the DPT CR by specifying the name of backup storage location (BSL), `VolumeSnapshotClass` object, and the persistent volume claim details as shown in the following example:
88+
+
89+
[source,yaml]
90+
----
91+
apiVersion: oadp.openshift.io/v1alpha1
92+
kind: DataProtectionTest
93+
metadata:
94+
name: dpt-sample
95+
namespace: openshift-adp
96+
spec:
97+
backupLocationName: <bsl_name> # <1>
98+
uploadSpeedTestConfig:
99+
fileSize: 40MB
100+
timeout: 120s
101+
csiVolumeSnapshotTestConfigs:
102+
- snapshotClassName: csi-azuredisk-vsc # <2>
103+
timeout: 90s
104+
volumeSnapshotSource:
105+
persistentVolumeClaimName: mysql-data # <3>
106+
persistentVolumeClaimNamespace: ocp-mysql # <4>
107+
- snapshotClassName: csi-azuredisk-vsc
108+
timeout: 120s
109+
volumeSnapshotSource:
110+
persistentVolumeClaimName: mysql-data1
111+
persistentVolumeClaimNamespace: ocp-mysql
112+
----
113+
<1> Specify the name of the BSL.
114+
<2> The Azure snapshot class name.
115+
<3> The name of the persistent volume claim.
116+
<4> The name of the persistent volume claim namespace.
117+
118+
. Run the DPT CR to verify the snapshot readiness.

‎modules/oadp-dpt-use-case-bsl-spec.adoc‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * backup_and_restore/application_backup_and_restore/oadp-data-protection-test.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oadp-dpt-use-case-bsl-spec_{context}"]
7+
= Running a data protection test by configuring a backup storage location specification
8+
9+
[role="_abstract"]
10+
You can configure the `DataProtectionTest` (DPT) custom resource (CR) by specifying the backup storage location (BSL) specification instead of a BSL name. You then run the DPT CR to verify the Container Storage Initiative (CSI) snapshot readiness and the data upload performance to the storage bucket.
11+
12+
.Prerequisites
13+
14+
* You have logged in to the {product-title} cluster as a user with the `cluster-admin` role.
15+
* You have installed the OpenShift CLI (`oc`).
16+
* You have installed the {oadp-short} Operator.
17+
* You have created the `DataProtectionApplication` (DPA) CR.
18+
* You have configured a bucket to store the backups.
19+
* You have created the `Secret` object to access the bucket storage.
20+
* You have an application with persistent volume claims (PVCs) running in a separate namespace.
21+
22+
23+
.Procedure
24+
25+
. Create a manifest file for the DPT CR as shown in the example:
26+
+
27+
[source,yaml]
28+
----
29+
apiVersion: oadp.openshift.io/v1alpha1
30+
kind: DataProtectionTest
31+
metadata:
32+
name: dpt-sample
33+
namespace: openshift-adp
34+
spec:
35+
backupLocationSpec: # <1>
36+
provider: aws
37+
default: true
38+
objectStorage:
39+
bucket: sample-bucket # <2>
40+
prefix: velero
41+
config:
42+
region: us-east-1 # <3>
43+
profile: "default"
44+
insecureSkipTLSVerify: "true"
45+
s3Url: "https://s3.amazonaws.com/sample-bucket"
46+
credential: # <4>
47+
name: cloud-credentials
48+
key: cloud
49+
uploadSpeedTestConfig: # <5>
50+
fileSize: 50MB
51+
timeout: 120s
52+
csiVolumeSnapshotTestConfigs: # <6>
53+
- volumeSnapshotSource:
54+
persistentVolumeClaimName: mongo
55+
persistentVolumeClaimNamespace: mongo-persistent
56+
snapshotClassName: csi-snapclass
57+
timeout: 2m
58+
forceRun: true
59+
skipTLSVerify: true # <7>
60+
----
61+
<1> Configure the BSL spec by specifying details such as the cloud provider.
62+
<2> Specify the bucket name. In this example, the bucket name is `sample-bucket`.
63+
<3> Specify the cloud provider region.
64+
<4> Specify the cloud credentials for the storage bucket.
65+
<5> (Optional) Configure the `uploadSpeedTestConfig` object by setting the `fileSize` and `timeout` fields.
66+
<6> Configure the `csiVolumeSnapshotTestConfigs` object.
67+
<7> Set to `true` to skip the TLS certificate validation during the DPT CR run.
68+
69+
. Create the DPT CR by running the following command:
70+
+
71+
[source,terminal]
72+
----
73+
$ oc create -f <dpt_file_name> # <1>
74+
----
75+
<1> Specify the file name of the DPT manifest.
76+
77+
78+
.Verification
79+
80+
. Verify that the phase of the DPT CR is `Complete` by running the following command:
81+
+
82+
[source,terminal]
83+
----
84+
$ oc get dpt dpt-sample
85+
----
86+
+
87+
The example output is as following:
88+
+
89+
[source,terminal]
90+
----
91+
NAME PHASE LASTTESTED UPLOADSPEED(MBPS) ENCRYPTION VERSIONING SNAPSHOTS AGE
92+
dpt-sample Complete 17m 546 AES256 Enabled 2/2 passed 17m
93+
----

‎modules/oadp-troubleshooting-dpt.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * backup_and_restore/application_backup_and_restore/oadp-data-protection-test.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="oadp-troubleshooting-dpt_{context}"]
7+
= Troubleshooting the DataProtectionTest custom resource
8+
9+
[role="_abstract"]
10+
Use the following table to troubleshoot common issues when running the `DataProtectionTest` (DPT) custom resource (CR).
11+
12+
.DPT CR troubleshooting
13+
|===
14+
|Error |Reason |Solution
15+
16+
| DPT stuck in `InProgress` state | Bucket credentials or bucket access failure | Check `Secret` object, bucket permissions, and logs.
17+
| Upload test failed | Incorrect `Secret` object or S3 endpoint | Check the `BackupStorageLocation` object config and the access keys.
18+
| Snapshot tests fail | Incorrect configuration of CSI snapshot controller | Check the `VolumeSnapshotClass` object availability and the CSI driver logs.
19+
| Bucket encryption or versioning not populated | Cloud provider limitations | Not all object storage providers expose these fields consistently.
20+
21+
|===

0 commit comments

Comments
 (0)