From e567492a089635904e20a15889945d99acda2bc3 Mon Sep 17 00:00:00 2001
From: Tiger Kaovilai <tkaovila@redhat.com>
Date: Mon, 15 Sep 2025 17:51:38 -0400
Subject: [PATCH] DNM: aws sts docs

Signed-off-by: Tiger Kaovilai <tkaovila@redhat.com>
---
 .../oadp-aws-sts-cloud-authentication.adoc    | 113 +++++-------------
 .../oadp-rosa-sts-cloud-authentication.adoc   |  43 ++++---
 2 files changed, 53 insertions(+), 103 deletions(-)

diff --git a/docs/config/aws/oadp-aws-sts-cloud-authentication.adoc b/docs/config/aws/oadp-aws-sts-cloud-authentication.adoc
index a09b888cb18..a70a32f93ab 100644
--- a/docs/config/aws/oadp-aws-sts-cloud-authentication.adoc
+++ b/docs/config/aws/oadp-aws-sts-cloud-authentication.adoc
@@ -194,31 +194,43 @@ echo "Role ARN: $ROLE_ARN"
 oc create namespace openshift-adp
 ----
 
-. Annotate the service accounts to use AWS STS:
+[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"
 +
-[source,bash]
-----
-oc annotate serviceaccount velero -n openshift-adp \
-    eks.amazonaws.com/role-arn="${ROLE_ARN}" --overwrite
+**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`).
 
-oc annotate serviceaccount openshift-adp-controller-manager -n openshift-adp \
-    eks.amazonaws.com/role-arn="${ROLE_ARN}" --overwrite
-----
+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 -
@@ -234,12 +246,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 -
@@ -258,7 +269,6 @@ spec:
   backupLocations:
     - name: default
       bucket:
-        # Reference the CloudStorage resource instead of direct bucket
         cloudStorageRef:
           name: aws-backup-storage
         prefix: velero
@@ -280,16 +290,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
@@ -299,51 +303,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:
@@ -397,14 +356,6 @@ EOF
 oc get pods -n openshift-adp
 ----
 
-. Check that the service accounts have the correct annotations:
-+
-[source,bash]
-----
-oc get sa velero -n openshift-adp -o yaml | grep -A5 annotations
-oc get sa openshift-adp-controller-manager -n openshift-adp -o yaml | grep -A5 annotations
-----
-
 . Verify the AWS IAM role trust relationships:
 +
 [source,bash]
diff --git a/docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc b/docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc
index b2aabc4eda9..940e8460bbd 100644
--- a/docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc
+++ b/docs/config/aws/oadp-rosa-sts-cloud-authentication.adoc
@@ -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 -
@@ -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 -
@@ -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}/
 ----
@@ -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: