:_mod-docs-content-type: ASSEMBLY
[id="installing-aws-localzone"]
= Installing a cluster with compute nodes on AWS Local Zones
include::_attributes/common-attributes.adoc[]
:context: installing-aws-localzone
:zone-type: Local Zones

toc::[]

You can quickly install an {product-title} cluster on Amazon Web Services (AWS) {zone-type} by setting the zone names in the edge compute pool of the `install-config.yaml` file, or install a cluster in an existing Amazon Virtual Private Cloud (VPC) with Local Zone subnets.

AWS {zone-type} is an 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].

// Infrastructure prerequisites
[id="aws-zones-prerequisites_{context}"]
== Infrastructure prerequisites

* You reviewed details about xref:../../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
* You are familiar with xref:../../../installing/overview/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.
+
[WARNING]
====
If you have an AWS profile stored on your computer, it must not use a temporary session token that you generated while using a multifactor 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-term 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 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-module_configuring-firewall[configured it to allow the sites] that your cluster must access.
* 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/[AWS Local Zones features] in the AWS documentation.
* You added permissions for creating network resources that support AWS Local Zones to the Identity and Access Management (IAM) user or role. The following example enables a zone group that can give a user or role access for creating network resources that support AWS {zone-type}.
+
.Example of an additional IAM policy with the `ec2:ModifyAvailabilityZoneGroup` permission attached to an IAM user or role.
+
[source,yaml]
----
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ec2:ModifyAvailabilityZoneGroup"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
----

[id="installation-about-local-zone-edge-compute-pool_{context}"]
== About AWS Local Zones and edge compute pool

Read the following sections to understand infrastructure behaviors and cluster limitations in an AWS {zone-type} environment.

// Cluster limitations
include::modules/cluster-limitations-aws-zone.adoc[leveloffset=+2]

// About edge compute pools
include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* xref:../../../networking/advanced_networking/changing-cluster-network-mtu.adoc#mtu-value-selection_changing-cluster-network-mtu[MTU value selection]
* xref:../../../networking/advanced_networking/changing-cluster-network-mtu.adoc#nw-ovn-ipsec-enable_configuring-ipsec-ovn[Changing the MTU for the cluster network]
* xref:../../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about_nodes-scheduler-taints-tolerations[Understanding taints and tolerations]
* xref:../../../storage/understanding-persistent-storage.adoc#pvc-storage-class_understanding-persistent-storage[Storage classes]
* xref:../../../networking/ingress_load_balancing/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding_configuring-ingress-cluster-traffic-ingress-controller[Ingress Controller sharding]
* link:https://docs.aws.amazon.com/local-zones/latest/ug/how-local-zones-work.html[How Local Zones work ({aws-short} documentation)]

[id="installation-prereqs-aws-local-zone_{context}"]
== Installation prerequisites

Before you install a cluster in an AWS {zone-type} environment, you must configure your infrastructure so that it can adopt Local Zone capabilities.

// Opting in to AWS Local Zones
include::modules/installation-aws-add-zone-locations.adoc[leveloffset=+2]

// Obtaining an AWS Marketplace image
include::modules/installation-aws-marketplace-subscribe.adoc[leveloffset=+2]

[id="prep-installation-aws-local-zone_{context}"]
== Preparing for the installation

Before you extend nodes to {zone-type}, you must prepare certain resources for the cluster installation environment.

// 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

* link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features ({aws-short} documentation)]

// Creating the installation configuration file
include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]

// Examples of installation configuration files with edge compute pools
include::modules/installation-aws-edge-compute-pools-examples.adoc[leveloffset=+2]

// Customizing Cluster Network MTU
include::modules/installation-aws-cluster-network-mtu.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* link:https://docs.aws.amazon.com/local-zones/latest/ug/how-local-zones-work.html#considerations[AWS resources supported in Local Zones ({aws-short} documentation)]

// Cluster installation options for an AWS Local Zone environment
include::modules/aws-cluster-installation-options-aws-lzs.adoc[leveloffset=+1]

.Next steps

Choose one of the following options to install an {product-title} cluster in an AWS {zone-type} environment:

