Merge pull request #50982 from EricPonvelle/OSDOCS-4225_Account-Role-Linking

jab-rh · web-flow · commit d71d52cc2863 · 2022-10-21T16:17:04.000-04:00
OSDOCS-4225: Added more references to IAM roles
diff --git a/modules/rosa-create-objects.adoc b/modules/rosa-create-objects.adoc
@@ -498,3 +498,52 @@ Add a machine pool with labels to a cluster:
 ----
 $ rosa create machinepool --cluster=mycluster --replicas=2 --instance-type=r5.2xlarge --labels=foo=bar,bar=baz --name=mp-1
 ----
+
+[id="rosa-create-ocm-role_{context}"]
+== create ocm-role
+
+Create the needed ocm-role resources for your cluster.
+
+.Syntax
+[source,terminal]
+----
+$ rosa create ocm-role [flags]
+----
+
+.Flags
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--admin                         
+|Enable admin capabilities for the role.
+
+|--debug
+|Enable debug mode.
+
+|-i, --interactive
+|Enable interactive mode.
+
+|-m, --mode string
+|How to perform the operation. Valid options are:
+    auto: Resource changes will be automatic applied using the current AWS account
+    manual: Commands necessary to modify AWS resources will be output to be run manually
+
+|--permissions-boundary string
+|The ARN of the policy that is used to set the permissions boundary for the OCM role.
+
+|--prefix string
+|User-defined prefix for all generated AWS resources (default "ManagedOpenShift")
+
+|--profile string
+|Use a specific AWS profile from your credential file.
+
+|--region string
+|Use a specific AWS region, overriding the AWS_REGION environment variable.
+
+|-y, --yes
+|Automatically answer yes to confirm operation.
+
+|===
+
+For more information about the ocm-roles and the roles created with the `rosa create ocm-roles`, see the Additional resources section.
diff --git a/modules/rosa-sts-about-ocm-role.adoc b/modules/rosa-sts-about-ocm-role.adoc
@@ -6,11 +6,11 @@
 [id="rosa-sts-about-ocm-role_{context}"]
 = About the ocm-role IAM resource
 
-You must create the `ocm-role` IAM resource to enable a Red Hat organization of users to create ROSA clusters.
+You must create the `ocm-role` IAM resource to enable a Red Hat organization of users to create ROSA clusters. Within the context of linking to AWS, a Red Hat organization is a single user within {cluster-manager}.
 
 Some considerations for your `ocm-role` IAM resource are:
 
-* You have only one `ocm-role` per AWS account in a Red Hat organization. You can have multiple `ocm-role` IAM roles in a Red Hat organization as long as these roles are for different AWS accounts.
+* Only one `ocm-role` IAM role can be linked per Red Hat organization; however, you can have any number of `ocm-role` IAM roles per AWS account. The web UI requires that only one of these roles can be linked at a time.
 * Any user in a Red Hat organization may create and link an `ocm-role` IAM resource.
 * Only the Red Hat Organization Administrator can unlink an `ocm-role` IAM resource. This limitation is to protect other Red Hat organization members from disturbing the interface capabilities of other users.
 +
@@ -19,8 +19,7 @@ Some considerations for your `ocm-role` IAM resource are:
 If you just created a Red Hat account that is not part of an existing organization, this account is also the Red Hat Organization Administrator.
 ====
 +
-* Only one `ocm-role` IAM resource can be created per AWS account per Red Hat organization.
-* See the associated permission tables for a list of the AWS permissions policy for the basic and admin `ocm-role` IAM resources.
+* See "Understanding the {cluster-manager} role" in the Additional resources of this section for a list of the AWS permissions policies for the basic and admin `ocm-role` IAM resources.
 
 Using the `rosa` CLI, you can link your IAM resource when you create it.
 
diff --git a/modules/rosa-sts-about-user-role.adoc b/modules/rosa-sts-about-user-role.adoc
@@ -7,14 +7,15 @@
 [id="rosa-sts-about-user-role_{context}"]
 = About the user-role IAM role
 
-You need to create the `user-role` IAM role to enable a Red Hat organization of users to create ROSA clusters.
+You need to create a `user-role` IAM role per web UI user to enable those users to create ROSA clusters.
 
 Some considerations for your `user-role` IAM role are:
 
 * You only need one `user-role` IAM role per Red Hat user account, but your Red Hat organization can have many of these IAM resources.
 * Any user in a Red Hat organization may create and link an `user-role` IAM role.
 * There can be numerous `user-role` IAM roles per AWS account per Red Hat organization.
 * Red Hat uses the `user-role` IAM role to identify the user. This IAM resource has no AWS account permissions.
+* Your AWS account can have multiple `user-role` IAM roles, but you must link each IAM role to each user in your Red Hat organization. No user can have more than one linked `user-role` IAM role.
 
 [NOTE]
 ====
diff --git a/modules/rosa-sts-aws-iam.adoc b/modules/rosa-sts-aws-iam.adoc
diff --git a/modules/rosa-sts-aws-requirements-creating-association.adoc b/modules/rosa-sts-aws-requirements-creating-association.adoc
@@ -13,7 +13,7 @@ You link your AWS account using the `rosa` CLI.
 
 * You have an AWS account.
 * You are using {cluster-manager-url} to create clusters.
-* You have the permissions required to install AWS account-wide roles.
+* You have the permissions required to install AWS account-wide roles. See the "Additional resources" of this section for more information.
 * You have installed and configured the latest AWS (`aws`) and ROSA (`rosa`) CLIs on your installation host.
 * You have created your `ocm-role` and `user-role` IAM roles.
 
diff --git a/modules/rosa-sts-operator-roles.adoc b/modules/rosa-sts-operator-roles.adoc
@@ -30,6 +30,10 @@ If more than one matching policy is available in your account for an Operator ro
 |`<cluster_name>-<hash>-openshift-cloud-credential-operator-cloud-credentials`
 |An IAM role required by the ROSA Cloud Credential Operator to manage cloud provider credentials.
 
+
+|`<cluster_name>-<hash>-openshift-cloud-network-config-controller-credentials`
+|An IAM role required by the cloud network config controller to manage cloud network configuration for a cluster.
+
 |`<cluster_name>-<hash>-openshift-image-registry-installer-cloud-credentials`
 |An IAM role required by the ROSA Image Registry Operator to manage the internal registry storage in AWS S3 for a cluster.
 
diff --git a/rosa_cli/rosa-manage-objects-cli.adoc b/rosa_cli/rosa-manage-objects-cli.adoc
@@ -11,6 +11,11 @@ Managing objects with the `rosa` CLI, such as adding `dedicated-admin` users, ma
 include::modules/rosa-common-commands.adoc[leveloffset=+1]
 include::modules/rosa-parent-commands.adoc[leveloffset=+1]
 include::modules/rosa-create-objects.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+* See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies_rosa-sts-about-iam-resources[Account-wide IAM role and policy reference] for a list of IAM roles needed for cluster creation.
+
 include::modules/rosa-edit-objects.adoc[leveloffset=+1]
 include::modules/rosa-delete-objects.adoc[leveloffset=+1]
 include::modules/rosa-install-uninstall-addon.adoc[leveloffset=+1]
diff --git a/rosa_planning/rosa-sts-aws-prereqs.adoc b/rosa_planning/rosa-sts-aws-prereqs.adoc
@@ -50,12 +50,28 @@ include::modules/rosa-sts-aws-requirements-security-req.adoc[leveloffset=+2]
 include::modules/rosa-sts-aws-requirements-ocm.adoc[leveloffset=+2]
 include::modules/rosa-sts-aws-requirements-association-concept.adoc[leveloffset=+3]
 include::modules/rosa-sts-aws-requirements-creating-association.adoc[leveloffset=+3]
+
+[discrete]
+[role="_additional-resources"]
+[id="additional-resources_creating-association_{context}"]
+== Additional resources
+* See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies_rosa-sts-about-iam-resources[Account-wide IAM role and policy reference] for a list of IAM roles needed for cluster creation.
+
 include::modules/rosa-sts-aws-requirements-creating-multi-association.adoc[leveloffset=+3]
 
 
 include::modules/rosa-requirements-deploying-in-opt-in-regions.adoc[leveloffset=+1]
 include::modules/rosa-setting-the-aws-security-token-version.adoc[leveloffset=+2]
-include::modules/rosa-sts-aws-iam.adoc[leveloffset=+1]
+
+[id="rosa-sts-policy-iam_{context}"]
+== Red Hat managed IAM references for AWS
+
+With the STS deployment model, Red Hat is no longer responsible for creating and managing Amazon Web Services (AWS) IAM policies, IAM users, or IAM roles. For information on creating these roles and policies, see the following sections on IAM roles.
+
+* To use the `ocm` CLI, you must have an `ocm-role` and `user-role` resource. See xref:../rosa_planning/rosa-sts-ocm-role.adoc#rosa-sts-ocm-role[OpenShift Cluster Manager IAM role resources].
+* If you have a single cluster, see xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies_rosa-sts-about-iam-resources[Account-wide IAM role and policy reference].
+* For every cluster, you must have the necessary operator roles. See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-operator-roles_rosa-sts-about-iam-resources[Cluster-specific Operator IAM role reference].
+
 include::modules/rosa-aws-provisioned.adoc[leveloffset=+1]
 include::modules/osd-aws-privatelink-firewall-prerequisites.adoc[leveloffset=+1]
 
diff --git a/rosa_planning/rosa-sts-ocm-role.adoc b/rosa_planning/rosa-sts-ocm-role.adoc
@@ -6,20 +6,48 @@ include::_attributes/attributes-openshift-dedicated.adoc[]
 
 toc::[]
 
-{product-title} (ROSA) web UI needs you to have some permissions on your AWS account that create a trust relationship to provide the end-user experience at {cluster-manager-url} and for the `rosa` command line interface (CLI).
+{product-title} (ROSA) web UI requires that you have specific permissions on your AWS account that create a trust relationship to provide the end-user experience at {cluster-manager-url} and for the `rosa` command line interface (CLI).
 
-This trust relationship is achieved through the creation and association of two AWS IAM roles:
+This trust relationship is achieved through the creation and association of the `ocm-role` AWS IAM role. This role has a trust policy with the AWS installer that links your Red Hat account to your AWS account. In addition, you also need a `user-role` AWS IAM role for each web UI user, which serves to identify these users. This `user-role` AWS IAM role has no permissions.
+
+The AWS IAM roles required to use {cluster-manager} are:
 
 1. `ocm-role`
 2. `user-role`
 
-If you use the `rosa` CLI, the `rosa` tool creates a number of these required permissions for you. This creation is available since your user account authenticates for both Red Hat and AWS. In the {cluster-manager} web UI, you need to create these roles.
+Whether you manage your clusters using the `rosa` CLI or {cluster-manager} web UI, you must create the account-wide roles, known as `account-roles` in the `rosa` CLI, by using the `rosa` CLI. These account roles are necessary for your first cluster, and these roles can be used across multiple clusters. These required account roles are:
+
+1. `Worker-Role` 
+1. `Support-Role` 
+1. `Installer-Role` 
+1. `ControlPlane-Role`
 
 [NOTE]
 ====
-Role creation does not request your AWS access or secret keys. This is because it uses an AWS Secure Token Service (STS) as the basis of its workflow.
+Role creation does not request your AWS access or secret keys. AWS Secure Token Service (STS) is used as the basis of this workflow. AWS STS uses temporary, limited-privilege credentials to provide authentication.
 ====
+
+For more information about creating these roles, see xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies[Account-wide IAM role and policy reference].
+
+Cluster-specific Operator roles, known as `operator-roles` in the `rosa` CLI, obtain the temporary permissions required to carry out cluster operations, such as managing back-end storage, ingress, and registry. These roles are required by the cluster that you create. These required Operator roles are: 
+
+1. `<cluster_name>-<hash>-openshift-cluster-csi-drivers-ebs-cloud-credentials`
+1. `<cluster_name>-<hash>-openshift-cloud-network-config-controller-credentials`
+1. `<cluster_name>-<hash>-openshift-machine-api-aws-cloud-credentials`
+1. `<cluster_name>-<hash>-openshift-cloud-credential-operator-cloud-credentials`
+1. `<cluster_name>-<hash>-openshift-image-registry-installer-cloud-credentials`
+1. `<cluster_name>-<hash>-openshift-ingress-operator-cloud-credentials`
+
+For more information on creating these roles, see xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-operator-roles_rosa-sts-about-iam-resources[Cluster-specific Operator IAM role reference].
+
 include::modules/rosa-sts-about-ocm-role.adoc[leveloffset=+1]
+
+[discrete]
+[id="additional-resources-about-ocm-role"]
+[role="_additional-resources"]
+== Additional resources
+* See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-understanding-ocm-role[Understanding the OpenShift Cluster Manager role]
+
 include::modules/rosa-sts-ocm-role-creation.adoc[leveloffset=+2]
 include::modules/rosa-sts-about-user-role.adoc[leveloffset=+1]
 include::modules/rosa-sts-user-role-creation.adoc[leveloffset=+2]
@@ -30,3 +58,4 @@ include::modules/rosa-sts-aws-requirements-creating-multi-association.adoc[level
 [role="_additional-resources"]
 == Additional resources
 * See xref:../rosa_support/rosa-troubleshooting-iam-resources.adoc#rosa-sts-ocm-roles-and-permissions-troubleshooting[Troubleshooting IAM roles]
+* See xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies[Account-wide IAM role and policy reference] for a list of IAM roles needed for cluster creation.
