quay · stevsmit · Jul 15, 2025 · Jul 10, 2025
diff --git a/modules/attributes.adoc b/modules/attributes.adoc
@@ -9,6 +9,7 @@
 :rhel: Red Hat Enterprise Linux (RHEL)
 :rhel-short: RHEL
 :ocp-y: 4.18
+:product-rosa: Red{nbsp}Hat OpenShift Service on AWS
 
 ifeval::["{productname}" == "Project Quay"]
 :upstream:

diff --git a/modules/config-fields-storage-aws.adoc b/modules/config-fields-storage-aws.adoc
@@ -34,7 +34,7 @@ DISTRIBUTED_STORAGE_PREFERENCE:
 # ...
 ----
 <1> The `S3Storage` storage driver should only be used for AWS S3 buckets. Note that this differs from general S3 access, where the RadosGW driver or other storage services can be used. For an example, see "Example B: Using RadosGW with general S3 access".
-<2> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
+<2> The Amazon Web Services region. Defaults to `us-east-1`.
 
 [id="config-fields-storage-aws-sts"]
 == Amazon Web Services STS S3 storage
@@ -64,7 +64,7 @@ DISTRIBUTED_STORAGE_PREFERENCE:
 <1> The unique Amazon Resource Name (ARN). 
 <2> The generated AWS S3 user access key.
 <3> The generated AWS S3 user secret key.
-<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
+<4> The Amazon Web Services region. Defaults to `us-east-1`.
 
 [id="aws-cloudfront-storage-example"]
 == AWS CloudFront storage

diff --git a/modules/configuring-aws-sts-quay.adoc b/modules/configuring-aws-sts-quay.adoc
@@ -1,125 +1,9 @@
-:_content-type: PROCEDURE
+:_content-type: CONCEPT
 [id="configuring-aws-sts-quay"]
 = Configuring AWS STS for {productname}
 
-Support for Amazon Web Services (AWS) Security Token Service (STS) is available for standalone {productname} deployments and {productname-ocp}. AWS STS is a web service for requesting temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users and for users that you authenticate, or _federated users_. This feature is useful for clusters using Amazon S3 as an object storage, allowing {productname} to use STS protocols to authenticate with Amazon S3, which can enhance the overall security of the cluster and help to ensure that access to sensitive data is properly authenticated and authorized. 
+Support for Amazon Web Services (AWS) Security Token Service (STS) is available for standalone {productname} deployments, {productname-ocp}, and Red Hat OpenShift Service on AWS (ROSA). AWS STS is a web service for requesting temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users and for users that you authenticate, or _federated users_. This feature is useful for clusters using Amazon S3 as an object storage, allowing {productname} to use STS protocols to authenticate with Amazon S3, which can enhance the overall security of the cluster and help to ensure that access to sensitive data is properly authenticated and authorized. 
 
-Configuring AWS STS is a multi-step process that requires creating an AWS IAM user, creating an S3 role, and configuring your {productname} `config.yaml` file to include the proper resources. 
+Configuring AWS STS for {ocp} or ROSA requires creating an AWS IAM user, creating an S3 role, and configuring your {productname} `config.yaml` file to include the proper resources.
 
-Use the following procedures to configure AWS STS for {productname}. 
-
-[id="creating-am-user"]
-== Creating an IAM user
-
-Use the following procedure to create an IAM user. 
-
-.Procedure
-
-. Log in to the Amazon Web Services (AWS) console and navigate to the Identity and Access Management (IAM) console. 
-
-. In the navigation pane, under *Access management* click *Users*. 
-
-. Click *Create User* and enter the following information:
-
-.. Enter a valid username, for example, `quay-user`. 
-
-.. For *Permissions options*, click *Add user to group*. 
-
-. On the *review and create* page, click *Create user*. You are redirected to the *Users* page.
-
-. Click the username, for example, *quay-user*. 
-
-. Copy the ARN of the user, for example, `arn:aws:iam::123492922789:user/quay-user`.
-
-. On the same page, click the *Security credentials* tab. 
-
-. Navigate to *Access keys*.
-
-. Click *Create access key*. 
-
-. On the *Access key best practices & alternatives* page, click *Command Line Interface (CLI)*, then, check the confirmation box. Then click *Next*. 
-
-. Optional. On the *Set description tag - optional* page, enter a description.
-
-. Click *Create access key*.
-
-. Copy and store the access key and the secret access key.
-+
-[IMPORTANT]
-====
-This is the only time that the secret access key can be viewed or downloaded. You cannot recover it later. However, you can create a new access key any time.
-====
-
-. Click *Done*.
-
-[id="creating-s3-role"]
-== Creating an S3 role
-
-Use the following procedure to create an S3 role for AWS STS. 
-
-.Prerequisites
-
-* You have created an IAM user and stored the access key and the secret access key.
-
-.Procedure
-
-. If you are not already, navigate to the IAM dashboard by clicking *Dashboard*. 
-
-. In the navigation pane, click *Roles* under *Access management*. 
-
-. Click *Create role*. 
-
-* Click *Custom Trust Policy*, which shows an editable JSON policy. By default, it shows the following information:
-+
-[source,json]
-----
-{
-	"Version": "2012-10-17",
-	"Statement": [
-		{
-			"Sid": "Statement1",
-			"Effect": "Allow",
-			"Principal": {},
-			"Action": "sts:AssumeRole"
-		}
-	]
-}
-----
-
-. Under the `Principal` configuration field, add your AWS ARN information. For example:
-+
-[source,json]
-----
-{
-    "Version": "2012-10-17",
-    "Statement": [
-   	 {
-   		 "Sid": "Statement1",
-   		 "Effect": "Allow",
-   		 "Principal": {
-   		 	"AWS": "arn:aws:iam::123492922789:user/quay-user"
-   		 },
-   		 "Action": "sts:AssumeRole"
-   	 }
-    ]
-}
-----
-
-. Click *Next*. 
-
-. On the *Add permissions* page, type `AmazonS3FullAccess` in the search box. Check the box to add that policy to the S3 role, then click *Next*. 
-
-. On the *Name, review, and create* page, enter the following information:
-
-.. Enter a role name, for example, `example-role`.
-
-.. Optional. Add a description.
-
-. Click the *Create role* button. You are navigated to the *Roles* page. Under *Role name*, the newly created S3 should be available.
-
-////
-[id="configuring-quay-operator-use-aws-sts"]
-== Configuring the {productname} to use AWS STS
-
-Depending on your deployment type, whether standalone or on {ocp}, you can use one of the following procedures to edit your `config.yaml` file to use AWS STS. 
-////
+Use the following procedures to configure AWS STS for {productname}.
diff --git a/modules/configuring-quay-ocp-aws-sts.adoc b/modules/configuring-quay-ocp-aws-sts.adoc
@@ -45,7 +45,7 @@ DISTRIBUTED_STORAGE_CONFIG:
 <1> The unique Amazon Resource Name (ARN) required when configuring AWS STS
 <2> The name of your s3 bucket.
 <3> The storage path for data. Usually `/datastorage`.
-<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
+<4> The Amazon Web Services region. Defaults to `us-east-1`.
 <5> The generated AWS S3 user access key required when configuring AWS STS.
 <6> The generated AWS S3 user secret key required when configuring AWS STS.
 

