openshift · kalexand-rh · May 20, 2021 · Apr 20, 2021
diff --git a/installing/installing_aws/installing-aws-account.adoc b/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

diff --git a/modules/installation-aws-config-yaml.adoc b/modules/installation-aws-config-yaml.adoc
@@ -126,6 +126,7 @@ ifdef::vpc,restricted[]
     serviceEndpoints: <9>
       - name: ec2
         url: https://vpce-id.ec2.us-west-2.vpce.amazonaws.com
+    hostedZone: Z3URY6TWQ91KVV <10>
 endif::vpc,restricted[]
 ifndef::vpc,restricted[]
     amiID: ami-96c6f8f7 <7>
@@ -135,11 +136,11 @@ ifndef::vpc,restricted[]
 endif::vpc,restricted[]
 ifdef::vpc,restricted[]
 ifndef::openshift-origin[]
-fips: false <10>
-sshKey: ssh-ed25519 AAAA... <11>
+fips: false <11>
+sshKey: ssh-ed25519 AAAA... <12>
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-sshKey: ssh-ed25519 AAAA... <10>
+sshKey: ssh-ed25519 AAAA... <11>
 endif::openshift-origin[]
 endif::vpc,restricted[]
 ifndef::vpc,restricted[]
@@ -153,7 +154,7 @@ endif::openshift-origin[]
 endif::vpc,restricted[]
 ifdef::private[]
 ifndef::openshift-origin[]
-publish: Internal <12>
+publish: Internal <13>
 endif::openshift-origin[]
 endif::private[]
 ifndef::restricted[]
@@ -164,20 +165,20 @@ pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "yo
 endif::restricted[]
 ifdef::gov[]
 ifndef::openshift-origin[]
-additionalTrustBundle: | <13>
+additionalTrustBundle: | <14>
     -----BEGIN CERTIFICATE-----
     <MY_TRUSTED_CA_CERT>
     -----END CERTIFICATE-----
 endif::openshift-origin[]
 endif::gov[]
 ifdef::private[]
 ifdef::openshift-origin[]
-publish: Internal <11>
+publish: Internal <12>
 endif::openshift-origin[]
 endif::private[]
 ifdef::gov[]
 ifdef::openshift-origin[]
-additionalTrustBundle: | <12>
+additionalTrustBundle: | <13>
     -----BEGIN CERTIFICATE-----
     <MY_TRUSTED_CA_CERT>
     -----END CERTIFICATE-----
@@ -236,13 +237,14 @@ must belong to the same region as the cluster.
 <9> The AWS service endpoints. Custom endpoints are required when installing to
 an unknown AWS region. The endpoint URL must use the `https` protocol and the
 host must trust the certificate.
+<10> The ID of your existing Route 53 private hosted zone. Providing an existing hosted zone requires that you supply your own VPC and the hosted zone is already associated with the VPC prior to installing your cluster. If undefined, the installation program creates a new hosted zone.
 ifndef::openshift-origin[]
-<10> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
-<11> You can optionally provide the `sshKey` value that you use to access the
+<11> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
+<12> You can optionally provide the `sshKey` value that you use to access the
 machines in your cluster.
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-<10> You can optionally provide the `sshKey` value that you use to access the
+<11> You can optionally provide the `sshKey` value that you use to access the
 machines in your cluster.
 endif::openshift-origin[]
 endif::vpc,restricted[]
@@ -268,10 +270,10 @@ endif::vpc,restricted[]
 For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses.
 ====
 ifdef::private[]
-<12> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`.
+<13> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`.
 endif::private[]
 ifdef::gov[]
-<13> The custom CA certificate. This is required when deploying to the AWS C2S Secret Region because the AWS API requires a custom CA trust bundle.
+<14> The custom CA certificate. This is required when deploying to the AWS C2S Secret Region because the AWS API requires a custom CA trust bundle.
 endif::gov[]
 ifdef::restricted[]
 <12> For `<local_registry>`, specify the registry domain name, and optionally the

diff --git a/modules/installation-aws-permissions-iam-roles.adoc b/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 cloud identity and access management (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`
+====
diff --git a/modules/installation-aws-permissions.adoc b/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}

diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc
@@ -402,6 +402,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`.
@@ -432,6 +436,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`.
@@ -450,6 +458,10 @@ control plane machine pool.
 belong to the same region as 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.
 
+|`platform.aws.hostedZone`
+|An existing Route 53 private hosted zone for the cluster. You can only use a pre-existing hosted zone when also supplying your own VPC. The hosted zone must already be associated with the user-provided VPC before installation. Also, the domain of the hosted zone must be the cluster domain or a parent of the cluster domain. If undefined, the installation program creates a new hosted zone.
+|String, for example `Z3URY6TWQ91KVV`.
+
 |`platform.aws.serviceEndpoints.name`
 |The AWS service endpoint name. Custom endpoints are only required for cases
 where alternative AWS endpoints, like FIPS, must be used. Custom API endpoints

diff --git a/modules/installation-custom-aws-vpc.adoc b/modules/installation-custom-aws-vpc.adoc
@@ -30,7 +30,7 @@ Your VPC must meet the following characteristics:
 
 * The VPC's CIDR block must contain the `Networking.MachineCIDR` range, which is the IP address pool for cluster machines.
 * The VPC must not use the `kubernetes.io/cluster/.*: owned` tag.
-* You must enable the `enableDnsSupport` and `enableDnsHostnames` attributes in your VPC so that the cluster can use the Route 53 zones that are attached to the VPC to resolve cluster’s internal DNS records. See link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support[DNS Support in Your VPC] in the AWS documentation.
+* You must enable the `enableDnsSupport` and `enableDnsHostnames` attributes in your VPC so that the cluster can use the Route 53 zones that are attached to the VPC to resolve cluster’s internal DNS records. See link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support[DNS Support in Your VPC] in the AWS documentation. If you prefer using your own Route 53 hosted private zone, you must associate the existing hosted zone with your VPC prior to installing a cluster. You can define your hosted zone using the `platform.aws.hostedZone` field in the `install-config.yaml` file.
 
 If you use a cluster with public access, you must create a public and a private subnet for each availability zone that your cluster uses.