Skip to content

Commit c32b7ad

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 c32b7ad

6 files changed

+448
-377
lines changed

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

Lines changed: 35 additions & 64 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, create a CloudStorage resource with the following configuration:
219244

220-
. Create a CloudStorage resource instead of manually creating buckets:
221-
+
222245
[source,yaml]
223246
----
224247
cat <<EOF | oc apply -f -
@@ -238,8 +261,8 @@ spec:
238261
EOF
239262
----
240263

241-
. Create the DataProtectionApplication with Cloud Storage API reference:
242-
+
264+
Then configure your DataProtectionApplication to use the CloudStorage resource:
265+
243266
[source,yaml]
244267
----
245268
cat <<EOF | oc apply -f -
@@ -258,7 +281,6 @@ spec:
258281
backupLocations:
259282
- name: default
260283
bucket:
261-
# Reference the CloudStorage resource instead of direct bucket
262284
cloudStorageRef:
263285
name: aws-backup-storage
264286
prefix: velero
@@ -280,16 +302,10 @@ spec:
280302
EOF
281303
----
282304

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-
----
305+
.AWS-Specific Verification
306+
307+
Verify the S3 bucket was created:
290308

291-
. Wait for bucket creation and verify:
292-
+
293309
[source,bash]
294310
----
295311
# Check if bucket was created in S3
@@ -299,51 +315,6 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
299315
aws s3api get-bucket-policy --bucket ${VELERO_BUCKET_NAME}
300316
----
301317

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-
347318
== Standard Configuration (Manual Bucket Creation)
348319

349320
. Create the DataProtectionApplication configuration for manual bucket setup:

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

Lines changed: 21 additions & 21 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 -
@@ -290,8 +290,8 @@ spec:
290290
EOF
291291
----
292292

293-
. Create the DataProtectionApplication with Cloud Storage API reference:
294-
+
293+
Then configure your DataProtectionApplication with ROSA-specific settings:
294+
295295
[source,yaml]
296296
----
297297
cat <<EOF | oc apply -f -
@@ -332,21 +332,12 @@ spec:
332332
EOF
333333
----
334334

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-
----
335+
.ROSA-Specific Verification
336+
337+
Verify the S3 bucket was created:
342338

343-
. Monitor CloudStorage operations:
344-
+
345339
[source,bash]
346340
----
347-
# Check CloudStorage controller logs
348-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage
349-
350341
# Verify S3 bucket creation
351342
aws s3 ls s3://${VELERO_BUCKET_NAME}/
352343
----
@@ -358,6 +349,15 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
358349
[NOTE]
359350
====
360351
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.
352+
353+
When installing through the web console with tokenized authentication support, you will see the following field:
354+
355+
**role ARN**
356+
- **Field Label:** "role ARN"
357+
- **Help Text:** "The role ARN required for the operator to access the cloud API."
358+
- **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`).
359+
360+
This corresponds to the IAM role created in the prerequisite steps with the format `arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE_NAME}`.
361361
====
362362

363363
. Create the DataProtectionApplication for standard ROSA STS setup:

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

Lines changed: 59 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -184,20 +184,57 @@ oc annotate serviceaccount openshift-adp-controller-manager -n openshift-adp \
184184
azure.workload.identity/client-id="$IDENTITY_CLIENT_ID" --overwrite
185185
----
186186

187+
[id="oadp-azure-console-installation_{context}"]
188+
== Installing OADP Operator via OpenShift Web Console
189+
190+
When installing the OADP operator through the OpenShift web console with tokenized authentication support, you will be presented with cloud provider-specific configuration fields.
191+
192+
[NOTE]
193+
====
194+
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.
195+
====
196+
197+
.Console Installation Fields for Azure
198+
199+
During operator installation, the web console will display the following fields:
200+
201+
*Azure Client ID*::
202+
**Field Label:** "Azure Client ID"
203+
+
204+
**Help Text:** "The Azure Client ID required for the operator to access the cloud API."
205+
+
206+
**Value to Enter:** Use the `IDENTITY_CLIENT_ID` value from the prerequisite setup steps above.
207+
208+
*Azure Tenant ID*::
209+
**Field Label:** "Azure Tenant ID"
210+
+
211+
**Help Text:** "The Azure Tenant ID required for the operator to access the cloud API."
212+
+
213+
**Value to Enter:** Use the `AZURE_TENANT_ID` value from the prerequisite setup steps above.
214+
215+
*Azure Subscription ID*::
216+
**Field Label:** "Azure Subscription ID"
217+
+
218+
**Help Text:** "The Azure Subscription ID required for the operator to access the cloud API."
219+
+
220+
**Value to Enter:** Use the `AZURE_SUBSCRIPTION_ID` value from the prerequisite setup steps above.
221+
222+
These fields correspond to the managed identity and Azure subscription information you configured in the prerequisite steps for Microsoft Entra Workload ID authentication.
223+
187224
[id="oadp-azure-cloud-storage-api_{context}"]
188225
== Alternative: Using Cloud Storage API for Automated Container Management
189226

190-
Instead of manually creating storage containers, you can use the OADP Cloud Storage API to automatically manage container creation and configuration. This approach requires OADP operator version with Cloud Storage API support.
227+
Instead of manually creating storage containers, you can use the OADP CloudStorage API to automatically manage container creation and configuration.
191228

192-
.Prerequisites for Cloud Storage API
229+
[NOTE]
230+
====
231+
For comprehensive documentation on the CloudStorage API, including detailed configuration options, troubleshooting, and advanced usage, see link:../oadp-cloudstorage-api.html[OADP CloudStorage API].
232+
====
193233

194-
* OADP operator with Cloud Storage API functionality enabled
195-
* The same Microsoft Entra Workload ID configuration as above
234+
.Azure-Specific CloudStorage Configuration
196235

197-
.Procedure for Cloud Storage API
236+
For Azure, create a CloudStorage resource with the following configuration:
198237

199-
. Create a CloudStorage resource instead of manually creating containers:
200-
+
201238
[source,yaml]
202239
----
203240
cat <<EOF | oc apply -f -
@@ -218,8 +255,8 @@ spec:
218255
EOF
219256
----
220257

221-
. Create the DataProtectionApplication with Cloud Storage API reference:
222-
+
258+
Then configure your DataProtectionApplication to use the CloudStorage resource:
259+
223260
[source,yaml]
224261
----
225262
cat <<EOF | oc apply -f -
@@ -237,15 +274,19 @@ spec:
237274
- csi
238275
backupLocations:
239276
- name: default
240-
bucket:
241-
# Reference the CloudStorage resource instead of direct container
242-
cloudStorageRef:
243-
name: azure-backup-storage
244-
prefix: velero
277+
velero:
278+
provider: azure
279+
default: true
245280
credential:
246281
name: cloud-credentials-azure
247282
key: azurekey
248-
default: true
283+
objectStorage:
284+
cloudStorageRef:
285+
name: azure-backup-storage
286+
prefix: velero
287+
config:
288+
resourceGroup: ${CLUSTER_RESOURCE_GROUP}
289+
subscriptionId: ${AZURE_SUBSCRIPTION_ID}
249290
snapshotLocations:
250291
- name: default
251292
velero:
@@ -259,16 +300,10 @@ spec:
259300
EOF
260301
----
261302

262-
. Verify the CloudStorage resource status:
263-
+
264-
[source,bash]
265-
----
266-
oc get cloudstorage azure-backup-storage -n openshift-adp -o yaml
267-
oc describe cloudstorage azure-backup-storage -n openshift-adp
268-
----
303+
.Azure-Specific Verification
304+
305+
Verify the storage container was created:
269306

270-
. Wait for container creation and verify:
271-
+
272307
[source,bash]
273308
----
274309
# Check if container was created in Azure Storage
@@ -278,51 +313,6 @@ az storage container list --account-name ${STORAGE_ACCOUNT_NAME} --auth-mode log
278313
az storage container show --name ${CONTAINER_NAME} --account-name ${STORAGE_ACCOUNT_NAME} --auth-mode login
279314
----
280315

281-
. Monitor the CloudStorage controller logs:
282-
+
283-
[source,bash]
284-
----
285-
# Check operator logs for CloudStorage operations
286-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage
287-
288-
# Check for Azure-specific operations
289-
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i azure
290-
----
291-
292-
[WARNING]
293-
====
294-
CloudStorage resources are protected by a finalizer (`oadp.openshift.io/bucket-protection`) to prevent accidental deletion of containers containing backup data. To delete a CloudStorage resource, you must first add the deletion annotation:
295-
296-
[source,bash]
297-
----
298-
# Add deletion annotation before attempting to delete
299-
oc annotate cloudstorage azure-backup-storage -n openshift-adp \
300-
oadp.openshift.io/cloudstorage-delete=true --overwrite
301-
302-
# Then delete the CloudStorage resource
303-
oc delete cloudstorage azure-backup-storage -n openshift-adp
304-
----
305-
306-
Without this annotation, the deletion will hang indefinitely as the finalizer prevents removal.
307-
308-
Alternatively, if you want to remove the CloudStorage resource from OpenShift without deleting the Azure storage container, you can manually remove the finalizer:
309-
310-
[source,bash]
311-
----
312-
# Remove finalizer to delete CloudStorage CR without deleting the Azure container
313-
oc patch cloudstorage azure-backup-storage -n openshift-adp --type json \
314-
-p='[{"op": "remove", "path": "/metadata/finalizers"}]'
315-
----
316-
====
317-
318-
The CloudStorage API will automatically:
319-
320-
* Create the storage container if it doesn't exist (with `creationPolicy: CreateIfNotExists`)
321-
* Configure appropriate access permissions for the managed identity
322-
* Handle authentication through the referenced credential secret
323-
* Manage container lifecycle and cleanup operations
324-
* Protect container resources with finalizers to prevent accidental deletion
325-
326316
== Standard Configuration (Manual Container Creation)
327317

328318
. Create the DataProtectionApplication configuration for manual container setup:

0 commit comments

Comments
 (0)