[OSDOCS-5240] Installer support to automatically create the MachineSets when installing in existing VPC on AWS w/Local Zones (#57427)

Co-authored-by: Marco Braga <[email protected]>
Co-authored-by: Yunfei Jiang <[email protected]>

Author: 3 people

installing/installing_aws/installing-aws-localzone.adoc

@@ -41,6 +41,24 @@ If you have an AWS profile stored on your computer, it must not use a temporary
 Be sure to also review this site list if you are configuring a proxy.
 ====
 * If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials].
+* Add permission for the user who creates the cluster to modify the Local Zone group with `ec2:ModifyAvailabilityZoneGroup`. For example:
++
+.An example of a permissive IAM policy to attach to a user or role
+[source,yaml]
+----
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "ec2:ModifyAvailabilityZoneGroup"
+      ],
+      "Effect": "Allow",
+      "Resource": "*"
+    }
+  ]
+}
+----
 
 include::modules/cluster-limitations-local-zone.adoc[leveloffset=+1]
 
@@ -51,14 +69,14 @@ include::modules/cluster-limitations-local-zone.adoc[leveloffset=+1]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
-include::modules/installation-aws-add-local-zone-locations.adoc[leveloffset=+1]
-
 include::modules/installation-aws-marketplace-subscribe.adoc[leveloffset=+1]
 
 include::modules/installation-creating-aws-vpc-localzone.adoc[leveloffset=+1]
 
 include::modules/installation-cloudformation-vpc-localzone.adoc[leveloffset=+2]
 
+include::modules/installation-aws-add-local-zone-locations.adoc[leveloffset=+1]
+
 include::modules/installation-creating-aws-subnet-localzone.adoc[leveloffset=+1]
 
 include::modules/installation-cloudformation-subnet-localzone.adoc[leveloffset=+2]
@@ -82,6 +100,17 @@ include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
 * See link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] in the AWS documentation for more information about AWS Local Zones and the supported instances types and services. 
 
 include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]
+// Suggest to standarize edge-pool's specific files with same prefixes, like: machine-edge-pool-[...] or compute-edge-pool-[...] (which is more compatible with install-config.yaml/compute)
+include::modules/machines-edge-machine-pool.adoc[leveloffset=+2]
+include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+3]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/changing-cluster-network-mtu.adoc#mtu-value-selection_changing-cluster-network-mtu[Changing the MTU for the cluster network]
+* xref:../../networking/changing-cluster-network-mtu.adoc#nw-ovn-ipsec-enable_configuring-ipsec-ovn[Enabling IPsec encryption]
+
+include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
@@ -91,13 +120,9 @@ include::modules/installation-generate-aws-user-infra-install-config.adoc[levelo
 //include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 //Put this back if QE validates it.
 
-include::modules/installation-localzone-generate-k8s-manifest.adoc[leveloffset=+2]
+// Verify removal due to automation.
+// include::modules/installation-localzone-generate-k8s-manifest.adoc[leveloffset=+2]
 
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../networking/changing-cluster-network-mtu.adoc#mtu-value-selection_changing-cluster-network-mtu[Changing the MTU for the cluster network]
-* xref:../../networking/changing-cluster-network-mtu.adoc#nw-ovn-ipsec-enable_configuring-ipsec-ovn[Enabling IPsec encryption]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
@@ -115,6 +140,8 @@ include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1]
 
 * See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console.
 
+include::modules/machine-edge-pool-review-nodes.adoc[leveloffset=+1]
+
 include::modules/cluster-telemetry.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -125,6 +152,7 @@ include::modules/cluster-telemetry.adoc[leveloffset=+1]
 [id="installing-aws-localzone-next-steps"]
 == Next steps
 
+* xref:../../post_installation_configuration/cluster-tasks.adoc#installation-extend-edge-nodes-aws-local-zones_post-install-cluster-tasks[Creating user workloads in AWS Local Zones].
 * xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation].
 * xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster].
 * If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting].

modules/edge-machine-pools-aws-local-zones.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+// * installing/installing_aws/installing-aws-localzone.adoc
+
+:_content-type: CONCEPT
+[id="edge-machine-pools-aws-local-zones_{context}"]
+= Edge compute pools and AWS Local Zones
+
+Edge worker nodes are tainted worker nodes that run in AWS Local Zones locations.
+
+When deploying a cluster that uses Local Zones:
+
+* Amazon EC2 instances in the Local Zones are more expensive than Amazon EC2 instances in the Availability Zones.
+* Latency between applications and end users is lower in Local Zones, and it may vary by location. There is a latency impact for some workloads if, for example, routers are mixed between Local Zones and Availability Zones.
+* The cluster-network Maximum Transmission Unit (MTU) is adjusted automatically to the lower restricted by AWS when Local Zone subnets are detected on the `install-config.yaml`, according to the network plugin. For example, the adjusted values are 1200 for OVN-Kubernetes and 1250 for OpenShift SDN. If additional features are enabled, manual MTU adjustment can be necessary.
+
+[IMPORTANT]
+====
+Generally, the Maximum Transmission Unit (MTU) between an Amazon EC2 instance in a Local Zone and an Amazon EC2 instance in the Region is 1300. For more information, see link:https://docs.aws.amazon.com/local-zones/latest/ug/how-local-zones-work.html[How Local Zones work] in the AWS documentation. 
+The cluster network MTU must be always less than the EC2 MTU to account for the overhead. The specific overhead is determined by the network plugin, for example:
+
+- OVN-Kubernetes: `100 bytes`
+- OpenShift SDN: `50 bytes`
+
+The network plugin can provide additional features, like IPsec, that also must be decreased the MTU. For additional information, see the documentation.
+====

