OSDOCS-6652 AWS shared private hosted zones

Author: bscott-rh

installing/installing_aws/installing-aws-vpc.adoc

@@ -14,6 +14,7 @@ parameters in the `install-config.yaml` file before you install the cluster.
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[configured an AWS account] to host the cluster.
+* If the existing VPC is owned by a different account than the cluster, you link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html[shared the VPC] between accounts.
 +
 [IMPORTANT]
 ====
@@ -23,6 +24,7 @@ If you have an AWS profile stored on your computer, it must not use a temporary
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
 include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
+include::modules/installation-aws-permissions-iam-shared-vpc.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 

modules/installation-aws-permissions-iam-shared-vpc.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assembly:
+// * installing/installing_aws/installing-aws-account.adoc
+
+:_content-type: REFERENCE
+[id="installation-aws-permissions-iam-shared-vpc_{context}"]
+= Modifying trust policy when installing into a shared VPC
+If you install your cluster using a shared VPC, you can use the `Passthrough` or `Manual` credentials mode. You must add the IAM role used to install the cluster as a principal in the trust policy of the account that owns the VPC.
+
+If you use `Passthrough` mode, add the Amazon Resource Name (ARN) of the account that creates the cluster, such as `arn:aws:iam::123456789012:user/clustercreator`, to the trust policy as a principal. 
+
+If you use `Manual` mode, add the ARN of the account that creates the cluster as well as the ARN of the ingress operator role in the cluster owner account, such as `arn:aws:iam::123456789012:role/<cluster-name>-openshift-ingress-operator-cloud-credentials`, to the trust policy as principals.
+ 
+You must add the following actions to the policy:
+
+.Required actions for shared VPC installation
+[%collapsible]
+====
+* `route53:ChangeResourceRecordSets`
+* `route53:ListHostedZones`
+* `route53:ListHostedZonesByName`
+* `route53:ListResourceRecordSets`
+* `route53:ChangeTagsForResource`
+* `route53:GetAccountLimit`
+* `route53:GetChange`
+* `route53:GetHostedZone`
+* `route53:ListTagsForResource`
+* `route53:UpdateHostedZoneComment`
+* `tag:GetResources`
+* `tag:UntagResources`
+====

modules/installation-aws-permissions.adoc

@@ -291,3 +291,9 @@ If you are managing your cloud provider credentials with mint mode, the IAM user
 * `ec2:DescribeInstanceTypeOfferings`
 * `servicequotas:ListAWSDefaultServiceQuotas`
 ====
+
+.Optional permissions for the cluster owner account when installing a cluster on a shared VPC
+[%collapsible]
+====
+* `sts:AssumeRole` 
+====

modules/installation-configuration-parameters.adoc

@@ -763,6 +763,10 @@ belong to the same region as the cluster. This is required for regions that requ
 |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.hostedZoneRole`
+|An Amazon Resource Name (ARN) for an existing IAM role in the account containing the specified hosted zone. The installation program and cluster operators will assume this role when performing operations on the hosted zone. This parameter should only be used if you are installing a cluster into a shared VPC.
+|String, for example `arn:aws:iam::1234567890:role/shared-vpc-role`.
+
 |`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

modules/installation-custom-aws-vpc.adoc

@@ -27,7 +27,7 @@ ifndef::aws-outposts[]
 In {product-title} {product-version}, you can deploy a cluster into existing subnets in an existing Amazon Virtual Private Cloud (VPC) in Amazon Web Services (AWS). By deploying {product-title} into an existing AWS VPC, you might be able to avoid limit constraints in new accounts or more easily abide by the operational constraints that your company's guidelines set. If you cannot obtain the infrastructure creation permissions that are required to create the VPC yourself, use this installation option.
 endif::aws-outposts[]
 ifdef::aws-outposts[]
-{product-title} {product-version} installer cannot automatically deploy AWS Subnets on AWS Outposts, so you will need to manually configure the VPC. Therefore, you have to deploy the cluster into existing subnets in an existing Amazon Virtual Private Cloud (VPC) in Amazon Web Services (AWS). In addition, by deploying {product-title} into an existing AWS VPC, you might be able to avoid limit constraints in new accounts or more easily abide by the operational constraints that your company’s guidelines set.
+{product-title} {product-version} installer cannot automatically deploy AWS Subnets on AWS Outposts, so you will need to manually configure the VPC. Therefore, you have to deploy the cluster into existing subnets in an existing Amazon Virtual Private Cloud (VPC) in Amazon Web Services (AWS). In addition, by deploying {product-title} into an existing AWS VPC, you might be able to avoid limit constraints in new accounts or more easily abide by the operational constraints that your company's guidelines set.
 endif::aws-outposts[]
 
 Because the installation program cannot know what other components are also in your existing subnets, it cannot choose subnet CIDRs and so forth on your behalf. You must configure networking for the subnets that you install your cluster to yourself.
@@ -101,7 +101,8 @@ endif::aws-outposts[]
 The installation program modifies your subnets to add the `kubernetes.io/cluster/.*: shared` tag, so your subnets must have at least one free tag slot available for it. See link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions[Tag Restrictions] in the AWS documentation to confirm that the installation program can add a tag to each subnet that you specify. You cannot use a `Name` tag, because it overlaps with the EC2 `Name` field and the installation fails.
 * 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 to use 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 prefer to use 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` and `platform.aws.hostedZoneRole` fields in the `install-config.yaml` file.
+You can use a private hosted zone from another account by sharing it with the account where you install the cluster. If you use a private hosted zone from another account, you must use the `Passthrough` or `Manual` credentials mode.
 
 ifndef::aws-secret,aws-outposts[]
 If you are working in a disconnected environment, you are unable to reach the public IP addresses for EC2, ELB, and S3 endpoints. Depending on the level to which you want to restrict internet traffic during the installation, the following configuration options are available: