Skip to content

Commit bdd6171

Browse files
kaovilaikaovilai
committed
Enhance documentation for OADP CloudStorage API, including installation instructions via OpenShift web console and provider-specific configurations for AWS, Azure, and GCP.
Signed-off-by: Tiger Kaovilai <[email protected]>
1 parent 455c40a commit bdd6171

6 files changed

+561
-377
lines changed

‎docs/config/aws/oadp-aws-sts-cloud-authentication.adoc

Lines changed: 35 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -205,20 +205,43 @@ oc annotate serviceaccount openshift-adp-controller-manager -n openshift-adp \
205205
eks.amazonaws.com/role-arn="${ROLE_ARN}" --overwrite
206206
----
207207
208+
[id="oadp-aws-console-installation_{context}"]
209+
== Installing OADP Operator via OpenShift Web Console
210+
211+
When installing the OADP operator through the OpenShift web console with tokenized authentication support, you will be presented with cloud provider-specific configuration fields.
212+
213+
[NOTE]
214+
====
215+
For OpenShift 4.15 and later, the web console supports tokenized authentication during operator installation, allowing you to provide cloud credentials directly through the installation form.
216+
====
217+
218+
.Console Installation Fields for AWS
219+
220+
During operator installation, the web console will display the following field:
221+
222+
*role ARN*::
223+
**Field Label:** "role ARN"
224+
+
225+
**Help Text:** "The role ARN required for the operator to access the cloud API."
226+
+
227+
**Value to Enter:** Use the `ROLE_ARN` value from the prerequisite setup steps above (e.g., `arn:aws:iam::123456789012:role/openshift-adp-controller-manager`).
228+
229+
This field corresponds to the IAM role you created in the prerequisite steps. The role ARN format is `arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE_NAME}`.
230+
208231
[id="oadp-aws-cloud-storage-api_{context}"]
209232
== Alternative: Using Cloud Storage API for Automated Bucket Management
210233

211-
Instead of manually creating S3 buckets, you can use the OADP Cloud Storage API to automatically manage bucket creation and configuration. This approach requires OADP operator version with Cloud Storage API support.
234+
Instead of manually creating S3 buckets, you can use the OADP CloudStorage API to automatically manage bucket creation and configuration.
212235

213-
.Prerequisites for Cloud Storage API
236+
[NOTE]
237+
====
238+
For comprehensive documentation on the CloudStorage API, including detailed configuration options, troubleshooting, and advanced usage, see link:../oadp-cloudstorage-api.html[OADP CloudStorage API].
239+
====
214240

215-
* OADP operator with Cloud Storage API functionality enabled
216-
* The same AWS STS configuration as above
241+
.AWS-Specific CloudStorage Configuration
217242

218-
.Procedure for Cloud Storage API
243+
For AWS with STS authentication, create a CloudStorage resource using the variables from the STS setup above:
219244

220-
. Create a CloudStorage resource instead of manually creating buckets:
221-
+
222245
[source,yaml]
223246
----
224247
cat <<EOF | oc apply -f -
@@ -234,12 +257,11 @@ spec:
234257
creationSecret:
235258
name: cloud-credentials-aws
236259
key: credentials # Required key name for AWS provider
237-
creationPolicy: CreateIfNotExists
238260
EOF
239261
----
240262

241-
. Create the DataProtectionApplication with Cloud Storage API reference:
242-
+
263+
Then configure your DataProtectionApplication to use the CloudStorage resource:
264+
243265
[source,yaml]
244266
----
245267
cat <<EOF | oc apply -f -
@@ -258,7 +280,6 @@ spec:
258280
backupLocations:
259281
- name: default
260282
bucket:
261-
# Reference the CloudStorage resource instead of direct bucket
262283
cloudStorageRef:
263284
name: aws-backup-storage
264285
prefix: velero
@@ -280,16 +301,10 @@ spec:
280301
EOF
281302
----
282303

283-
. Verify the CloudStorage resource status:
284-
+
285-
[source,bash]
286-
----
287-
oc get cloudstorage aws-backup-storage -n openshift-adp -o yaml
288-
oc describe cloudstorage aws-backup-storage -n openshift-adp
289-
----
304+
.AWS-Specific Verification
305+
306+
Verify the S3 bucket was created:
290307

291-
. Wait for bucket creation and verify:
292-
+
293308
[source,bash]
294309
----
295310
# Check if bucket was created in S3
@@ -299,51 +314,6 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
299314
aws s3api get-bucket-policy --bucket ${VELERO_BUCKET_NAME}
300315
----
301316