* xref:../../../installing/installing_aws/ipi/installing-aws-localzone.adoc#installation-cluster-quickly-extend-compute-nodes_installing-aws-localzone[Installing a cluster quickly in AWS Local Zones]
* xref:../../../installing/installing_aws/ipi/installing-aws-localzone.adoc#creating-aws-local-zone-environment-existing_installing-aws-localzone[Installing a cluster in an existing VPC with defined AWS Local Zone subnets]

// Installing a cluster quickly in AWS Local Zones
include::modules/installation-cluster-quickly-extend-compute-nodes.adoc[leveloffset=+1]

// Modifying an installation configuration to use AWS Local Zones
include::modules/install-creating-install-config-aws-edge-zones.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* xref:../../../installing/installing_aws/ipi/installing-aws-localzone.adoc#installation-generate-aws-user-infra-install-config_installing-aws-localzone[Creating the installation configuration file]

* xref:../../../installing/installing_aws/ipi/installing-aws-localzone.adoc#cluster-limitations-aws-zone_installing-aws-localzone[Cluster limitations in AWS Local Zones]

.Next steps
* xref:../../../installing/installing_aws/ipi/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, change parameters in the `install-config.yaml` file before you install the cluster.

Installing a cluster on AWS into an existing VPC requires extending compute nodes to the edge of the Cloud Infrastructure by using AWS {zone-type}.

Local Zone subnets extend regular compute nodes to edge networks. Each edge compute 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 compute nodes to create user workloads in Local Zone subnets.

[NOTE]
====
If you want to create private subnets, you must either change the provided CloudFormation template or create your own template.
====

You can use a provided CloudFormation template to create network resources. Additionally, you can change a template to customize your infrastructure or use the information that they contain to create AWS resources according to your company's policies.

[IMPORTANT]
====
The documentation provides the steps for performing an installer-provisioned infrastructure installation 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.
====

// Creating a VPC in AWS
include::modules/installation-creating-aws-vpc-localzone.adoc[leveloffset=+2]

// CloudFormation template for the VPC
include::modules/installation-cloudformation-vpc-localzone.adoc[leveloffset=+2]

// Creating subnets in Local Zones
include::modules/installation-creating-aws-vpc-subnets-lz.adoc[leveloffset=+2]

// CloudFormation template for the subnet that uses AWS Local Zones
include::modules/installation-cloudformation-subnet-localzone.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* link:https://console.aws.amazon.com/cloudformation/[{aws-short} CloudFormation console ({aws-short} documentation)]

// Modifying an installation configuration file to use AWS Wavelength Zones subnets
include::modules/installing-aws-edge-zones-custom-vpc-config.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* link:https://console.aws.amazon.com/cloudformation[{aws-short} CloudFormation console]
* link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings in the {aws-short} CLI ({aws-short} documentation)]

.Next steps
* xref:../../../installing/installing_aws/ipi/installing-aws-localzone.adoc#installation-launching-installer_installing-aws-localzone[Deploying the cluster]

// Optional: AWS security groups
include::modules/installation-aws-security-groups.adoc[leveloffset=+1]

// Optional: Assign public IP to edge compute nodes (optional)
include::modules/installing-with-edge-node-public.adoc[leveloffset=+1]

// Deploying the cluster
include::modules/installation-launching-installer.adoc[leveloffset=+1]

[id="verify-aws-local-zone-deployed-cluster-status_{context}"]
== Verifying the status of the deployed cluster

Verify that your {product-title} successfully deployed on AWS {zone-type}.

// Logging in to the cluster by using the CLI
include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+2]

// Logging in to the cluster by using the web console
include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources

* xref:../../../web_console/web-console.adoc#web-console[Accessing the web console]

// Verifying nodes that were created with edge compute pool
include::modules/machine-edge-pool-review-nodes.adoc[leveloffset=+2]

.Next steps

* xref:../../../installing/validation_and_troubleshooting/validating-an-installation.adoc#validating-an-installation[Validating an installation].
* If necessary, you can xref:../../../support/remote_health_monitoring/remote-health-reporting.adoc#remote-health-reporting[Remote health reporting].
