Skip to content

Commit 098885b

Browse files
EricPonvelleEricPonvelle
authored
Merge pull request #43476 from EricPonvelle/OSDOCS-3203_Cluster_Roles_Guide
OSDOCS-3203: OCM and Operator Roles and Policies
2 parents b55d1c7 + ece0ef9 commit 098885b

9 files changed

+417
-5
lines changed

‎modules/rosa-sts-account-wide-role-and-policy-commands.adoc

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
// Module included in the following assemblies:
22
//
33
// * rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-about-iam-resources.adoc
4-
4+
:_content-type: PROCEDURE
55
[id="rosa-sts-account-wide-role-and-policy-aws-cli_{context}"]
66
= Account-wide IAM role and policy AWS CLI reference
77

8-
This section lists the `aws` CLI commands that are shown in the terminal when you run the following `rosa` command using `manual` mode:
8+
This section lists the `aws` CLI commands that the `rosa` command generates in the terminal. You can run the command in either manual or automatic mode.
9+
10+
[discrete]
11+
[id="rosa-sts-account-wide-role-and-policy-aws-cli-manual-mode_{context}"]
12+
== Using manual mode for account role creation
13+
14+
The manual role creation mode generates the `aws` commands for you to review and run. The following command starts that process:
915

1016
[source,terminal]
1117
----
@@ -14,7 +20,7 @@ $ rosa create account-roles --mode manual
1420

1521
[NOTE]
1622
====
17-
When using `manual` mode, the `aws` commands are printed to the terminal for your review. After reviewing the `aws` commands, you must run them manually. Alternatively, you can specify `--mode auto` with the `rosa create` command to run the `aws` commands immediately.
23+
The provided command examples include the `ManagedOpenShift` prefix. The `ManagedOpenShift` prefix is the default value, if you do not specify a custom prefix by using the `--prefix` option.
1824
====
1925

2026
.Command output
@@ -86,7 +92,41 @@ aws iam create-policy \
8692
--tags Key=rosa_openshift_version,Value=4.8 Key=rosa_role_prefix,Value=ManagedOpenShift Key=operator_namespace,Value=openshift-image-registry Key=operator_name,Value=installer-cloud-credentials
8793
----
8894

95+
[discrete]
96+
[id="rosa-sts-account-wide-role-and-policy-aws-cli-auto-mode_{context}"]
97+
== Using auto mode for role creation
98+
99+
When you add the `--mode auto` argument, the `rosa` CLI tool creates your roles and policies. The following command starts that process:
100+
101+
[source,terminal]
102+
----
103+
$ rosa create account-roles --mode auto
104+
----
105+
89106
[NOTE]
90107
====
91-
The command examples provided in the table include the `ManagedOpenShift` prefix. The prefix is implied if you do not specify a custom prefix by using the `--prefix` option.
108+
The provided command examples include the `ManagedOpenShift` prefix. The `ManagedOpenShift` prefix is the default value, if you do not specify a custom prefix by using the `--prefix` option.
92109
====
110+
111+
.Command output
112+
[source,terminal]
113+
----
114+
I: Creating roles using 'arn:aws:iam::<ARN>:user/<UserID>'
115+
? Create the 'ManagedOpenShift-Installer-Role' role? Yes
116+
I: Created role 'ManagedOpenShift-Installer-Role' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-Installer-Role'
117+
? Create the 'ManagedOpenShift-ControlPlane-Role' role? Yes
118+
I: Created role 'ManagedOpenShift-ControlPlane-Role' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-ControlPlane-Role'
119+
? Create the 'ManagedOpenShift-Worker-Role' role? Yes
120+
I: Created role 'ManagedOpenShift-Worker-Role' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-Worker-Role'
121+
? Create the 'ManagedOpenShift-Support-Role' role? Yes
122+
I: Created role 'ManagedOpenShift-Support-Role' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-Support-Role'
123+
? Create the operator policies? Yes
124+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-machine-api-aws-cloud-credentials'
125+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-cloud-credential-operator-cloud-crede'
126+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-image-registry-installer-cloud-creden'
127+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-ingress-operator-cloud-credentials'
128+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-cluster-csi-drivers-ebs-cloud-credent'
129+
I: Created policy with ARN 'arn:aws:iam::<ARN>:policy/ManagedOpenShift-openshift-cloud-network-config-controller-cloud'
130+
I: To create a cluster with these roles, run the following command:
131+
rosa create cluster --sts
132+
----

