openshift · JoeAldinger · Sep 20, 2023 · Jun 1, 2023
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -179,7 +179,7 @@ Topics:
     File: installing-aws-china
   - Name: Installing a cluster on AWS using CloudFormation templates
     File: installing-aws-user-infra
-  - Name: Installing a cluster using AWS Local Zones
+  - Name: Installing a cluster on AWS with worker nodes on AWS Local Zones
     File: installing-aws-localzone
   - Name: Installing a cluster on AWS in a restricted network with user-provisioned infrastructure
     File: installing-restricted-networks-aws

diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc
@@ -1,24 +1,18 @@
 :_content-type: ASSEMBLY
 [id="installing-aws-localzone"]
-= Installing a cluster using AWS Local Zones
+= Installing a cluster on AWS with worker nodes on AWS Local Zones
 include::_attributes/common-attributes.adoc[]
 :context: installing-aws-localzone
 
 toc::[]
 
-In {product-title} version {product-version}, you can install a cluster on Amazon Web Services (AWS) into an existing VPC, extending workers to the edge of the Cloud Infrastructure using AWS Local Zones.
+You can quickly install an {product-title} cluster in Amazon Web Services (AWS) Local Zones by setting the zone names in the edge compute pool of the `install-config.yaml` file, or install a cluster in an existing VPC that lists Local Zone subnets.
 
-After you create an Amazon Web Service (AWS) Local Zone environment, and you deploy your cluster, you can use edge worker nodes to create user workloads in Local Zone subnets.
-
-AWS Local Zones are a type of infrastructure that place Cloud Resources close to the metropolitan regions. For more information, see the link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-local-zones[AWS Local Zones Documentation].
-
-{product-title} can be installed in existing VPCs with Local Zone subnets. The Local Zone subnets can be used to extend the regular workers' nodes to the edge networks. The edge worker nodes are dedicated to running user workloads.
-
-One way to create the VPC and subnets is to use the provided CloudFormation templates. You can modify the templates to customize your infrastructure or use the information that they contain to create AWS objects according to your company's policies.
+AWS Local Zones are a type of infrastructure that place Cloud Resources close to metropolitan regions. For more information, see the link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-local-zones[AWS Local Zones Documentation].
 
 [IMPORTANT]
 ====
-The steps for performing an installer-provisioned infrastructure installation are provided as an example only. Installing a cluster with VPC you provide requires knowledge of the cloud provider and the installation process of {product-title}. The CloudFormation templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example.
+The steps for performing an installer-provisioned infrastructure installation are provided for example purposes only. Installing a cluster in an existing VPC requires that you have knowledge of the cloud provider and the installation process of {product-title}. You can use a CloudFormation template to assist you with completing these steps or to help model your own cluster installation. Instead of using the CloudFormation template to create resources, you can decide to use other methods for generating these resources.
 ====
 
 == Prerequisites
@@ -59,38 +53,65 @@ Be sure to also review this site list if you are configuring a proxy.
 }
 ----
 
+// Cluster limitations in AWS Local Zones
 include::modules/cluster-limitations-local-zone.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../storage/understanding-persistent-storage.adoc#pvc-storage-class_understanding-persistent-storage[Storage classes]
 
+* xref:../../networking/ingress-sharding.html#nw-ingress-sharding_ingress-sharding[Ingress Controller sharding]
+
+// Internet access for OpenShift Container Platform
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
+// Obtaining an AWS Marketplace image
 include::modules/installation-aws-marketplace-subscribe.adoc[leveloffset=+1]
 
-include::modules/installation-creating-aws-vpc-localzone.adoc[leveloffset=+1]
+//Installing the OpenShift CLI by downloading the binary: Moved up to precede `ccoctl` steps, which require the use of `oc`
+include::modules/cli-installing-cli.adoc[leveloffset=+1]
 
-include::modules/installation-cloudformation-vpc-localzone.adoc[leveloffset=+2]
-include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
+== Preparing for the installation
 
-include::modules/installation-aws-add-local-zone-locations.adoc[leveloffset=+1]
+Before you extend nodes to local zones, you must prepare certain resources for the cluster installation environment.
 
-include::modules/installation-creating-aws-subnet-localzone.adoc[leveloffset=+1]
+// Obtaining the installation program
+include::modules/installation-obtaining-installer.adoc[leveloffset=+2]
 
-include::modules/installation-cloudformation-subnet-localzone.adoc[leveloffset=+2]
+// Generating a key pair for cluster node SSH access
+include::modules/ssh-agent-using.adoc[leveloffset=+2]
+
+// Creating the installation files for AWS
+include::modules/installation-user-infra-generate.adoc[leveloffset=+2]
+
+// Minimum resource requirements for cluster installation
+include::modules/installation-minimum-resource-requirements.adoc[leveloffset=+2]
+
+// Tested instance types for AWS
+include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
-* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console].
+* 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-obtaining-installer.adoc[leveloffset=+1]
+// Creating the installation configuration file
+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)
 
-//Installing the OpenShift CLI by downloading the binary: Moved up to precede `ccoctl` steps, which require the use of `oc`
-include::modules/cli-installing-cli.adoc[leveloffset=+1]
+// Edge compute pools and AWS Local Zones
+include::modules/edge-machine-pools-aws-local-zones.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]
+* xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about_nodes-scheduler-taints-tolerations[Understanding taints and tolerations]
+
+////
+// Revisit the need for the link to this section based on testing outcome of 4.15 Wavelenght Zone testing work that also assesses Manual STS, Manual long-term, and Mint routes.
 //Supertask: Configuring an AWS cluster to use short-term credentials
 [id="installing-aws-with-short-term-creds_{context}"]
 == Optional: Configuring an AWS cluster to use short-term credentials
@@ -120,36 +141,71 @@ include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+3]
 
 //Task part 2b: Creating the required AWS resources individually
 include::modules/cco-ccoctl-creating-individually.adoc[leveloffset=+3]
+////
 
-include::modules/ssh-agent-using.adoc[leveloffset=+1]
+// Opting in to AWS Local Zones
+include::modules/installation-aws-add-local-zone-locations.adoc[leveloffset=+1]
 
-include::modules/installation-user-infra-generate.adoc[leveloffset=+1]
-include::modules/installation-minimum-resource-requirements.adoc[leveloffset=+2]
+// Cluster installation options for an AWS Local Zone environment
+include::modules/aws-cluster-installation-options-aws-lzs.adoc[leveloffset=+1]
 
-[role="_additional-resources"]
-.Additional resources
+.Next steps
 
-* xref:../../scalability_and_performance/optimization/optimizing-storage.adoc#optimizing-storage[Optimizing storage]
+Choose one of the following options to install an {product-title} cluster in an AWS Local Zones environment:
 
-include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
+* xref:../../installing/installing_aws/installing-aws-localzone.adoc#installation-cluster-quickly-extend-workers_installing-aws-localzone[Installing a cluster quickly in AWS Local Zones]
+* xref:../../installing/installing_aws/installing-aws-localzone.adoc#creating-aws-local-zone-environment-existing_installing-aws-localzone[Installing a cluster in an existing VPC with defined Local Zone subnets]
+
+// Installing a cluster quickly in AWS Local Zones
+include::modules/installation-cluster-quickly-extend-workers.adoc[leveloffset=+1]
+
+// Modifying an installation configuration to use AWS Local Zones
+include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
-* 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.
+* xref:../../installing/installing_aws/installing-aws-localzone.adoc_installing-aws-localzone[Creating the installation configuration file]
 
-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]
+* xref:../../installing/installing_aws/installing-aws-localzone.adoc#cluster-limitations-local-zone_installing-aws-localzone[Cluster limitations in AWS Local Zones]
+
+.Next steps
+* xref:../../installing/installing_aws/installing-aws-localzone.adoc#installation-launching-installer_installing-aws-localzone[Deploying the cluster]
+
+[id="creating-aws-local-zone-environment-existing_{context}"]
+== Installing a cluster in an existing VPC that has Local Zone subnets
+
+You can install a cluster into an existing Amazon Virtual Private Cloud (VPC) on Amazon Web Services (AWS). The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, modify parameters in the `install-config.yaml` file before you install the cluster.
+
+Installing a cluster on AWS into an existing VPC requires extending workers to the edge of the Cloud Infrastructure by using AWS Local Zones.
+
+Local Zone subnets extend regular workers' nodes to edge networks. Each edge worker nodes runs a user workload. After you create an Amazon Web Service (AWS) Local Zone environment, and you deploy your cluster, you can use edge worker nodes to create user workloads in Local Zone subnets. 
+
+You can use a provided CloudFormation template to create the VPC and public subnets. Additionally, you can modify a template to customize your infrastructure or use the information that they contain to create AWS objects according to your company's policies.
+
+[NOTE]
+====
+If you want to create private subnets, you must either modify the provided CloudFormation template or create your own template.
+====
+
+// Creating a VPC in AWS
+include::modules/installation-creating-aws-vpc-localzone.adoc[leveloffset=+2]
+// Creating a subnet in AWS Local Zones
+include::modules/installation-creating-aws-subnet-localzone.adoc[leveloffset=+2]
+// CloudFormation template for the VPC
+include::modules/installation-cloudformation-vpc-localzone.adoc[leveloffset=+2]
+// AWS security groups
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
+// CloududFormation template for the subnet that uses AWS Local Zones
+include::modules/installation-cloudformation-subnet-localzone.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]
+* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console].
 
-include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2]
+// Modifying an installation configuration file to use AWS Local Zones subnets
+include::modules/install-creating-install-config-aws-local-zones-subnets.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
@@ -162,6 +218,8 @@ include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffse
 // Verify removal due to automation.
 // include::modules/installation-localzone-generate-k8s-manifest.adoc[leveloffset=+2]
 
+////
+// Revisit the need for the link to this section based on testing outcome of 4.15 Wavelenght Zone testing work that also assesses Manual STS, Manual long-term, and Mint routes.
 [id="installing-aws-manual-modes_{context}"]
 == Alternatives to storing administrator-level secrets in the kube-system project
 
@@ -176,23 +234,29 @@ include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+2]
 
 //Manually creating IAM
 include::modules/manually-create-identity-access-management.adoc[leveloffset=+2]
+////
 
+// Deploying the cluster
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 .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]
 
+// Logging in to the cluster by using the CLI
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
+// Logging in to the cluster by using the web console
 include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * 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.
 
+// Verifying nodes that were created with edge compute pool
 include::modules/machine-edge-pool-review-nodes.adoc[leveloffset=+1]
 
+// Telemetry access for OpenShift Container Platform
 include::modules/cluster-telemetry.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -207,4 +271,7 @@ include::modules/cluster-telemetry.adoc[leveloffset=+1]
 * 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].
+////
+// Revisit the need for the link to this section based on testing outcome of 4.15 Wavelenght Zone testing work that also assesses Manual STS, Manual long-term, and Mint routes.
 * If necessary, you can xref:../../post_installation_configuration/cluster-tasks.adoc#manually-removing-cloud-creds_post-install-cluster-tasks[remove cloud provider credentials].
+////
diff --git a/modules/aws-cluster-installation-options-aws-lzs.adoc b/modules/aws-cluster-installation-options-aws-lzs.adoc
@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-localzone.adoc
+
+:_content-type: CONCEPT
+[id="aws-cluster-installation-options-aws-lzs_{context}"]
+= Cluster installation options for an AWS Local Zones environment
+
+To install an {product-title} cluster in an AWS Local Zones environment on AWS infrastructure, choose one of the following installation options:
+
+* Installing a cluster to quickly extend workers to edge compute pools, where the installation program automatically creates resources for the {product-title} cluster. 
+
+* Installing a cluster on AWS into an existing VPC, where you must add Local Zone subnets to the `install-config.yaml` file.
diff --git a/modules/cluster-limitations-local-zone.adoc b/modules/cluster-limitations-local-zone.adoc
@@ -14,6 +14,15 @@ Some limitations exist when you attempt to deploy a cluster with a default insta
 The following list details limitations when deploying a cluster in AWS Local Zones:
 
 - The Maximum Transmission Unit (MTU) between an Amazon EC2 instance in a Local Zone and an Amazon EC2 instance in the Region is `1300`. This causes the cluster-wide network MTU to change according to the network plugin that is used on the deployment.
-- Network resources such as Network Load Balancer (NLB), Classic Load Balancer, and Network Address Translation (NAT) Gateways are not supported in AWS Local Zones.
+- Network resources such as Network Load Balancer (NLB), Classic Load Balancer, and Network Address Translation (NAT) Gateways are not globally supported in AWS Local Zones.
 - For an {product-title} cluster on AWS, the AWS Elastic Block Storage (EBS) `gp3` type volume is the default for node volumes and the default for the storage class. This volume type is not globally available on Local Zone locations. By default, the nodes running in Local Zones are deployed with the `gp2` EBS volume. The `gp2-csi` `StorageClass` must be set when creating workloads on Local Zone nodes.
 ====
+
+If you want the installation program to automatically create Local Zone subnets for your {product-title} cluster, specific configuration limitations apply with this method.
+
+[IMPORTANT]
+====
+The following configuration limitation applies when you set the installation program to automatically create subnets for your {product-title} cluster:
+
+- The private subnets for an AWS Local Zone associate with the route table of the parent zone, so that each private subnet can route egress traffic to the internet. If this route table does not exist during cluster installation, the private subnet associates with the first available private route table in the Virtual Private Cloud (VPC). This approach is valid only for AWS Local Zones subnets in an {product-title} cluster.
+====