diff --git a/modules/configuring-quay-rosa-aws-sts.adoc b/modules/configuring-quay-rosa-aws-sts.adoc
@@ -0,0 +1,142 @@
+:_content-type: PROCEDURE
+[id="configuring-quay-rosa-aws-sts"]
+= Configuring {productname} on {product-rosa} to use AWS STS
+
+Use the following procedure to configure {productname} to use AWS STS on {product-rosa} platforms.
+
+.Prerequisites
+
+* You have created an IAM user.
+* You have created an s3 Role ARN.
+* You have created a *Custom Trust Policy* that uses the Role ARN.
+
+.Procedure
+
+. Get the `serviceAccountIssuer` resource by entering the following command:
++
+[source,terminal]
+----
+$ oc get authentication.config.openshift.io cluster -o json | jq -r .spec.serviceAccountIssuer | sed -e "s/^https:\/\///"
+----
++
+.Example output
++
+[source,terminal]
+----
+oidc.op1.openshiftapps.com/123456
+----
+
+. On the Identity and Access Management (IAM) console of the Amazon Web Services (AWS) console:
+
+.. Click *Roles*.
+
+.. Click the name of the Role to be used with AWS STS, for example, `example-role`.
+
+.. Click the *Trust relationships* tab, which shows the JSON policy created during "Creating an S3 role". Update the JSON policy as follows:
++
+[source,json]
+----
+{
+	"Version": "2012-10-17",
+	"Statement": [
+    	{
+        	"Sid": "Statement1",
+        	"Effect": "Allow",
+        	"Principal": {
+            	"Federated": "arn:aws:iam::123456:oidc-provider/oidc.op1.openshiftapps.com/123456" <1>
+        	},
+        	"Action": "sts:AssumeRoleWithWebIdentity", <2>
+        	"Condition": {
+            	"StringEquals": {
+                	"oidc.op1.openshiftapps.com/123456:sub": "system:serviceaccount:quay:registry-quay-app" <3>
+            	}
+        	}
+    	}
+	]
+}
+----
+<1> Updates the `Principal` parameter of the JSON policy to `Federated:<your_user_ARN>:<serviceAccountIssuer_domain_path>`
+<2> Updates the `Action` parameter of the JSON policy to `sts:AssumeRoleWithWebIdentity`.
+<3> Updates the `Condition` parameter of the JSON policy to `StringEquals”: “<serviceAccountIssuer>:sub”: “system:serviceAccount:<quay_namespace>:<quay_registry_using_serviceAccount>`
+
+.. Verify that your User ARN is configured correct, then click *Next*. 
+
+.. On the *Add permissions* page, select *AmazonS3FullAccess*, then click *Next*. 
+
+.. On the *Name, review, and create* page, provide your role a name, a description, verify your configuration, add any optional tags. Then, click *Create Role*.
+
+. On the *Roles* page, click the new role and store the `Role ARN` resource. For example:
++
+[source,text]
+----
+arn:aws:iam::123456:role/test_s3_access
+----
+
+. On the {productname} web console:
+
+.. Click *Operators* -> *Installed Operators*. 
+
+.. Click *Red Hat Quay*. 
+
+.. Click *Quay Registry* and then the name of your {productname} registry. 
+
+.. Under *Config Bundle Secret*, click the name of your registry configuration bundle, for example, *quay-registry-config-bundle-12345*. 
+
+.. On the configuration bundle page, click *Actions* to reveal a drop-down menu. Then click *Edit Secret*. 
+
+.. Update your the `DISTRIBUTED_STORAGE_CONFIG` fields of your `config.yaml` file with the following information:
++
+[source,yaml]
+----
+# ...
+DISTRIBUTED_STORAGE_CONFIG:
+   default:
+    - STSS3Storage
+      s3_bucket: <s3_bucket_name> <1>
+      storage_path: <storage_path> <2> 
+      s3_region: <region> <3>
+# ...
+----
+<1> The name of your s3 bucket.
+<2> The storage path for data. Usually `/datastorage`.
+<3> The Amazon Web Services region. Defaults to `us-east-1`.
+
+. Click *Save*. Your `QuayRegistry` custom resource (CR) automatically restarts.
+
+. Annotate the Service Account (SA) that executes pods with the EKS configuration values. For example:
++
+[source,terminal]
+----
+$ oc annotate sa registry-quay-app "eks.amazonaws.com/role-arn"="arn:aws:iam::123456:role/test_s3_access" "eks.amazonaws.com/audience"="sts.amazonaws.com" "eks.amazonaws.com/sts-regional-endpoints"="true"
+----
+
+.Verification
+
+. Tag a sample image, for example, `busybox`, that will be pushed to the repository. For example:
++
+[source,terminal]
+----
+$ podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/busybox:test
+----
+
+. Push the sample image by running the following command:
++
+[source,terminal]
+----
+$ podman push <quay-server.example.com>/<organization_name>/busybox:test
+----
+
+. Verify that the push was successful by navigating to the Organization that you pushed the image to in your {productname} registry -> *Tags*. 
+
+. Navigate to the Amazon Web Services (AWS) console and locate your s3 bucket. 
+
+. Click the name of your s3 bucket.
+
+. On the *Objects* page, click *datastorage/*.
+
+. On the *datastorage/* page, the following resources should seen:
++
+* *sha256/*
+* *uploads/* 
++
+These resources indicate that the push was successful, and that AWS STS is properly configured.
diff --git a/modules/configuring-quay-standalone-aws-sts.adoc b/modules/configuring-quay-standalone-aws-sts.adoc
@@ -24,7 +24,7 @@ DISTRIBUTED_STORAGE_CONFIG:
 <1> The unique Amazon Resource Name (ARN) required when configuring AWS STS
 <2> The name of your s3 bucket.
 <3> The storage path for data. Usually `/datastorage`.
-<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
+<4> The Amazon Web Services region. Defaults to `us-east-1`.
 <5> The generated AWS S3 user access key required when configuring AWS STS.
 <6> The generated AWS S3 user secret key required when configuring AWS STS.
 

diff --git a/modules/creating-iam-user-aws-sts-quay.adoc b/modules/creating-iam-user-aws-sts-quay.adoc
@@ -0,0 +1,44 @@
+:_content-type: PROCEDURE
+[id="creating-iam-user-aws-sts-quay"]
+= Creating an IAM user
+
+Use the following procedure to create an Identity and Access Management (IAM) user. 
+
+.Procedure
+
+. Log in to the Amazon Web Services (AWS) console and navigate to the Identity and Access Management (IAM) console. 
+
+. In the navigation pane, under *Access management* click *Users*. 
+
+. Click *Create User* and enter the following information:
+
+.. Enter a valid username, for example, `quay-user`. 
+
+.. For *Permissions options*, click *Add user to group*. 
+
+. On the *review and create* page, click *Create user*. You are redirected to the *Users* page.
+
+. Click the username, for example, *quay-user*. 
+
+. Copy the ARN of the user, for example, `arn:aws:iam::123456:user/quay-user`.
+
+. On the same page, click the *Security credentials* tab. 
+
+. Navigate to *Access keys*.
+
+. Click *Create access key*. 
+
+. On the *Access key best practices & alternatives* page, click *Command Line Interface (CLI)*, then, check the confirmation box. Then click *Next*. 
+
+. Optional. On the *Set description tag - optional* page, enter a description.
+
+. Click *Create access key*.
+
+. Copy and store the access key and the secret access key.
++
+[IMPORTANT]
+====
+This is the only time that the secret access key can be viewed or downloaded. You cannot recover it later. However, you can create a new access key any time.
+====
+
+. Click *Done*.