modules/install-creating-install-config-aws-local-zones.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+// * installing/installing_aws/installing-aws-localzone.adoc
+
+:_content-type: PROCEDURE
+[id="install-creating-install-config-aws-local-zones_{context}"]
+= Modifying an installation configuration file to use AWS Local Zones subnets
+
+Modify an `install-config.yaml` file to include AWS Local Zones subnets.
+
+.Prerequisites
+
+* You created subnets by using the procedure "Creating a subnet in AWS Local Zones".
+* You created an `install-config.yaml` file by using the procedure "Creating the installation configuration file".
+
+.Procedure
+
+* Add the VPC and Local Zone subnets as the values of the `platform.aws.subnets` property. As an example:
++
+[source,yaml]
+----
+...
+platform:
+  aws:
+    region: us-west-2
+    subnets: <1>
+    - publicSubnetId-1
+    - publicSubnetId-2
+    - publicSubnetId-3
+    - privateSubnetId-1
+    - privateSubnetId-2
+    - privateSubnetId-3
+    - publicSubnetId-LocalZone-1
+...
+----
+<1> List of subnets created in the Availability and Local Zones.

modules/installation-aws-add-local-zone-locations.adoc

@@ -23,29 +23,32 @@ $ export CLUSTER_REGION="<region_name>" <1>
 ----
 <1> For `<region_name>`, specify a valid AWS region name, such as `us-east-1`.
 
-. Review the list of zones that your region contains by running the following command:
+. List the zones that are available in your region by running the following command:
 +
 [source,terminal]
 ----
-$ aws ec2 describe-availability-zones \
-    --filters Name=region-name,Values=${CLUSTER_REGION} \
-    --query 'AvailabilityZones[].ZoneName' \
+$ aws --region ${CLUSTER_REGION} ec2 describe-availability-zones \
+    --query 'AvailabilityZones[].[{ZoneName: ZoneName, GroupName: GroupName, Status: OptInStatus}]' \
+    --filters Name=zone-type,Values=local-zone \
     --all-availability-zones
 ----
 +
-Depending on the region, the list of available zones can be long. The different zones use the following naming conventions:
+Depending on the region, the list of available zones can be long. The command will return the following fields:
 +
-`${REGION}[a-z]`:: Availability zones available in the region.
-`${REGION}-LID-N[a-z]`:: Available AWS Local Zones. `${REGION}LID-N` is the zone group identifier, and `[a-z]` is the zone identifier.
-`${REGION}-wl1-LID-wlz-[1-9]`:: Available Wavelength zones.
+`ZoneName`:: The name of the Local Zone.
+`GroupName`:: The group that the zone is part of. You need to save this name to opt in.
+`Status`:: The status of the Local Zone group. If the status is `not-opted-in`, you must opt in the `GroupName` by running the commands that follow.
 
 . Export a variable to contain the name of the Local Zone to host your VPC by running the following command:
 +
 [source,terminal]
 ----
-$ export ZONE_GROUP_NAME="${CLUSTER_REGION}-<location_identifier>-<zone_identifier>" <1>
+$ export ZONE_GROUP_NAME="<value_of_GroupName>" <1>
 ----
-<1> For `<location_identifier>-<zone_identifier>`, specify the location identifier and zone identifier for the Local Zone that you selected for your region. For example, specify `nyc-1a` to use the US East (New York) Local Zone.
++
+where:
+
+<value_of_GroupName>:: Specifies the name of the group of the Local Zone you want to create subnets on. For example, specify `us-east-1-nyc-1` to use the zone `us-east-1-nyc-1a`, US East (New York).
 
 . Opt in to the zone group on your AWS account by running the following command:
 +

modules/installation-cloudformation-subnet-localzone.adoc

@@ -16,20 +16,17 @@ you need for your {product-title} cluster that uses AWS Local Zones.
 ----
 # CloudFormation template used to create Local Zone subnets and dependencies
 AWSTemplateFormatVersion: 2010-09-09
-Description: Template for Best Practice VPC with 1-3 AZs
+Description: Template for create Public Local Zone subnets
 
 Parameters:
-  ClusterName:
-    Description: ClusterName used to prefix resource names
-    Type: String
   VpcId:
     Description: VPC Id
     Type: String
-  LocalZoneName:
-    Description: Local Zone Name (Example us-east-1-bos-1)
+  ZoneName:
+    Description: Local Zone Name (Example us-east-1-nyc-1a)
     Type: String
-  LocalZoneNameShort:
-    Description: Short name for Local Zone used on tag Name (Example bos1)
+  SubnetName:
+    Description: Local Zone Name (Example cluster-public-us-east-1-nyc-1a)
     Type: String
   PublicRouteTableId:
     Description: Public Route Table ID to associate the Local Zone subnet
@@ -47,12 +44,10 @@ Resources:
     Properties:
       VpcId: !Ref VpcId
       CidrBlock: !Ref PublicSubnetCidr
-      AvailabilityZone: !Ref LocalZoneName
+      AvailabilityZone: !Ref ZoneName
       Tags:
       - Key: Name
-        Value: !Join
-          - ""
-          - [ !Ref ClusterName, "-public-", !Ref LocalZoneNameShort, "-1" ]
+        Value: !Ref SubnetName
       - Key: kubernetes.io/cluster/unmanaged
         Value: "true"
 
@@ -66,9 +61,6 @@ Outputs:
   PublicSubnetIds:
     Description: Subnet IDs of the public subnets.
     Value:
-      !Join [
-        "",
-        [!Ref PublicSubnet]
-      ]
+      !Join ["", [!Ref PublicSubnet]]
 ----
 ====