Skip to content

Commit 5dbbb5c

Browse files
jneczyporjneczypor
committed
OSDOCS-8401
1 parent fc4c69b commit 5dbbb5c

File tree

2 files changed

+135
-0
lines changed

2 files changed

+135
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@ Topics:
108108
File: cloud-experts-dynamic-certificate-custom-domain
109109
- Name: Assigning consistent egress IP for external traffic
110110
File: cloud-experts-consistent-egress-ip
111+
- Name: ROSA with AWS STS explained
112+
File: cloud-experts-rosa-sts-explained
111113
---
112114
Name: Getting started
113115
Dir: rosa_getting_started

‎cloud_experts_tutorials/cloud-experts-rosa-sts-explained.adoc

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
:_content-type: ASSEMBLY
2+
[id="cloud-experts-rosa-sts-explained"]
3+
= Tutorial: ROSA with AWS STS explained
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: cloud-experts-rosa-sts-explained
6+
7+
toc::[]
8+
9+
//rosaworkshop.io content metadata
10+
//Brought into ROSA product docs 2023-10-26
11+
12+
== Tutorial overview
13+
This tutorial will:
14+
* Enumerate the two main deployment options:
15+
** {product-title} (ROSA) with Security Token Service (STS)
16+
** ROSA with IAM Users
17+
* Explain the differences between the two options
18+
* Explain why ROSA with STS is more secure and the preferred option
19+
* Explain how ROSA with STS works
20+
21+
== The different credential methods to deploy ROSA
22+
As part of the ROSA service, Red Hat manages infrastructure resources in your AWS account and must be granted the necessary permissions. There are currently two supported methods for granting those permissions:
23+
24+
* Using static IAM user credentials with an AdministratorAccess policy
25+
+
26+
This is referred to as “ROSA with IAM Users” in our documentation. It is not the preferred credential method.
27+
+
28+
* Using AWS STS with short-lived, dynamic tokens
29+
+
30+
This is referred to as “ROSA with STS” in our documentation. It is the preferred credential method.
31+
+
32+
33+
== Rosa with IAM Users
34+
When ROSA was first released, the only credential method was ROSA with IAM Users. This method grants an IAM user with an attached AdministratorAccess policy full access to create the necessary resources in the AWS account that uses ROSA. It also allows the cluster to create and expand its own credentials as needed.
35+
36+
== ROSA with STS
37+
Red Hat has improved ROSA to implement security best practices and introduce a method that utilizes AWS STS. The STS method uses predefined roles and policies to grant temporary service minimal, or least-privilege, permissions to IAM users or authenticated federated users. ROSA with STS can be used to grant users limited, short-term access to resources in your AWS account. The credentials typically expire an hour after being requested. Once expired, they are no longer recognized by AWS and no longer have any kind of account access from API requests made with them. For more information, see the link:https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html[AWS documentation]. While both ROSA with IAM Users and ROSA with STS are currently enabled, ROSA with STS is the preferred and recommended option.
38+
39+
== ROSA with STS Security
40+
Several crucial components make ROSA with STS more secure than ROSA with IAM Users:
41+
* An explicit and limited set of roles and policies that the user creates ahead of time. Th user knows every permission asked for and every role used.
42+
* The service cannot do anything outside of those permissions.
43+
* Whenever the service needs to perform an action, it obtains credentials that will expire in at most one hour. This means that there is no need to rotate or revoke credentials. Additionally, credential expiration reduces the risks of credentials leaking and being reused.
44+
45+
== The use of STS
46+
ROSA uses STS to grant permissions defined as least-privilege policies to specific and segregated IAM roles with short-term security credentials. These credentials are associated to the IAM roles that are specific to each component and cluster that makes AWS API calls. This method better aligns with principles of least-privilege and secure practices in cloud service resource management. The ROSA command-line interface (CLI) tool manages the STS roles and policies that are assigned for unique tasks and takes action upon AWS resources as part of OpenShift functionality.
47+
48+
STS roles and policies must be created for each ROSA cluster. To make this easier, the installation tools provide all the commands and files needed to create the roles as policies as well as an option to allow the CLI to perform the creation of these roles and policies automatically. See xref:../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-sts-creating-cluster-customizations_rosa-sts-creating-a-cluster-with-customizations[Creating a ROSa cluster with STS using customizations] for more information about the different `--mode` options.
49+
50+
== Components specific to ROSA with STS
51+
* *AWS infrastructure* - This provides the infrastructure required for the cluster. This will contain the actual EC2 instances, storage, and networking components. See xref:../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-aws-compute-types_rosa-service-definition[AWS compute types] to see supported instance types for compute nodes and xref:../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-ec2-instances_rosa-sts-aws-prereqs[provisioned AWS infrastructure] for the control plane and infrastructure node configuration.
52+
* *AWS STS* - See the above section titled "ROSA with STS".
53+
* *OIDC* - Provides a mechanism for cluster operators to authenticate with AWS, assume the cluster roles via a trust policy, and obtain temporary credentials from STS in order to make the required API calls.
54+
* *Roles and policies* - This is the main component that differentiates ROSA with STS from ROSA with IAM Users. The roles and policies that are used by ROSA are broken up into account-wide roles and policies and operator roles and policies.
55+
56+
The policies determine the allowed actions, or permissions policies, for each of the roles. See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-about-iam-resources[About IAM resources for ROSA clusters that use STS] for more details about the individual roles and policies.
57+
58+
The account-wide roles are:
59+
* ManagedOpenShift-Installer-Role
60+
* ManagedOpenShift-ControlPlane-Role
61+
* ManagedOpenShift-Worker-Role
62+
* ManagedOpenShift-Support-Role
63+
64+
The account-wide policies are:
65+
* ManagedOpenShift-Installer-Role-Policy
66+
* ManagedOpenShift-ControlPlane-Role-Policy
67+
* ManagedOpenShift-Worker-Role-Policy
68+
* ManagedOpenShift-Support-Role-Policy
69+
* ManagedOpenShift-openshift-ingress-operator-cloud-credentials ^[1]^
70+
* ManagedOpenShift-openshift-cluster-csi-drivers-ebs-cloud-credent ^[1]^
71+
* ManagedOpenShift-openshift-cloud-network-config-controller-cloud ^[1]^
72+
* ManagedOpenShift-openshift-machine-api-aws-cloud-credentials ^[1]^
73+
* ManagedOpenShift-openshift-cloud-credential-operator-cloud-crede ^[1]^
74+
* ManagedOpenShift-openshift-image-registry-installer-cloud-creden ^[1]^
75+
76+
+
77+
[.small]
78+
--
79+
1. This policy is used by the cluster operator roles, listed below, which are created in a second step since they are dependent on an existing cluster name and cannot be created at the same time as the account-wide roles.
80+
--
81+
82+
The operator roles are:
83+
* <cluster-name\>-xxxx-openshift-cluster-csi-drivers-ebs-cloud-credent
84+
* <cluster-name\>-xxxx-openshift-cloud-network-config-controller-cloud
85+
* <cluster-name\>-xxxx-openshift-machine-api-aws-cloud-credentials
86+
* <cluster-name\>-xxxx-openshift-cloud-credential-operator-cloud-crede
87+
* <cluster-name\>-xxxx-openshift-image-registry-installer-cloud-creden
88+
* <cluster-name\>-xxxx-openshift-ingress-operator-cloud-credentials
89+
90+
Trust policies are created for each account-wide and operator role.
91+
92+
== What is the process for deploying a ROSA cluster that uses STS?
93+
While reading the steps below, please do not become intimidated. You are not expected to create these resources from scratch. The ROSA CLI will create the required JSON files for you, and will output the commands you need to run. The ROSA CLI can also take this a step further and do it all for you, if desired.
94+
95+
The steps are:
96+
. Create the account-wide roles and policies
97+
. Assign the permissions policy to the corresponding role
98+
. Create the cluster
99+
. Create the operator roles
100+
. Assign the permission policy to the corresponding operator roles.
101+
. Create the OIDC provider
102+
. Cluster is created. Done.
103+
104+
These roles and policies can be created automatically by the ROSA CLI or they can be manually created by utilizing the `--mode manual` or `--mode auto` flags in the ROSA CLI. See the documentation for details about the link:https://docs.openshift.com/rosa/rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.html#rosa-sts-creating-cluster-customizations_rosa-sts-creating-a-cluster-with-customizations[modes], or see the link:2-deploy.md[Deploy the cluster] section in this workshop as well.
105+
106+
== How does ROSA with STS work?
107+
To get started, the user, using their local AWS user, will create the required account-wide roles and account-wide policies (see the [components](#what-are-the-components-that-are-specific-to-rosa-with-sts) section above). As a part of creating these roles a trust policy will be created which allows a Red Hat owned role to assume these roles (cross-account trust policy). Trust policies will also be created for the EC2 service (allowing workloads on EC2 instances to assume roles and get credentials). Then the user will assign to each role its corresponding permissions policy.
108+
109+
After the account-wide roles and policies are created we must proceed with creating the cluster. Once the cluster creation has been initiated, the operator related roles can be created so that the operators on the cluster can make AWS API calls. These roles are then assigned to their corresponding permission policies that were created earlier, along with a trust policy to an OIDC provider. These roles are a bit different from the account-wide roles in that they represent the operators on the cluster (which ultimately are pods) that need access to AWS resources. Now, we cannot attach IAM roles to pods, so we need to create a trust policy with an OIDC provider so that the pods (comprising the operator) can have access to the roles they need.
110+
111+
Once we have assigned the roles to the corresponding policy permissions, the final step is to create the OIDC provider.
112+
113+
![STS_Creation_Flow](images/15-sts_creation_flow.png)
114+
115+
After this process has completed, when a role is needed, the workload, currently using the Red Hat role, will assume the role in the AWS account, obtain temporary credentials from AWS STS and begin performing the actions (via API calls) within the customer's AWS account as permitted by the assumed role's permissions policy. It should be noted that these credentials are temporary and have a maximum duration of 1 hour.
116+
117+
![STS_HighLevel](images/15-sts_highlevel.png)
118+
119+
Placing this all together we can see the following flow and relationships:
120+
121+
![STS_CLI_Flow](images/15-cli_flow.png)
122+
123+
Operators in the cluster use the following process to get credentials in order to perform their required tasks. As we saw above, each operator has an operator role, a permissions policy and a trust policy with an OIDC provider. The operator will assume-role by passing a JWT that contains the role and a token file (web_identity_token_file) to the OIDC provider, which then authenticates the signed key with a public key (created at cluster creation time and was stored in an S3 bucket). It will then confirm that the subject in the signed token file that was sent matches the role in the role trust policy (this way we ensure you only can get the role allowed). Then it will return the temporary credentials to the operator so that it can make AWS API calls. Here is an illustration of this concept:
124+
125+
![STS_OIDC](images/15-oidc_op_roles.png)
126+
127+
To illustrate how this works, let's take a look at two examples:
128+
129+
. *How nodes are created at cluster install* - The installer, using the _RH-Managed-OpenShift-Installer_ role would assume the role of _Managed-OpenShift-Installer-Role_ within the customers account (via the trust policy) which returns temporary credentials from AWS STS. Red Hat (the installer) would then begin making the required API calls (with the temporary credentials just received from STS) to create the infrastructure required in AWS. The same process would apply for support. Just in this case there would be an SRE instead of the installer.
130+
. *Scaling out the cluster* - the _machine-api-operator_ will assume-role (AssumeRoleWithWebIdentity) for the _machine-api-aws-cloud-credentials_ role. This would launch the sequence described above for the cluster operators and then it would receive the credentials. The _machine-api-operator_ can now make the relevant API calls to add more EC2 instances to the cluster.
131+
132+
== Wrapping up
133+
We have seen the options for allowing the ROSA service to interact with resources in a user's AWS account and reviewed why AWS STS is the preferred and more secure method. Additionally we have looked at the detailed components and processes that ROSA with STS uses in order to obtain the credentials it needs.

0 commit comments

Comments
 (0)