Merge pull request #49586 from pneedle-rh/osdocs-3803-adding-custom-arn-path-content

OSDOCS-3803 - Adding custom ARN path content for ROSA

Author: pneedle-rh

modules/rosa-create-objects.adoc

@@ -6,9 +6,52 @@
 [id="rosa-create-objects_{context}"]
 = Create objects
 
-
 This section describes the `create` commands for clusters and resources.
 
+[id="rosa-create-account-roles_{context}"]
+== create account-roles
+
+Create the needed account-wide role and policy resources for your cluster.
+
+.Syntax
+[source,terminal]
+----
+$ rosa create account-roles [flags]
+----
+
+.Flags
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--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
+
+|--path string
+|The ARN path for the account-wide roles and policies, including the Operator policies.
+
+|--permissions-boundary string
+|The ARN of the policy that is used to set the permissions boundary for the account roles.
+
+|--prefix string
+|User-defined prefix for all generated AWS resources. The default is `ManagedOpenShift`.
+
+|--profile string
+|Use a specific AWS profile from your credential file.
+
+|-y, --yes
+|Automatically answer yes to confirm operation.
+
+|===
+
 [id="rosa-create-admin_{context}"]
 == create admin
 
@@ -83,6 +126,9 @@ $ rosa create cluster --cluster=<cluster_name> | <cluster_id> [arguments]
 |--compute-nodes
 |The number (integer) of worker nodes to provision per zone. Single-zone clusters require at least 2 nodes. Multi-zone clusters require at least 3 nodes. Default: `2` for single-az; `3` for multi-az
 
+|--controlplane-iam-role string
+|The Amazon Resource Name (ARN) of the IAM role that will be attached to control plane instances.
+
 |--disable-scp-checks
 |Indicates whether cloud permission checks are disabled when attempting to install a cluster.
 
@@ -119,17 +165,25 @@ $ rosa create cluster --cluster=<cluster_name> | <cluster_id> [arguments]
 |--region
 |The AWS region (string) where your worker pool will be located. This argument overrides the `AWS_REGION` environment variable.
 
+|--role-arn string
+|The Amazon Resource Name (ARN) of the installer role that {cluster-manager} will assume to create the cluster.
+
 |--service-cidr
 |Block of IP addresses (ipNet) for services. Example: `172.30.0.0/16`
 
 |--subnet-ids
 |The subnet IDs (string) to use when installing the cluster. Subnet IDs must be in pairs with one private subnet ID and one public subnet ID per availability zone. Subnets are comma-delimited. Example: `--subnet-ids=subnet-1,subnet-2`. Leave the value empty for installer-provisioned subnet IDs.
 
-
 When using `--private-link`, the `--subnet-ids` argument is required and only one private subnet is allowed per zone.
 
+|--support-role-arn string
+|The Amazon Resource Name (ARN) of the role used by Red Hat Site Reliabilty Engineers (SREs) to enable access to the cluster account to provide support.
+
 |--version
 |The version (string) of OpenShift Container Platform that will be used to install the cluster. Example: `4.3.10`
+
+|--worker-iam-role string
+|The Amazon Resource Name (ARN) of the IAM role that will be attached to compute instances.
 |===
 
 .Optional arguments inherited from parent commands
@@ -499,7 +553,7 @@ $ rosa create machinepool --cluster=mycluster --replicas=2 --instance-type=r5.2x
 [id="rosa-create-ocm-role_{context}"]
 == create ocm-role
 
-Create the needed ocm-role resources for your cluster.
+Create the required ocm-role resources for your cluster.
 
 .Syntax
 [source,terminal]
@@ -522,25 +576,73 @@ $ rosa create ocm-role [flags]
 |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
+a|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
+
+|--path string
+|The ARN path for the OCM role and policies.
 
 |--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")
