OSDOCS-1871 Supplying predefined IAM roles to the cluster

installing/installing_aws/installing-aws-account.adoc

@@ -22,6 +22,8 @@ include::modules/installation-aws-iam-user.adoc[leveloffset=+1]
 
 * See xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS] for steps to set the Cloud Credential Operator (CCO) to manual mode prior to installation. Use this mode in environments where the cloud identity and access management (IAM) APIs are not reachable, or if you prefer not to store an administrator-level credential secret in the cluster `kube-system` project.
 
+include::modules/installation-aws-permissions-iam-roles.adoc[leveloffset=+1]
+
 include::modules/installation-aws-regions.adoc[leveloffset=+1]
 
 == Next steps

modules/installation-aws-permissions-iam-roles.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-account.adoc
+
+[id="installation-aws-permissions-iam-roles_{context}"]
+= Required AWS permissions for IAM roles
+
+You have the option of defining your own IAM roles that are applied to the instance profiles of your machines created by the installation program. You can specify existing IAM roles by defining the `controlPlane.platform.aws.iamRole` and `compute.platform.aws.iamRoleThis` fields in the `install-config.yaml` file. You can use these fields to match naming schemes and include predefined permissions boundaries for your IAM roles.
+
+The control plane and compute machines require the following IAM role permissions:
+
+.Required IAM role permissions for control plane instance profiles
+[%collapsible]
+====
+* `sts:AssumeRole`
+* `ec2:AttachVolume`
+* `ec2:AuthorizeSecurityGroupIngress`
+* `ec2:CreateSecurityGroup`
+* `ec2:CreateTags`
+* `ec2:CreateVolume`
+* `ec2:DeleteSecurityGroup`
+* `ec2:DeleteVolume`
+* `ec2:Describe*`
+* `ec2:DetachVolume`
+* `ec2:ModifyInstanceAttribute`
+* `ec2:ModifyVolume`
+* `ec2:RevokeSecurityGroupIngress`
+* `elasticloadbalancing:AddTags`
+* `elasticloadbalancing:AttachLoadBalancerToSubnets`
+* `elasticloadbalancing:ApplySecurityGroupsToLoadBalancer`
+* `elasticloadbalancing:CreateListener`
+* `elasticloadbalancing:CreateLoadBalancer`
+* `elasticloadbalancing:CreateLoadBalancerPolicy`
+* `elasticloadbalancing:CreateLoadBalancerListeners`
+* `elasticloadbalancing:CreateTargetGroup`
+* `elasticloadbalancing:ConfigureHealthCheck`
+* `elasticloadbalancing:DeleteListener`
+* `elasticloadbalancing:DeleteLoadBalancer`
+* `elasticloadbalancing:DeleteLoadBalancerListeners`
+* `elasticloadbalancing:DeleteTargetGroup`
+* `elasticloadbalancing:DeregisterInstancesFromLoadBalancer`
+* `elasticloadbalancing:DeregisterTargets`
+* `elasticloadbalancing:Describe*`
+* `elasticloadbalancing:DetachLoadBalancerFromSubnets`
+* `elasticloadbalancing:ModifyListener`
+* `elasticloadbalancing:ModifyLoadBalancerAttributes`
+* `elasticloadbalancing:ModifyTargetGroup`
+* `elasticloadbalancing:ModifyTargetGroupAttributes`
+* `elasticloadbalancing:RegisterInstancesWithLoadBalancer`
+* `elasticloadbalancing:RegisterTargets`
+* `elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer`
+* `elasticloadbalancing:SetLoadBalancerPoliciesOfListener`
+* `kms:DescribeKey`
+====
+
+.Required IAM role permissions for compute instance profiles
+[%collapsible]
+====
+* `sts:AssumeRole`
+* `ec2:DescribeInstances`
+* `ec2:DescribeRegions`
+====

modules/installation-aws-permissions.adoc

@@ -5,7 +5,7 @@
 // * installing/installing_aws/installing-restricted-networks-aws.adoc
 
 [id="installation-aws-permissions_{context}"]
-= Required AWS permissions
+= Required AWS permissions for the IAM user
 
 When you attach the `AdministratorAccess` policy to the IAM user that you create in Amazon Web Services (AWS),
 you grant that user all of the required permissions. To deploy all components of an {product-title}

modules/installation-configuration-parameters.adoc

@@ -355,6 +355,10 @@ ifdef::aws[]
 |The AWS AMI used to boot compute machines for the cluster. This is required for regions that require a custom {op-system} AMI.
 |Any published or custom {op-system} AMI that belongs to the set AWS region.
 
+|`compute.platform.aws.iamRole`
+|A pre-existing AWS IAM role applied to the compute machine pool instance profiles. You can use these fields to match naming schemes and include predefined permissions boundaries for your IAM roles. If undefined, the installation program creates a new IAM role.
+|The name of a valid AWS IAM role.
+
 |`compute.platform.aws.rootVolume.iops`
 |The Input/Output Operations Per Second (IOPS) that is reserved for the root volume.
 |Integer, for example `4000`.
@@ -385,6 +389,10 @@ link:https://yaml.org/spec/1.2/spec.html#sequence//[YAML sequence].
 |The AWS AMI used to boot control plane machines for the cluster.  This is required for regions that require a custom {op-system} AMI.
 |Any published or custom {op-system} AMI that belongs to the set AWS region.
 
+|`controlPlane.platform.aws.iamRole`
+|A pre-existing AWS IAM role applied to the control plane machine pool instance profiles. You can use these fields to match naming schemes and include predefined permissions boundaries for your IAM roles. If undefined, the installation program creates a new IAM role.
+|The name of a valid AWS IAM role.
+
 |`controlPlane.platform.aws.type`
 |The EC2 instance type for the control plane machines.
 |Valid link:https://aws.amazon.com/ec2/instance-types/[AWS instance type], such as `c5.9xlarge`.