Skip to content

Commit db6c6b5

Browse files
stevsmitSteven Smith
stevsmit
and
Steven Smith
authored
Adds aws sts support on rosa to quay docs (quay#1377)
Co-authored-by: Steven Smith <[email protected]>
1 parent 37c96ab commit db6c6b5

9 files changed

+248
-124
lines changed

‎modules/attributes.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
:rhel: Red Hat Enterprise Linux (RHEL)
1010
:rhel-short: RHEL
1111
:ocp-y: 4.18
12+
:product-rosa: Red{nbsp}Hat OpenShift Service on AWS
1213

1314
ifeval::["{productname}" == "Project Quay"]
1415
:upstream:

‎modules/config-fields-storage-aws.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ DISTRIBUTED_STORAGE_PREFERENCE:
3434
# ...
3535
----
3636
<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".
37-
<2> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
37+
<2> The Amazon Web Services region. Defaults to `us-east-1`.
3838

3939
[id="config-fields-storage-aws-sts"]
4040
== Amazon Web Services STS S3 storage
@@ -64,7 +64,7 @@ DISTRIBUTED_STORAGE_PREFERENCE:
6464
<1> The unique Amazon Resource Name (ARN).
6565
<2> The generated AWS S3 user access key.
6666
<3> The generated AWS S3 user secret key.
67-
<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
67+
<4> The Amazon Web Services region. Defaults to `us-east-1`.
6868

6969
[id="aws-cloudfront-storage-example"]
7070
== AWS CloudFront storage

‎modules/configuring-aws-sts-quay.adoc‎

Lines changed: 4 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,9 @@
1-
:_content-type: PROCEDURE
1+
:_content-type: CONCEPT
22
[id="configuring-aws-sts-quay"]
33
= Configuring AWS STS for {productname}
44

5-
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.
5+
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.
66

7-
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.
7+
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.
88

9-
Use the following procedures to configure AWS STS for {productname}.
10-
11-
[id="creating-am-user"]
12-
== Creating an IAM user
13-
14-
Use the following procedure to create an IAM user.
15-
16-
.Procedure
17-
18-
. Log in to the Amazon Web Services (AWS) console and navigate to the Identity and Access Management (IAM) console.
19-
20-
. In the navigation pane, under *Access management* click *Users*.
21-
22-
. Click *Create User* and enter the following information:
23-
24-
.. Enter a valid username, for example, `quay-user`.
25-
26-
.. For *Permissions options*, click *Add user to group*.
27-
28-
. On the *review and create* page, click *Create user*. You are redirected to the *Users* page.
29-
30-
. Click the username, for example, *quay-user*.
31-
32-
. Copy the ARN of the user, for example, `arn:aws:iam::123492922789:user/quay-user`.
33-
34-
. On the same page, click the *Security credentials* tab.
35-
36-
. Navigate to *Access keys*.
37-
38-
. Click *Create access key*.
39-
40-
. On the *Access key best practices & alternatives* page, click *Command Line Interface (CLI)*, then, check the confirmation box. Then click *Next*.
41-
42-
. Optional. On the *Set description tag - optional* page, enter a description.
43-
44-
. Click *Create access key*.
45-
46-
. Copy and store the access key and the secret access key.
47-
+
48-
[IMPORTANT]
49-
====
50-
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.
51-
====
52-
53-
. Click *Done*.
54-
55-
[id="creating-s3-role"]
56-
== Creating an S3 role
57-
58-
Use the following procedure to create an S3 role for AWS STS.
59-
60-
.Prerequisites
61-
62-
* You have created an IAM user and stored the access key and the secret access key.
63-
64-
.Procedure
65-
66-
. If you are not already, navigate to the IAM dashboard by clicking *Dashboard*.
67-
68-
. In the navigation pane, click *Roles* under *Access management*.
69-
70-
. Click *Create role*.
71-
72-
* Click *Custom Trust Policy*, which shows an editable JSON policy. By default, it shows the following information:
73-
+
74-
[source,json]
75-
----
76-
{
77-
"Version": "2012-10-17",
78-
"Statement": [
79-
{
80-
"Sid": "Statement1",
81-
"Effect": "Allow",
82-
"Principal": {},
83-
"Action": "sts:AssumeRole"
84-
}
85-
]
86-
}
87-
----
88-
89-
. Under the `Principal` configuration field, add your AWS ARN information. For example:
90-
+
91-
[source,json]
92-
----
93-
{
94-
"Version": "2012-10-17",
95-
"Statement": [
96-
{
97-
"Sid": "Statement1",
98-
"Effect": "Allow",
99-
"Principal": {
100-
"AWS": "arn:aws:iam::123492922789:user/quay-user"
101-
},
102-
"Action": "sts:AssumeRole"
103-
}
104-
]
105-
}
106-
----
107-
108-
. Click *Next*.
109-
110-
. 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*.
111-
112-
. On the *Name, review, and create* page, enter the following information:
113-
114-
.. Enter a role name, for example, `example-role`.
115-
116-
.. Optional. Add a description.
117-
118-
. Click the *Create role* button. You are navigated to the *Roles* page. Under *Role name*, the newly created S3 should be available.
119-
120-
////
121-
[id="configuring-quay-operator-use-aws-sts"]
122-
== Configuring the {productname} to use AWS STS
123-
124-
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.
125-
////
9+
Use the following procedures to configure AWS STS for {productname}.

‎modules/configuring-quay-ocp-aws-sts.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ DISTRIBUTED_STORAGE_CONFIG:
4545
<1> The unique Amazon Resource Name (ARN) required when configuring AWS STS
4646
<2> The name of your s3 bucket.
4747
<3> The storage path for data. Usually `/datastorage`.
48-
<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
48+
<4> The Amazon Web Services region. Defaults to `us-east-1`.
4949
<5> The generated AWS S3 user access key required when configuring AWS STS.
5050
<6> The generated AWS S3 user secret key required when configuring AWS STS.
5151

‎modules/configuring-quay-rosa-aws-sts.adoc‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
:_content-type: PROCEDURE
2+
[id="configuring-quay-rosa-aws-sts"]
3+
= Configuring {productname} on {product-rosa} to use AWS STS
4+
5+
Use the following procedure to configure {productname} to use AWS STS on {product-rosa} platforms.
6+
7+
.Prerequisites
8+
9+
* You have created an IAM user.
10+
* You have created an s3 Role ARN.
11+
* You have created a *Custom Trust Policy* that uses the Role ARN.
12+
13+
.Procedure
14+
15+
. Get the `serviceAccountIssuer` resource by entering the following command:
16+
+
17+
[source,terminal]
18+
----
19+
$ oc get authentication.config.openshift.io cluster -o json | jq -r .spec.serviceAccountIssuer | sed -e "s/^https:\/\///"
20+
----
21+
+
22+
.Example output
23+
+
24+
[source,terminal]
25+
----
26+
oidc.op1.openshiftapps.com/123456
27+
----
28+
29+
. On the Identity and Access Management (IAM) console of the Amazon Web Services (AWS) console:
30+
31+
.. Click *Roles*.
32+
33+
.. Click the name of the Role to be used with AWS STS, for example, `example-role`.
34+
35+
.. Click the *Trust relationships* tab, which shows the JSON policy created during "Creating an S3 role". Update the JSON policy as follows:
36+
+
37+
[source,json]
38+
----
39+
{
40+
"Version": "2012-10-17",
41+
"Statement": [
42+
{
43+
"Sid": "Statement1",
44+
"Effect": "Allow",
45+
"Principal": {
46+
"Federated": "arn:aws:iam::123456:oidc-provider/oidc.op1.openshiftapps.com/123456" <1>
47+
},
48+
"Action": "sts:AssumeRoleWithWebIdentity", <2>
49+
"Condition": {
50+
"StringEquals": {
51+
"oidc.op1.openshiftapps.com/123456:sub": "system:serviceaccount:quay:registry-quay-app" <3>
52+
}
53+
}
54+
}
55+
]
56+
}
57+
----
58+
<1> Updates the `Principal` parameter of the JSON policy to `Federated:<your_user_ARN>:<serviceAccountIssuer_domain_path>`
59+
<2> Updates the `Action` parameter of the JSON policy to `sts:AssumeRoleWithWebIdentity`.
60+
<3> Updates the `Condition` parameter of the JSON policy to `StringEquals”: “<serviceAccountIssuer>:sub”: “system:serviceAccount:<quay_namespace>:<quay_registry_using_serviceAccount>`
61+
62+
.. Verify that your User ARN is configured correct, then click *Next*.
63+
64+
.. On the *Add permissions* page, select *AmazonS3FullAccess*, then click *Next*.
65+
66+
.. 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*.
67+
68+
. On the *Roles* page, click the new role and store the `Role ARN` resource. For example:
69+
+
70+
[source,text]
71+
----
72+
arn:aws:iam::123456:role/test_s3_access
73+
----
74+
75+
. On the {productname} web console:
76+
77+
.. Click *Operators* -> *Installed Operators*.
78+
79+
.. Click *Red Hat Quay*.
80+
81+
.. Click *Quay Registry* and then the name of your {productname} registry.
82+
83+
.. Under *Config Bundle Secret*, click the name of your registry configuration bundle, for example, *quay-registry-config-bundle-12345*.
84+
85+
.. On the configuration bundle page, click *Actions* to reveal a drop-down menu. Then click *Edit Secret*.
86+
87+
.. Update your the `DISTRIBUTED_STORAGE_CONFIG` fields of your `config.yaml` file with the following information:
88+
+
89+
[source,yaml]
90+
----
91+
# ...
92+
DISTRIBUTED_STORAGE_CONFIG:
93+
default:
94+
- STSS3Storage
95+
s3_bucket: <s3_bucket_name> <1>
96+
storage_path: <storage_path> <2>
97+
s3_region: <region> <3>
98+
# ...
99+
----
100+
<1> The name of your s3 bucket.
101+
<2> The storage path for data. Usually `/datastorage`.
102+
<3> The Amazon Web Services region. Defaults to `us-east-1`.
103+
104+
. Click *Save*. Your `QuayRegistry` custom resource (CR) automatically restarts.
105+
106+
. Annotate the Service Account (SA) that executes pods with the EKS configuration values. For example:
107+
+
108+
[source,terminal]
109+
----
110+
$ 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"
111+
----
112+
113+
.Verification
114+
115+
. Tag a sample image, for example, `busybox`, that will be pushed to the repository. For example:
116+
+
117+
[source,terminal]
118+
----
119+
$ podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/busybox:test
120+
----
121+
122+
. Push the sample image by running the following command:
123+
+
124+
[source,terminal]
125+
----
126+
$ podman push <quay-server.example.com>/<organization_name>/busybox:test
127+
----
128+
129+
. Verify that the push was successful by navigating to the Organization that you pushed the image to in your {productname} registry -> *Tags*.
130+
131+
. Navigate to the Amazon Web Services (AWS) console and locate your s3 bucket.
132+
133+
. Click the name of your s3 bucket.
134+
135+
. On the *Objects* page, click *datastorage/*.
136+
137+
. On the *datastorage/* page, the following resources should seen:
138+
+
139+
* *sha256/*
140+
* *uploads/*
141+
+
142+
These resources indicate that the push was successful, and that AWS STS is properly configured.

‎modules/configuring-quay-standalone-aws-sts.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ DISTRIBUTED_STORAGE_CONFIG:
2424
<1> The unique Amazon Resource Name (ARN) required when configuring AWS STS
2525
<2> The name of your s3 bucket.
2626
<3> The storage path for data. Usually `/datastorage`.
27-
<4> Optional. The Amazon Web Services region. Defaults to `us-east-1`.
27+
<4> The Amazon Web Services region. Defaults to `us-east-1`.
2828
<5> The generated AWS S3 user access key required when configuring AWS STS.
2929
<6> The generated AWS S3 user secret key required when configuring AWS STS.
3030

‎modules/creating-iam-user-aws-sts-quay.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
:_content-type: PROCEDURE
2+
[id="creating-iam-user-aws-sts-quay"]
3+
= Creating an IAM user
4+
5+
Use the following procedure to create an Identity and Access Management (IAM) user.
6+
7+
.Procedure
8+
9+
. Log in to the Amazon Web Services (AWS) console and navigate to the Identity and Access Management (IAM) console.
10+
11+
. In the navigation pane, under *Access management* click *Users*.
12+
13+
. Click *Create User* and enter the following information:
14+
15+
.. Enter a valid username, for example, `quay-user`.
16+
17+
.. For *Permissions options*, click *Add user to group*.
18+
19+
. On the *review and create* page, click *Create user*. You are redirected to the *Users* page.
20+
21+
. Click the username, for example, *quay-user*.
22+
23+
. Copy the ARN of the user, for example, `arn:aws:iam::123456:user/quay-user`.
24+
25+
. On the same page, click the *Security credentials* tab.
26+
27+
. Navigate to *Access keys*.
28+
29+
. Click *Create access key*.
30+
31+
. On the *Access key best practices & alternatives* page, click *Command Line Interface (CLI)*, then, check the confirmation box. Then click *Next*.
32+
33+
. Optional. On the *Set description tag - optional* page, enter a description.
34+
35+
. Click *Create access key*.
36+
37+
. Copy and store the access key and the secret access key.
38+
+
39+
[IMPORTANT]
40+
====
41+
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.
42+
====
43+
44+
. Click *Done*.

0 commit comments

Comments
 (0)