‎modules/rosa-sts-account-wide-roles-and-policies.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,43 @@ This section provides details about the account-wide IAM roles and policies that
99

1010
The account-wide roles and policies are specific to an OpenShift minor release version, for example OpenShift 4.8, and are backward compatible. You can minimize the required STS resources by reusing the account-wide roles and policies for multiple clusters of the same minor version, regardless of their patch version.
1111

12+
[id="rosa-sts-account-wide-roles-and-policies-creation-methods_{context}"]
13+
== Methods of account-wide role creation
14+
15+
// Commenting out until ROSA UI release
16+
//
17+
// You can create account-wide roles by using the `rosa` CLI tool or the {cluster-manager-url} guided installation. You can create the roles manually or by using an automatic process that uses pre-defined names for these roles and polices.
18+
//
19+
// Commenting out until ROSA UI release
20+
21+
You can create account-wide roles by using the `rosa` CLI tool. You can create the roles manually or by using an automatic process that uses pre-defined names for these roles and polices.
22+
23+
[discrete]
24+
[id="rosa-sts-account-wide-roles-and-policies-creation-methods-manual_{context}"]
25+
=== Manual ocm-role resource creation
26+
27+
// Commenting out until ROSA UI release
28+
//
29+
// You can use the manual creation method if you have the necessary CLI access to create these roles on your system. You can run this option in your desired CLI tool or from {cluster-manager}. After you start the manual creation process, the CLI presents a series of commands for you to run that create the roles and link them to the needed policies.
30+
//
31+
// Commenting out until ROSA UI release
32+
33+
You can use the manual creation method if you have the necessary CLI access to create these roles on your system. You can run this option in your desired CLI tool or from {cluster-manager}. After you start the manual creation process, the CLI presents a series of commands for you to run that create the roles and link them to the needed policies.
34+
35+
[discrete]
36+
[id="rosa-sts-account-wide-roles-and-policies-creation-methods-auto_{context}"]
37+
=== Automatic ocm-role resource creation
38+
39+
// Commenting out until ROSA UI release
40+
//
41+
// If you created an `ocm-role` resource with administrative permissions, you can use the automatic creation method in the CLI and from {cluster-manager}. Selecting this method creates the roles and policies that uses the default names.
42+
//
43+
// If you use the ROSA guided installation on {cluster-manager}, you must have created an `ocm-role` resource with administrative permissions in the first step of the guided cluster installation. Without this role, you cannot use the automatic Operator role and policy creation option.
44+
//
45+
// Commenting out until ROSA UI release
46+
47+
If you created an `ocm-role` resource with administrative permissions, you can use the automatic creation method in the CLI. Selecting this method creates the roles and policies that uses the default names.
48+
1249
[NOTE]
1350
====
1451
The account number present in the `sts_installer_trust_policy.json` and `sts_support_trust_policy.json` samples represents the Red Hat account that is allowed to assume the required roles.

‎modules/rosa-sts-aws-requirements.adoc

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// Module included in the following assemblies:
22
//
33
// * rosa_getting_started_sts/rosa-sts-aws-prereqs.adoc
4-
4+
:_content-type: CONCEPT
55
[id="rosa-sts-customer-requirements_{context}"]
66
= Customer requirements when using STS for deployment
77

@@ -21,6 +21,105 @@ The following prerequisites must be complete before you deploy a {product-title}
2121
Customers are encouraged, but not mandated, to deploy resources in a Virtual Private Cloud (VPC) separate from the VPC hosting {product-title} and other Red Hat supported services.
2222
====
2323

24+
[id="rosa-associating-account_{context}"]
25+
== Associating your AWS account
26+
27+
To perform {product-title} (ROSA) cluster provisioning tasks, you must create `ocm-role` and `user-role` IAM resources in your AWS account and link them to your Red Hat organization.
28+
29+
The `ocm-role` ARN is stored as a label in your Red Hat organization while the `user-role` ARN is stored as a label inside your Red Hat user account. Red Hat uses these ARN labels to confirm that the user is a valid account holder and that the correct permissions are available to perform the necessary tasks in the AWS account.
30+
31+
.Prerequisites
32+
33+
* You have an AWS account.
34+
* You have the permissions required to install AWS account-wide roles.
35+
* You have installed and configured the latest AWS (`aws`) and ROSA (`rosa`) CLIs on your installation host.
36+
* You have created your `ocm-role` and `user-role` IAM roles.
37+
38+
// Commenting out until ROSA UI release
39+
//
40+
// * You have an AWS account.
41+
// * You are using {cluster-manager-url} to create clusters.
42+
// * You have the permissions required to install AWS account-wide roles.
43+
// * You have installed and configured the latest AWS (`aws`) and ROSA (`rosa`) CLIs on your installation host.
44+
// * You have created your `ocm-role` and `user-role` IAM roles.
45+
//
46+
// Commenting out until ROSA UI release
47+
48+
.Procedures
49+
50+
1. From the CLI, link your `ocm-role` resource to your Red Hat organization by using your Amazon Resource Name (ARN):
51+
+
52+
[NOTE]
53+
====
54+
You must have organization administrator privileges to run the `rosa link` command. After you link the `ocm-role` resource with your AWS account, it is visible for all users in the organization.
55+
====
56+
+
57+
[source,terminal]
58+
----
59+
$ rosa link ocm-role --role-arn <arn>
60+
----
61+
+
62+
.Example output
63+
[source,terminal]
64+
----
65+
I: Linking OCM role
66+
? Link the '<AWS ACCOUNT ID>` role with organization '<ORG ID>'? Yes
67+
I: Successfully linked role-arn '<AWS ACCOUNT ID>' with organization account '<ORG ID>'
68+
----
69+
1. From the CLI, link your `user-role` resource to your Red Hat user account by using your Amazon Resource Name (ARN):
70+
+
71+
[source,terminal]
72+
----
73+
$ rosa link user-role --role-arn <arn>
74+
----
75+
+
76+
.Example output
77+
[source,terminal]
78+
----
79+
I: Linking User role
80+
? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-User-Role-125' role with organization '<AWS ID>'? Yes
81+
I: Successfully linked role-arn 'arn:aws:iam::<ARN>:role/ManagedOpenShift-User-Role-125' with organization account '<AWS ID>'
82+
----
83+
84+
[id="rosa-associating-multiple-account_{context}"]
85+
=== Associating multiple AWS accounts with your Red Hat organization
86+
87+
You can associate multiple AWS accounts with your Red Hat organization. Associating multiple accounts lets you create {product-title} (ROSA) clusters on any of the associated AWS accounts from your Red Hat organization.
88+
89+
With this feature, you can create clusters in different AWS regions by using multiple AWS profiles as region-bound environments.
90+
91+
.Specifying an AWS profile name when creating the OCM, user, and account roles
92+
93+
To associate an additional AWS account, first create a profile in your local AWS configuration. Then, associate the account with your Red Hat organization by creating the `ocm-role`, user, and account roles in the additional AWS account.
94+
95+
To create the roles in an additional region, specify the `--profile <aws-profile>` parameter when running the `rosa create` commands and replace `<aws_profile>` with the additional account profile name:
96+
97+
* To specify an AWS account profile when creating an {cluster-manager} role:
98+
+
99+
[source,terminal]
100+
----
101+
$ rosa create --profile <aws_profile> ocm-role
102+
----
103+
104+
* To specify an AWS account profile when creating a user role:
105+
+
106+
[source,terminal]
107+
----
108+
$ rosa create --profile <aws_profile> user-role
109+
----
110+
111+
* To specify an AWS account profile when creating the account roles:
112+
+
113+
[source,terminal]
114+
----
115+
$ rosa create --profile <aws_profile> account-roles
116+
----
117+
118+
[NOTE]
119+
====
120+
If you do not specify a profile, the default AWS profile is used.
121+
====
122+
24123
[id="rosa-access-requirements_{context}"]
25124
== Access requirements
26125

‎modules/rosa-sts-ocm-role-creation.adoc

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assemblies:
2+
//
3+
// rosa_architecture/rosa-sts-about-iam-resources.adoc
4+
//
5+
:_content-type: PROCEDURE
6+
[id="rosa-sts-ocm-roles-and-permissions-iam-basic-role_{context}"]
7+
= Creating an {cluster-manager} IAM role
8+
9+
You create your {cluster-manager} IAM roles by using the command-line interface (CLI).
10+
11+
.Prerequisites
12+
13+
* You have an AWS account.
14+
* You have organization administrator privileges in the {cluster-manager} organization.
15+
* You have the permissions required to install AWS account-wide roles.
16+
* You have installed and configured the latest AWS (`aws`) and ROSA (`rosa`) CLIs on your installation host.
17+
18+
.Procedure
19+
* To create an ocm-role IAM role with basic privileges, run the following command:
20+
[source,terminal]
21+
----
22+
$ rosa create ocm-role
23+
----
24+
25+
* To create an ocm-role IAM role with admin privileges, run the following command:
26+
27+
[source,terminal]
28+
----
29+
$ rosa create ocm-role --admin
30+
----
31+
32+
This command lets you create the role by specifying specific attribues. The following example output shows the "auto mode" selected, which lets the `rosa` CLI to create your Operator roles and policies. See "Understanding the auto and manual deployment modes" in the Additional resources for more information.
33+
34+
.Example output
35+
[source,terminal]
36+
----
37+
I: Creating ocm role
38+
? Role prefix: ManagedOpenShift <1>
39+
? Enable admin capabilities for the OCM role (optional): No <2>
40+
? Permissions boundary ARN (optional): <3>
41+
? Role creation mode: auto <4>
42+
I: Creating role using 'arn:aws:iam::<ARN>:user/<UserName>'
43+
? Create the 'ManagedOpenShift-OCM-Role-182' role? Yes <5>
44+
I: Created role 'ManagedOpenShift-OCM-Role-182' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182'
45+
I: Linking OCM role
46+
? OCM Role ARN: arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182 <6>
47+
? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' role with organization '<AWS ARN'? Yes <7>
48+
I: Successfully linked role-arn 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' with organization account '<AWS ARN>'
49+
----
50+
<1> A prefix value for all of the created AWS resources. In this example, `ManagedOpenShift` prepends all of the AWS resources.
51+
<2> Choose if you want this role to have the additional admin permissions.
52+
+
53+
[NOTE]
54+
====
55+
You do not see this prompt if you used the `--admin` option.
56+
====
57+
+
58+
<3> The Amazon Resource Name (ARN) of the policy to set permission boundaries.
59+
<4> Choose the method of how to create your AWS roles. Using `auto`, the `rosa` CLI tool generates and links the roles and policies. In the `auto` mode, you receive some different prompts to create the AWS roles.
60+
<5> The auto method asks if you want to create a specific `ocm-role` using your prefix.
61+
<6> Confirm that you want to associate your IAM role with your {cluster-manager}.
62+
<7> Links the created role with your AWS organization.