+|User-defined prefix for all generated AWS resources. The default is `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 role created with the `rosa create ocm-role` command, see _Account-wide IAM role and policy reference_.
+
+[id="rosa-create-user-role_{context}"]
+== create user-role
+
+Create the required user-role resources for your cluster.
+
+.Syntax
+[source,terminal]
+----
+$ rosa create user-role [flags]
+----
+
+.Flags
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--debug
+|Enable debug mode.
+
+|-i, --interactive
+|Enable interactive mode.
+
+|-m, --mode string
+a|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
+
+|--path string
+|The ARN path for the user role and policies.
+
+|--permissions-boundary string
+|The ARN of the policy that is used to set the permissions boundary for the user role.
+
+|--prefix string
+|User-defined prefix for all generated AWS resources The default is `ManagedOpenShift`.
+
+|--profile string
+|Use a specific AWS profile from your credential file.
 
 |-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.
+For more information about the user role created with the `rosa create user-role` command, see _Understanding AWS account association_.

modules/rosa-sts-arn-path-customization-for-iam-roles-and-policies.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-creating-a-cluster-with-customizations.adoc
+
+:_content-type: CONCEPT
+[id="rosa-sts-arn-path-customization-for-iam-roles-and-policies_{context}"]
+= ARN path customization for IAM roles and policies
+
+When you create the AWS IAM roles and policies required for {product-title} (ROSA) clusters that use the AWS Security Token Service (STS), you can specify custom Amazon Resource Name (ARN) paths. This enables you to use role and policy ARN paths that meet the security requirements of your organization.
+
+You can specify custom ARN paths when you create your OCM role, user role, and account-wide roles and policies.
+
+If you define a custom ARN path when you create a set of account-wide roles and policies, the same path is applied to all of the roles and policies in the set. The following example shows the ARNs for a set of account-wide roles and policies. In the example, the ARNs use the custom path `/test/path/dev/` and the custom role prefix `test-env`:
+
+* `arn:aws:iam::<account_id>:role/test/path/dev/test-env-Worker-Role`
+* `arn:aws:iam::<account_id>:role/test/path/dev/test-env-Support-Role`
+* `arn:aws:iam::<account_id>:role/test/path/dev/test-env-Installer-Role`
+* `arn:aws:iam::<account_id>:role/test/path/dev/test-env-ControlPlane-Role`
+* `arn:aws:iam::<account_id>:policy/test/path/dev/test-env-Worker-Role-Policy`
+* `arn:aws:iam::<account_id>:policy/test/path/dev/test-env-Support-Role-Policy`
+* `arn:aws:iam::<account_id>:policy/test/path/dev/test-env-Installer-Role-Policy`
+* `arn:aws:iam::<account_id>:policy/test/path/dev/test-env-ControlPlane-Role-Policy`
+
+When you create the cluster-specific Operator roles, the ARN path for the relevant account-wide installer role is automatically detected and applied to the Operator roles.
+
+For more information about ARN paths, see link:https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[Amazon Resource Names (ARNs)] in the AWS documentation.

modules/rosa-sts-creating-a-cluster-using-defaults-ocm.adoc

@@ -39,9 +39,7 @@ endif::[]
 
 . On the *Create an OpenShift cluster* page, select *Create cluster* in the *{product-title} (ROSA)* row.
 
-. Review and complete the *Prerequisites* listed on the *Accounts and roles* page. Select the checkbox to acknowledge that you have read and completed all of the prerequisites.
-
-. Verify that your AWS account ID is listed in the *Associated AWS accounts* drop-down menu and that the installer, support, worker, and control plane account role Amazon Resource Names (ARNs) are listed on the *Accounts and roles* page.
+. Verify that your AWS account ID is listed in the *Associated AWS accounts* drop-down menu and that the installer, support, worker, and control plane account role Amazon Resource Names (ARNs) are listed on the *Accounts and roles* page. 
 +
 [NOTE]
 ====

modules/rosa-sts-creating-a-cluster-with-customizations-cli.adoc

@@ -42,9 +42,57 @@ To successfully install ROSA clusters, use latest version of the ROSA CLI.
 +
 [source,terminal]
 ----
-$ rosa create account-roles --mode manual <1>
+$ rosa create account-roles --interactive \ <1>
+                            --mode manual <2>
 ----
-<1> `manual` mode generates the `aws` CLI commands and JSON files needed to create the account-wide roles and policies. After review, you must run the commands manually to create the resources.
+<1> `interactive` mode enables you to specify configuration options at the interactive prompts. For more information, see _Interactive cluster creation mode reference_.
+<2> `manual` mode generates the `aws` CLI commands and JSON files needed to create the account-wide roles and policies. After review, you must run the commands manually to create the resources.
++
+--
+.Example output
+[source,terminal]
+----
+I: Logged in as '<red_hat_username>' on 'https://api.openshift.com'
+I: Validating AWS credentials...
+I: AWS credentials are valid!
+I: Validating AWS quota...
+I: AWS quota ok. If cluster installation fails, validate actual AWS resource usage against https://docs.openshift.com/rosa/rosa_getting_started/rosa-required-aws-service-quotas.html
+I: Verifying whether OpenShift command-line tool is available...
+I: Current OpenShift Client Version: 4.11.6
+I: Creating account roles
+? Role prefix: ManagedOpenShift <1>
+? Permissions boundary ARN (optional): <2>
+? Path (optional): [? for help] <3>
+? Role creation mode: auto <4>
+I: Creating roles using 'arn:aws:iam::<aws_account_number>:user/<aws_username>'
+? Create the 'ManagedOpenShift-Installer-Role' role? Yes <5>
+I: Created role 'ManagedOpenShift-Installer-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Installer-Role'
+? Create the 'ManagedOpenShift-ControlPlane-Role' role? Yes <5>
+I: Created role 'ManagedOpenShift-ControlPlane-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-ControlPlane-Role'
+? Create the 'ManagedOpenShift-Worker-Role' role? Yes <5>
+I: Created role 'ManagedOpenShift-Worker-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Worker-Role'
+? Create the 'ManagedOpenShift-Support-Role' role? Yes <5>
+I: Created role 'ManagedOpenShift-Support-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Support-Role'
+I: To create a cluster with these roles, run the following command:
+rosa create cluster --sts
+----
+<1> Specify the prefix to include in the {cluster-manager} IAM role name. The default is `ManagedOpenShift`.
++
+[IMPORTANT]
+====
+You must specify an account-wide role prefix that is unique across your AWS account, even if you use a custom ARN path for your account roles.
+====
++
+<2> Optional: Specifies a permissions boundary Amazon Resource Name (ARN) for the role. For more information, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html[Permissions boundaries for IAM entities] in the AWS documentation.
+<3> Specify a custom ARN path for your account-wide roles. The path must contain alphanumeric characters only and start and end with `/`, for example `/test/path/dev/`. For more information, see _ARN path customization for IAM roles and policies_.
+<4> Select the role creation mode. You can use `auto` mode to automatically create the account wide roles and policies. In `manual` mode, the `rosa` CLI generates the `aws` commands needed to create the roles and policies. In `manual` mode, the corresponding policy JSON files are also saved to the current directory. `manual` mode enables you to review the details before running the `aws` commands manually.
+<5> Creates the account-wide installer, control plane, worker and support roles and corresponding IAM policies. For more information, see _Account-wide IAM role and policy reference_.
++
+[NOTE]
+====
+In this step, the ROSA CLI also automatically creates the account-wide Operator IAM policies that are used by the cluster-specific Operator policies to permit the ROSA cluster Operators to carry out core OpenShift functionality. For more information, see _Account-wide IAM role and policy reference_.
+====
+--
 +
 .. After review, run the `aws` commands manually to create the roles and policies. Alternatively, you can run the preceding command using `--mode auto` to run the `aws` commands immediately.
 
@@ -168,6 +216,7 @@ I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role for th
 ? AWS region: us-east-1
 ? PrivateLink cluster (optional): No
 ? Install into an existing VPC (optional): No
+? Select availability zones (optional): No
 ? Enable Customer Managed key (optional): No <5>
 ? Compute nodes instance type (optional):
 ? Enable autoscaling (optional): No
@@ -184,12 +233,16 @@ I: To create this cluster again in the future, you can run:
 I: To view a list of clusters and their status, run 'rosa list clusters'
 I: Cluster '<cluster_name>' has been created.
 I: Once the cluster is installed you will need to add an Identity Provider before you can login into the cluster. See 'rosa create idp --help' for more information.
-I: To determine when your cluster is Ready, run 'rosa describe cluster -c <cluster_name>'.
-I: To watch your cluster installation logs, run 'rosa logs install -c <cluster_name> --watch'.
+...
 ----
 <1> When creating the cluster, the listed `OpenShift version` options include the major, minor, and patch versions, for example `4.8.9`.
-<2> If more than one matching set of account-wide roles are available in your account for a cluster version, an interactive list of options is provided.
+<2> If you have more than one set of account roles in your AWS account for your cluster version, an interactive list of options is provided.
 <3> Optional: By default, the cluster-specific Operator role names are prefixed with the cluster name and random 4-digit hash. You can optionally specify a custom prefix to replace `<cluster_name>-<hash>` in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see _Defining an Operator IAM role prefix_.
++
+[NOTE]
+====
+If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.
+====
 <4> Multiple availability zones are recommended for production workloads. The default is a single availability zone.
 <5> Enable this option if you are using your own AWS KMS key to encrypt the control plane, infrastructure, worker node root volumes, and PVs. Specify the ARN for the KMS key that you added to the account-wide role ARN to in the preceding step.
 +
@@ -230,6 +283,8 @@ $ rosa create operator-roles --mode manual --cluster <cluster_name|cluster_id> <
 [NOTE]
 ====
 A custom prefix is applied to the Operator role names if you specified the prefix in the preceding step.
+
+If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected and applied to the Operator roles.
 ====
 
 . Create the OpenID Connect (OIDC) provider that the cluster Operators use to authenticate: