Merge pull request #38264 from mjpytlak/osdocs-1968

OSDOCS:1968 - Updated Requirements for using your VPC with links to AWS doc

Author: bmcelvee

modules/installation-custom-aws-vpc.adoc

@@ -4,11 +4,15 @@
 // * installing/installing_aws/installing-aws-private.adoc
 // * installing/installing_aws/installing-aws-vpc.adoc
 
-[id="installation-custom-aws-vpc_{context}"]
-= About using a custom VPC
 ifeval::["{context}" == "installing-aws-china-region"]
 :aws-china:
 endif::[]
+ifeval::["{context}" == "installing-aws-vpc"]
+:public:
+endif::[]
+
+[id="installation-custom-aws-vpc_{context}"]
+= About using a custom VPC
 
 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.
 
@@ -27,17 +31,37 @@ The installation program no longer creates the following components:
 * VPC DHCP options
 * VPC endpoints
 
-If you use a custom VPC, you must correctly configure it and its subnets for the installation program and the cluster to use. The installation program cannot subdivide network ranges for the cluster to use, set route tables for the subnets, or set VPC options like DHCP, so you must do so before you install the cluster.
+If you use a custom VPC, you must correctly configure it and its subnets for the installation program and the cluster to use. See link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_wizard.html[Amazon VPC console wizard configurations] and link:https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html[Work with VPCs and subnets] in the AWS documentation for more information on creating and managing an AWS VPC.
 
-Your VPC must meet the following characteristics:
+The installation program cannot:
 
-* 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. 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.
+* Subdivide network ranges for the cluster to use.
+* Set route tables for the subnets.
+* Set VPC options like DHCP.
+
+You must complete these tasks before you install the cluster. See link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Networking.html[VPC networking components] and link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html[Route tables for your VPC] for more information on configuring networking in an AWS VPC.
 
-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.
+Your VPC must meet the following characteristics:
 
-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. Review the current link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions[Tag Restrictions] in the AWS documentation to ensure that the installation program can add a tag to each subnet that you specify.
+ifdef::public[]
+* Create a public and private subnet for each availability zone that your cluster uses. Each availability zone can contain no more than one public and one private subnet. For an example of this type of configuration, see link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html[VPC with public and private subnets (NAT)] in the AWS documentation.
++
+Record each subnet ID. Completing the installation requires that you enter these values in the `platform` section of the `install-config.yaml` file. See link:https://docs.aws.amazon.com/managedservices/latest/userguide/find-subnet.html[Finding a subnet ID] in the AWS documentation.
+* The VPC's CIDR block must contain the `Networking.MachineCIDR` range, which is the IP address pool for cluster machines. The subnet CIDR blocks must belong to the machine CIDR that you specify.
+* The VPC must have a public internet gateway attached to it. For each availability zone:
+** The public subnet requires a route to the internet gateway.
+** The public subnet requires a NAT gateway with an EIP address.
+** The private subnet requires a route to the NAT gateway in public subnet.
+endif::public[]
+* The VPC must not use the `kubernetes.io/cluster/.*: owned` tag.
++
+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 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.
+ifndef::public[]
+* 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. Each availability zone can contain no more than one public and one private subnet.
+endif::public[]
 
 ifndef::aws-china[]
 If you are working in a disconnected environment, you are unable to reach the public IP addresses for EC2 and ELB endpoints. To resolve this, you must create a VPC endpoint and attach it to the subnet that the clusters are using. The endpoints should be named as follows:
@@ -160,4 +184,7 @@ If you deploy {product-title} to an existing network, the isolation of cluster s
 ifeval::["{context}" == "installing-aws-china-region"]
 :!aws-china:
 endif::[]
+ifeval::["{context}" == "installing-aws-vpc"]
+:!public:
+endif::[]
 //This should be restricted to the control plane and compute security groups, instead of the current by-VPC-CIDR logic to avoid leaking sensitive Ignition configs to non-cluster entities sharing the VPC.