OSDOCS-4347: AWS Local Zones installation

Author: GroceryBoyJr

_topic_maps/_topic_map.yml

@@ -174,6 +174,8 @@ 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
+    File: installing-aws-localzone
   - Name: Installing a cluster on AWS in a restricted network with user-provisioned infrastructure
     File: installing-restricted-networks-aws
   - Name: Uninstalling a cluster on AWS
@@ -677,7 +679,7 @@ Topics:
 - Name: Dynamic plug-ins
   Dir: dynamic-plug-in
   Distros: openshift-enterprise,openshift-origin
-  Topics: 
+  Topics:
   - Name: Overview of dynamic plug-ins
     File: dynamic-plug-in
   - Name: Getting started with dynamic plug-ins

installing/installing_aws/installing-aws-localzone.adoc

@@ -0,0 +1,117 @@
+:_content-type: ASSEMBLY
+[id="installing-aws-localzone"]
+= Installing a cluster using 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.
+
+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.
+
+[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.
+====
+
+== Prerequisites
+
+* 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.
++
+[IMPORTANT]
+====
+If you have an AWS profile stored on your computer, it must not use a temporary session token that you generated while using a multi-factor authentication device. The cluster continues to use your current AWS credentials to create AWS resources for the entire life of the cluster, so you must use key-based, long-lived credentials. To generate appropriate keys, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] in the AWS documentation. You can supply the keys when you run the installation program.
+====
+* You noted the region and supported link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/locations[AWS Local Zones locations] to create the network resources in.
+* You read the link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[Features] for each AWS Local Zones location.
+* You downloaded the AWS CLI and installed it on your computer. See link:https://docs.aws.amazon.com/cli/latest/userguide/install-bundle.html[Install the AWS CLI Using the Bundled Installer (Linux, macOS, or UNIX)] in the AWS documentation.
+* If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
++
+[NOTE]
+====
+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].
+
+include::modules/cluster-entitlements.adoc[leveloffset=+1]
+
+include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
+
+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-creating-aws-subnet-localzone.adoc[leveloffset=+1]
+
+include::modules/installation-cloudformation-subnet-localzone.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].
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
+include::modules/installation-user-infra-generate.adoc[leveloffset=+1]
+
+include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings] in the AWS documentation for more information about AWS profile and credential configuration.
+
+//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]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
+include::modules/cli-installing-cli.adoc[leveloffset=+1]
+
+include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
+
+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.
+
+include::modules/cluster-telemetry.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service.
+
+[role="_additional-resources"]
+[id="installing-localzone-additional-resources"]
+== Additional resources
+
+* See link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html[Working with stacks] in the AWS documentation for more information about AWS CloudFormation stacks.
+* link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#opt-in-local-zone[Opt into AWS Local Zones]
+* link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/locations[AWS Local Zones available locations]
+* link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features[AWS Local Zones features]
+
+[id="installing-aws-localzone-next-steps"]
+== Next steps
+
+* 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].
+* If necessary, you can xref:../../authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc#manually-removing-cloud-creds_cco-mode-mint[remove cloud provider credentials].

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

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-localzone.adoc
+
+:_content-type: PROCEDURE
+[id="installation-aws-add-local-zone-locations_{context}"]
+= Opting into AWS Local Zones
+
+If you plan to create the subnets in AWS Local Zones, you must opt in to each zone group separately.
+
+.Prerequisites
+
+* You have installed the AWS CLI.
+* You have determined into which region you will deploy your {product-title} cluster.
+
+.Procedure
+
+. Export a variable to contain the name of the region in which you plan to deploy your {product-title} cluster by running the following command:
++
+[source,terminal]
+----
+$ 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:
++
+[source,terminal]
+----
+$ aws ec2 describe-availability-zones \
+    --filters Name=region-name,Values=${CLUSTER_REGION} \
+    --query 'AvailabilityZones[].ZoneName' \
+    --all-availability-zones
+----
++
+Depending on the region, the list of available zones can be long. The different zones use the following naming conventions:
++
+`${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.
+
+. 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>
+----
+<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.
+
+. Opt in to the zone group on your AWS account by running the following command:
++
+[source,terminal]
+----
+$ aws ec2 modify-availability-zone-group \
+    --group-name "${ZONE_GROUP_NAME}" \
+    --opt-in-status opted-in
+----

modules/installation-aws-marketplace-subscribe.adoc

@@ -10,6 +10,9 @@ endif::[]
 ifeval::["{context}" == "installing-aws-government-region"]
 :ipi:
 endif::[]
+ifeval::["{context}" == "installing-aws-localzone"]
+:ipi:
+endif::[]
 ifeval::["{context}" == "installing-aws-user-infra"]
 :upi:
 endif::[]
@@ -66,6 +69,9 @@ endif::[]
 ifeval::["{context}" == "installing-aws-government-region"]
 :!ipi:
 endif::[]
+ifeval::["{context}" == "installing-aws-localzone"]
+:!ipi:
+endif::[]
 ifeval::["{context}" == "installing-aws-user-infra"]
 :!upi:
 endif::[]

modules/installation-aws-tested-machine-types.adoc

@@ -9,18 +9,42 @@
 // installing/installing_aws/installing-aws-vpc.adoc
 // installing/installing_aws/installing-restricted-networks-aws.adoc
 
+ifeval::["{context}" == "installing-aws-localzone"]
+:localzone:
+endif::[]
+
 [id="installation-aws-tested-machine-types_{context}"]
 = Tested instance types for AWS
 
-The following Amazon Web Services (AWS) instance types have been tested with {product-title}.
+The following Amazon Web Services (AWS) instance types have been tested with
+ifndef::localzone[]
+{product-title}.
+endif::localzone[]
+ifdef::localzone[]
+{product-title} for use with AWS Local Zones.
+endif::localzone[]
+
 
 [NOTE]
 ====
-Use the machine types included in the following charts for your AWS instances. If you use an instance type that is not listed in the chart, ensure that the instance size you use matches the minimum resource requirements that are listed in "Minimum resource requirements for cluster installation". 
+Use the machine types included in the following charts for your AWS instances. If you use an instance type that is not listed in the chart, ensure that the instance size you use matches the minimum resource requirements that are listed in "Minimum resource requirements for cluster installation".
 ====
 
+ifndef::localzone[]
 .Machine types based on x86_64 architecture
 [%collapsible]
 ====
 include::https://raw.githubusercontent.com/openshift/installer/master/docs/user/aws/tested_instance_types_x86_64.md[]
 ====
+endif::localzone[]
+ifdef::localzone[]
+.Machine types based on x86_64 architecture for AWS Local Zones
+[%collapsible]
+====
+* `m5.xlarge`
+====
+endif::localzone[]
+
+ifeval::["{context}" == "installing-aws-localzone"]
+:!localzone:
+endif::[]

modules/installation-cloudformation-subnet-localzone.adoc

@@ -0,0 +1,74 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-localzone.adoc
+
+:_content-type: REFERENCE
+[id="installation-cloudformation-subnet-localzone_{context}"]
+= CloudFormation template for the subnet that uses AWS Local Zones
+
+You can use the following CloudFormation template to deploy the subnet that
+you need for your {product-title} cluster that uses AWS Local Zones.
+
+.CloudFormation template for the subnet
+[%collapsible]
+====
+[source,yaml]
+----
+# CloudFormation template used to create Local Zone subnets and dependencies
+AWSTemplateFormatVersion: 2010-09-09
+Description: Template for Best Practice VPC with 1-3 AZs
+
+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)
+    Type: String
+  LocalZoneNameShort:
+    Description: Short name for Local Zone used on tag Name (Example bos1)
+    Type: String
+  PublicRouteTableId:
+    Description: Public Route Table ID to associate the Local Zone subnet
+    Type: String
+  PublicSubnetCidr:
+    AllowedPattern: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(1[6-9]|2[0-4]))$
+    ConstraintDescription: CIDR block parameter must be in the form x.x.x.x/16-24.
+    Default: 10.0.128.0/20
+    Description: CIDR block for Public Subnet
+    Type: String
+
+Resources:
+  PublicSubnet:
+    Type: "AWS::EC2::Subnet"
+    Properties:
+      VpcId: !Ref VpcId
+      CidrBlock: !Ref PublicSubnetCidr
+      AvailabilityZone: !Ref LocalZoneName
+      Tags:
+      - Key: Name
+        Value: !Join
+          - ""
+          - [ !Ref ClusterName, "-public-", !Ref LocalZoneNameShort, "-1" ]
+      - Key: kubernetes.io/cluster/unmanaged
+        Value: "true"
+
+  PublicSubnetRouteTableAssociation:
+    Type: "AWS::EC2::SubnetRouteTableAssociation"
+    Properties:
+      SubnetId: !Ref PublicSubnet
+      RouteTableId: !Ref PublicRouteTableId
+
+Outputs:
+  PublicSubnetIds:
+    Description: Subnet IDs of the public subnets.
+    Value:
+      !Join [
+        "",
+        [!Ref PublicSubnet]
+      ]
+----
+====