‎modules/rosa-sts-understanding-ocm-role.adoc

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Module included in the following assemblies:
2+
//
3+
// rosa_architecture/rosa-sts-about-iam-resources.adoc
4+
//
5+
:_content-type: CONCEPT
6+
[id="rosa-sts-understanding-ocm-role_{context}"]
7+
= Understanding the {cluster-manager} role
8+
9+
Creating ROSA clusters in {cluster-manager-url} require an `ocm-role` IAM role. The basic `ocm-role` IAM role permissions let you to perform cluster maintenance within {cluster-manager}. To automatically create the operator roles and OpenID Connect (OIDC) provider, you must add the `--admin` option to the `rosa create` command. This command creates an `ocm-role` resource with additional permissions needed for administrative tasks.
10+
11+
[NOTE]
12+
====
13+
This elevated IAM role allows {cluster-manager} to automatically create the cluster-specific Operator roles and OIDC provider during cluster creation. For more information about this automatic role and policy creation, see the "Understanding the auto and manual deployment modes" link in Additional resources.
14+
====
15+
16+
[id="rosa-sts-understanding-user-role_{context}"]
17+
== Understanding the user role
18+
19+
In addition to an `ocm-role` IAM role, you must create a user role so that {product-title} can verify your AWS identity. This role has no permissions, and it is only used to create a trust relationship between the installer account and your `ocm-role` resources.
20+
21+
The following tables show the associated basic and administrative permissions for the `ocm-role` resource.
22+
23+
.Associated permissions for the basic `ocm-role` resource
24+
[cols="1,2",options="header"]
25+
|===
26+
27+
|Resource|Description
28+
29+
| `iam:GetOpenIDConnectProvider`
30+
| This permission allows the basic role to retrieve information about the specified OpenID Connect (OIDC) provider.
31+
| `iam:GetRole`
32+
| This permission allows the basic role to retrieve any information for a specified role. Some of the data returned include the role's path, GUID, ARN, and the role's trust policy that grants permission to assume the role.
33+
| `iam:ListRoles`
34+
| This permission allows the basic role to list the roles within a path prefix.
35+
| `iam:ListRoleTags`
36+
| This permission allows the basic role to list the tags on a specified role.
37+
| `ec2:DescribeRegions`
38+
| This permission allows the basic role to return information about all of the enabled regions on your account.
39+
| `ec2:DescribeRouteTables`
40+
| This permission allows the basic role to return information about all of your route tables.
41+
| `ec2:DescribeSubnets`
42+
| This permission allows the basic role to return information about all of your subnets.
43+
| `ec2:DescribeVpcs`
44+
| This permission allows the basic role to return information about all of your virtual private clouds (VPCs).
45+
| `sts:AssumeRole`
46+
| This permission allows the basic role to retrieve temporary security credentials to access AWS resources that are beyond its normal permissions.
47+
| `sts:AssumeRoleWithWebIdentity`
48+
| This permission allows the basic role to retrieve temporary security credentials for users authenticated their account with a web identity provider.
49+
50+
|===
51+
52+
.Additional permissions for the admin `ocm-role` resource
53+
[cols="1,2",options="header"]
54+
|===
55+
56+
|Resource|Description
57+
58+
| `iam:AttachRolePolicy`
59+
| This permission allows the admin role to attach a specified policy to the desired IAM role.
60+
| `iam:CreateOpenIDConnectProvider`
61+
| This permission creates a resource that describes an identity provider, which supports OpenID Connect (OIDC). When you create an OIDC provider with this permission, this provider establishes a trust relationship between the provider and AWS.
62+
| `iam:CreateRole`
63+
| This permission allows the admin role to create a role for your AWS account.
64+
| `iam:ListPolicies`
65+
| This permission allows the admin role to list any policies associated with your AWS account.
66+
| `iam:ListPolicyTags`
67+
| This permission allows the admin role to list any tags on a designated policy.
68+
| `iam:PutRolePermissionsBoundary`
69+
| This permission allows the admin role to change the permissions boundary for a user based on a specified policy.
70+
| `iam:TagRole`
71+
| This permission allows the admin role to add tags to an IAM role.
72+
73+
|===

0 commit comments

Comments
 (0)