302-
. Monitor the CloudStorage controller logs:
303-
+
304-
[source,bash]
305-
----
306-
# Check operator logs for CloudStorage operations
307-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage
308-
309-
# Check for AWS-specific operations
310-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i aws
311-
----
312-
313-
[WARNING]
314-
====
315-
CloudStorage resources are protected by a finalizer (`oadp.openshift.io/bucket-protection`) to prevent accidental deletion of buckets containing backup data. To delete a CloudStorage resource, you must first add the deletion annotation:
316-
317-
[source,bash]
318-
----
319-
# Add deletion annotation before attempting to delete
320-
oc annotate cloudstorage aws-backup-storage -n openshift-adp \
321-
oadp.openshift.io/cloudstorage-delete=true --overwrite
322-
323-
# Then delete the CloudStorage resource
324-
oc delete cloudstorage aws-backup-storage -n openshift-adp
325-
----
326-
327-
Without this annotation, the deletion will hang indefinitely as the finalizer prevents removal.
328-
329-
Alternatively, if you want to remove the CloudStorage resource from OpenShift without deleting the S3 bucket in AWS, you can manually remove the finalizer:
330-
331-
[source,bash]
332-
----
333-
# Remove finalizer to delete CloudStorage CR without deleting the S3 bucket
334-
oc patch cloudstorage aws-backup-storage -n openshift-adp --type json \
335-
-p='[{"op": "remove", "path": "/metadata/finalizers"}]'
336-
----
337-
====
338-
339-
The CloudStorage API will automatically:
340-
341-
* Create the S3 bucket if it doesn't exist (with `creationPolicy: CreateIfNotExists`)
342-
* Configure appropriate bucket policies for the IAM role
343-
* Set up regional configuration based on the specified region
344-
* Handle authentication through the referenced credential secret
345-
* Protect bucket resources with finalizers to prevent accidental deletion
346-
347317
== Standard Configuration (Manual Bucket Creation)
348318

349319
. Create the DataProtectionApplication configuration for manual bucket setup:

‎docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -260,17 +260,17 @@ echo "Created and configured S3 bucket: ${VELERO_BUCKET_NAME}"
260260
[id="oadp-rosa-cloud-storage-api_{context}"]
261261
== Alternative: Using Cloud Storage API for Automated Bucket Management
262262

263-
The OADP Cloud Storage API can automatically manage S3 bucket creation and configuration for ROSA STS clusters.
263+
The OADP CloudStorage API can automatically manage S3 bucket creation and configuration for ROSA STS clusters.
264264

265-
.Prerequisites for Cloud Storage API
265+
[NOTE]
266+
====
267+
For comprehensive documentation on the CloudStorage API, including detailed configuration options, troubleshooting, and advanced usage, see link:../oadp-cloudstorage-api.html[OADP CloudStorage API].
268+
====
266269

267-
* OADP operator with Cloud Storage API functionality enabled
268-
* The same ROSA STS configuration as above
270+
.ROSA-Specific CloudStorage Configuration
269271

270-
.Procedure for Cloud Storage API
272+
For ROSA, create a CloudStorage resource with the following configuration:
271273

272-
. Create a CloudStorage resource for ROSA:
273-
+
274274
[source,yaml]
275275
----
276276
cat <<EOF | oc apply -f -
@@ -286,12 +286,11 @@ spec:
286286
creationSecret:
287287
name: cloud-credentials-aws
288288
key: credentials
289-
creationPolicy: CreateIfNotExists
290289
EOF
291290
----
292291

293-
. Create the DataProtectionApplication with Cloud Storage API reference:
294-
+
292+
Then configure your DataProtectionApplication with ROSA-specific settings:
293+
295294
[source,yaml]
296295
----
297296
cat <<EOF | oc apply -f -
@@ -332,21 +331,12 @@ spec:
332331
EOF
333332
----
334333

335-
. Verify the CloudStorage resource status:
336-
+
337-
[source,bash]
338-
----
339-
oc get cloudstorage rosa-backup-storage -n openshift-adp -o yaml
340-
oc describe cloudstorage rosa-backup-storage -n openshift-adp
341-
----
334+
.ROSA-Specific Verification
335+
336+
Verify the S3 bucket was created:
342337

343-
. Monitor CloudStorage operations:
344-
+
345338
[source,bash]
346339
----
347-
# Check CloudStorage controller logs
348-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage
349-
350340
# Verify S3 bucket creation
351341
aws s3 ls s3://${VELERO_BUCKET_NAME}/
352342
----
@@ -358,6 +348,15 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
358348
[NOTE]
359349
====
360350
For OpenShift 4.15 and later, you can provide the role ARN directly during operator installation through the web console, which will automatically create the necessary credentials secret.
351+
352+
When installing through the web console with tokenized authentication support, you will see the following field:
353+
354+
**role ARN**
355+
- **Field Label:** "role ARN"
356+
- **Help Text:** "The role ARN required for the operator to access the cloud API."
357+
- **Value to Enter:** Use the `ROLE_ARN` value from the prerequisite setup steps above (e.g., `arn:aws:iam::123456789012:role/your-cluster-openshift-oadp-aws-cloud-credentials`).
358+
359+
This corresponds to the IAM role created in the prerequisite steps with the format `arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE_NAME}`.
361360
====
362361

363362
. Create the DataProtectionApplication for standard ROSA STS setup:

0 commit comments

Comments
 (0)