Skip to content

OADP-4005: Enhance documentation for OADP CloudStorage API, including installation instructions via OpenShift web console and provider-specific configurations for AWS, Azure, and GCP. #1925

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: oadp-dev
Choose a base branch
from
+556 −401
Open

OADP-4005: Enhance documentation for OADP CloudStorage API, including installation instructions via OpenShift web console and provider-specific configurations for AWS, Azure, and GCP. #1925

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
49e25e5
Enhance documentation for OADP CloudStorage API, including installati…
kaovilai Aug 21, 2025
30cfb9b
Remove redundant cloud provider service account annotations from docs
kaovilai Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 35 additions & 65 deletions docs/config/aws/oadp-aws-sts-cloud-authentication.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,20 +205,43 @@ oc annotate serviceaccount openshift-adp-controller-manager -n openshift-adp \
eks.amazonaws.com/role-arn="${ROLE_ARN}" --overwrite
----

[id="oadp-aws-console-installation_{context}"]
== Installing OADP Operator via OpenShift Web Console

When installing the OADP operator through the OpenShift web console with tokenized authentication support, you will be presented with cloud provider-specific configuration fields.

[NOTE]
====
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.
====

.Console Installation Fields for AWS

During operator installation, the web console will display the following field:

*role ARN*::
**Field Label:** "role ARN"
+
**Help Text:** "The role ARN required for the operator to access the cloud API."
+
**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`).

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}`.

[id="oadp-aws-cloud-storage-api_{context}"]
== Alternative: Using Cloud Storage API for Automated Bucket Management

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.
Instead of manually creating S3 buckets, you can use the OADP CloudStorage API to automatically manage bucket creation and configuration.

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

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

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

. Create a CloudStorage resource instead of manually creating buckets:
+
[source,yaml]
----
cat <<EOF | oc apply -f -
Expand All @@ -234,12 +257,11 @@ spec:
creationSecret:
name: cloud-credentials-aws
key: credentials # Required key name for AWS provider
creationPolicy: CreateIfNotExists
EOF
----

. Create the DataProtectionApplication with Cloud Storage API reference:
+
Then configure your DataProtectionApplication to use the CloudStorage resource:

[source,yaml]
----
cat <<EOF | oc apply -f -
Expand All @@ -258,7 +280,6 @@ spec:
backupLocations:
- name: default
bucket:
# Reference the CloudStorage resource instead of direct bucket
cloudStorageRef:
name: aws-backup-storage
prefix: velero
Expand All @@ -280,16 +301,10 @@ spec:
EOF
----

. Verify the CloudStorage resource status:
+
[source,bash]
----
oc get cloudstorage aws-backup-storage -n openshift-adp -o yaml
oc describe cloudstorage aws-backup-storage -n openshift-adp
----
.AWS-Specific Verification

Verify the S3 bucket was created:

. Wait for bucket creation and verify:
+
[source,bash]
----
# Check if bucket was created in S3
Expand All @@ -299,51 +314,6 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
aws s3api get-bucket-policy --bucket ${VELERO_BUCKET_NAME}
----

. Monitor the CloudStorage controller logs:
+
[source,bash]
----
# Check operator logs for CloudStorage operations
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage

# Check for AWS-specific operations
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i aws
----

[WARNING]
====
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:

[source,bash]
----
# Add deletion annotation before attempting to delete
oc annotate cloudstorage aws-backup-storage -n openshift-adp \
oadp.openshift.io/cloudstorage-delete=true --overwrite

# Then delete the CloudStorage resource
oc delete cloudstorage aws-backup-storage -n openshift-adp
----

Without this annotation, the deletion will hang indefinitely as the finalizer prevents removal.

Alternatively, if you want to remove the CloudStorage resource from OpenShift without deleting the S3 bucket in AWS, you can manually remove the finalizer:

[source,bash]
----
# Remove finalizer to delete CloudStorage CR without deleting the S3 bucket
oc patch cloudstorage aws-backup-storage -n openshift-adp --type json \
-p='[{"op": "remove", "path": "/metadata/finalizers"}]'
----
====

The CloudStorage API will automatically:

* Create the S3 bucket if it doesn't exist (with `creationPolicy: CreateIfNotExists`)
* Configure appropriate bucket policies for the IAM role
* Set up regional configuration based on the specified region
* Handle authentication through the referenced credential secret
* Protect bucket resources with finalizers to prevent accidental deletion

== Standard Configuration (Manual Bucket Creation)

. Create the DataProtectionApplication configuration for manual bucket setup:
Expand Down
43 changes: 21 additions & 22 deletions docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,17 +260,17 @@ echo "Created and configured S3 bucket: ${VELERO_BUCKET_NAME}"
[id="oadp-rosa-cloud-storage-api_{context}"]
== Alternative: Using Cloud Storage API for Automated Bucket Management

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

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

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

.Procedure for Cloud Storage API
For ROSA, create a CloudStorage resource with the following configuration:

. Create a CloudStorage resource for ROSA:
+
[source,yaml]
----
cat <<EOF | oc apply -f -
Expand All @@ -286,12 +286,11 @@ spec:
creationSecret:
name: cloud-credentials-aws
key: credentials
creationPolicy: CreateIfNotExists
EOF
----

. Create the DataProtectionApplication with Cloud Storage API reference:
+
Then configure your DataProtectionApplication with ROSA-specific settings:

[source,yaml]
----
cat <<EOF | oc apply -f -
Expand Down Expand Up @@ -332,21 +331,12 @@ spec:
EOF
----

. Verify the CloudStorage resource status:
+
[source,bash]
----
oc get cloudstorage rosa-backup-storage -n openshift-adp -o yaml
oc describe cloudstorage rosa-backup-storage -n openshift-adp
----
.ROSA-Specific Verification

Verify the S3 bucket was created:

. Monitor CloudStorage operations:
+
[source,bash]
----
# Check CloudStorage controller logs
oc logs -n openshift-adp deployment/oadp-operator-controller-manager | grep -i cloudstorage

# Verify S3 bucket creation
aws s3 ls s3://${VELERO_BUCKET_NAME}/
----
Expand All @@ -358,6 +348,15 @@ aws s3 ls s3://${VELERO_BUCKET_NAME}/
[NOTE]
====
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.

When installing through the web console with tokenized authentication support, you will see the following field:

**role ARN**
- **Field Label:** "role ARN"
- **Help Text:** "The role ARN required for the operator to access the cloud API."
- **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`).

This corresponds to the IAM role created in the prerequisite steps with the format `arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE_NAME}`.
====

. Create the DataProtectionApplication for standard ROSA STS setup:
Expand Down
Loading