From 2bfe0b3672f7a392bd6cd11f70b11158266a9a31 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 16 Mar 2023 15:45:06 -0400 Subject: [PATCH 01/42] Dump converted content --- _topic_maps/_topic_map.yml | 2 + .../installing-aws-vpc-local-zones.adoc | 198 ++++++++++++++++++ .../edge-machine-pools-aws-local-zones.adoc | 10 + ...stall-creating-aws-local-zones-subnet.adoc | 77 +++++++ ...ll-creating-aws-local-zones-vpc-stack.adoc | 79 +++++++ ...eating-install-config-aws-local-zones.adoc | 35 ++++ modules/machines-edge-machine-pool.adoc | 103 +++++++++ ...aws-local-zones-user-workload-ingress.adoc | 9 + 8 files changed, 513 insertions(+) create mode 100644 installing/installing_aws/installing-aws-vpc-local-zones.adoc create mode 100644 modules/edge-machine-pools-aws-local-zones.adoc create mode 100644 modules/install-creating-aws-local-zones-subnet.adoc create mode 100644 modules/install-creating-aws-local-zones-vpc-stack.adoc create mode 100644 modules/install-creating-install-config-aws-local-zones.adoc create mode 100644 modules/machines-edge-machine-pool.adoc create mode 100644 modules/nw-aws-local-zones-user-workload-ingress.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index c885f3a67c38..86914d21ba04 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -166,6 +166,8 @@ Topics: File: installing-restricted-networks-aws-installer-provisioned - Name: Installing a cluster on AWS into an existing VPC File: installing-aws-vpc + - Name: Installing a cluster on AWS using AWS Local Zones + File: installing-aws-vpc-local-zones - Name: Installing a private cluster on AWS File: installing-aws-private - Name: Installing a cluster on AWS into a government region diff --git a/installing/installing_aws/installing-aws-vpc-local-zones.adoc b/installing/installing_aws/installing-aws-vpc-local-zones.adoc new file mode 100644 index 000000000000..b34a03b0e888 --- /dev/null +++ b/installing/installing_aws/installing-aws-vpc-local-zones.adoc @@ -0,0 +1,198 @@ +:_content-type: ASSEMBLY +[id="installing-aws-vpc-local-zones"] += Installing a cluster on AWS using AWS Local Zones +include::_attributes/common-attributes.adoc[] +:context: installing-aws-vpc-local-zones + +toc::[] + +In {product-title} version {product-version}, you can install a cluster into an existing Amazon Virtual Private Cloud (VPC) on Amazon Web Services (AWS) that uses AWS Local Zones. + +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. + +== 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 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 downloaded the AWS CLI and installed it on your computer. +* 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. +* 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]. +* To use the AWS Local Zone deployment that is described in this document: +** 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": [ + { + "Sid": "Stmt1677614927608", + "Action": [ + "ec2:ModifyAvailabilityZoneGroup" + ], + "Effect": "Allow", + "Resource": "*" + } + ] +} +---- + +** Export the following environment variables: ++ +[source,terminal] +---- +export CLUSTER_NAME="ipi-localzones" + +# AWS Region and extra Local Zone group Information +export AWS_REGION="us-west-2" +export ZONE_GROUP_NAME="us-west-2-lax-1" +export ZONE_NAME="us-west-2-lax-1a" + +# VPC Information +export VPC_CIDR="10.0.0.0/16" +export VPC_SUBNETS_BITS="10" +export VPC_SUBNETS_COUNT="3" + +# Local Zone Subnet information +export SUBNET_CIDR="10.0.192.0/22" +export SUBNET_NAME="${CLUSTER_NAME}-public-usw2-lax-1a" +---- + +include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+1] + + +// TODO: This could just be a nixed w/the children bumped up a level. +:_content-type: PROCEDURE +[id="install-aws-local-zones-vpc-stack"] +== Creating the network stack + +Create a network stack that involves a virtual private cloud (VPC) and an AWS Local Zones subnet. While you can create the VPC by using the instructions in xref:../../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[Installing a cluster on AWS into an existing VPC], the following instructions use xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[CloudFormation templates] that rely on the environment variables you already set. + +include::modules/install-creating-aws-local-zones-vpc-stack.adoc[leveloffset=+2] +include::modules/install-creating-aws-local-zones-subnet.adoc[leveloffset=+2] + +[id="installing-cluster-aws-local-zones"] +== Install the cluster + +To install an OpenShift cluster in an existing VPC with subnets in Local Zones, follow these steps: + +* Generate the `install-config.yaml` file or provide your own. +* Set the option `platform.aws.subnets` to add the subnet IDs. +* Optional: Customize the edge compute pool. + +include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2] +include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] + +include::modules/installation-launching-installer.adoc[leveloffset=+1] + +include::modules/nw-aws-local-zones-user-workload-ingress.adoc[leveloffset=+1] + +// TODO: I would prefer not to have teardown instructions for this guide if we can help it. Would the user likely be able to figure this out on their own or with AWS' docs? + +// :_content-type: PROCEDURE +// == Removing the cluster + +// :_content-type: PROCEDURE +// === Destroying the cluster + +// [source,terminal] +// ---- +// ./openshift-install destroy cluster --dir ${CLUSTER_NAME} +// ---- + +// :_content-type: PROCEDURE +// === Destroying the Local Zone subnets + +// [source,terminal] +// ---- +// aws cloudformation delete-stack \ +// --region ${AWS_REGION} \ +// --stack-name ${SUBNET_NAME} +// ---- + +// :_content-type: PROCEDURE +// === Destroying the VPC + +// [source,terminal] +// ---- +// aws cloudformation delete-stack \ +// --region ${AWS_REGION} \ +// --stack-name ${CLUSTER_NAME}-vpc +// ---- + +// TODO: Shouldn't this be a blog post if anything? + +// :content-type: REFERENCE +// == Use Cases + +// :content-type: REFERENCE +// == A sample application deployment with edge machine pools and AWS Local Zones + +// The example below creates one sample application on the node running in the Local zone, setting the tolerations needed to pin the pod on the correct node: + +// [source,terminal] +// ---- +// cat << EOF | oc create -f - +// apiVersion: v1 +// kind: Namespace +// metadata: +// name: local-zone-demo +// --- +// apiVersion: apps/v1 +// kind: Deployment +// metadata: +// name: local-zone-demo-app-nyc-1 +// namespace: local-zone-demo +// spec: +// selector: +// matchLabels: +// app: local-zone-demo-app-nyc-1 +// replicas: 1 +// template: +// metadata: +// labels: +// app: local-zone-demo-app-nyc-1 +// machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} +// spec: +// nodeSelector: +// machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} +// tolerations: +// - key: "node-role.kubernetes.io/edge" +// operator: "Equal" +// value: "" +// effect: "NoSchedule" +// containers: +// - image: openshift/origin-node +// command: +// - "/bin/socat" +// args: +// - TCP4-LISTEN:8080,reuseaddr,fork +// - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' +// imagePullPolicy: Always +// name: echoserver +// ports: +// - containerPort: 8080 +// --- +// apiVersion: v1 +// kind: Service +// metadata: +// name: local-zone-demo-app-nyc-1 +// namespace: local-zone-demo +// spec: +// ports: +// - port: 80 +// targetPort: 8080 +// protocol: TCP +// type: NodePort +// selector: +// app: local-zone-demo-app-nyc-1 +// EOF +// ---- + diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc new file mode 100644 index 000000000000..c8bc8441eca9 --- /dev/null +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -0,0 +1,10 @@ +:_content-type: CONCEPT +[id="edge-machine-pools-aws-local-zones_{context}"] +== Edge machine pools and AWS Local Zones + +An edge machine pool generates workers that run in AWS Local Zones locations. These workers differ from the those of the default compute pool in the following ways: + +* AWS Local Zones resources are more expensive than those of normal availability zones. +* Latency between applications and end users are 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. +* Network load balancers do not support Local Zones subnets. +* The time for end users who are close to a metropolitan region to connect to applications that run in Local Zones can be as much as ten times faster than if those applications run in a parent region. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-subnet.adoc b/modules/install-creating-aws-local-zones-subnet.adoc new file mode 100644 index 000000000000..15b3f0d26ec1 --- /dev/null +++ b/modules/install-creating-aws-local-zones-subnet.adoc @@ -0,0 +1,77 @@ +:_content-type: PROCEDURE +[id="install-creating-aws-local-zones-subnet"] +=== Creating an AWS Local Zone subnet + +To create a Local Zone subnet, choose a zone group to enable and opt it in. Then, create the subnet. + +.Procedure + +. To opt the zone group in, from a command line, enter the following command: ++ +[source,terminal] +---- +$ aws ec2 modify-availability-zone-group \ + --region ${AWS_REGION} \ + --group-name ${ZONE_GROUP_NAME} \ + --opt-in-status opted-in +---- + +// TODO: GitHub +// TODO: Review yaml--is this only us-west-2-lax-la? +. Create the stack for the Local Zone subnet `us-west-2-lax-1a`. For example: ++ +[source,terminal] +---- +INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" +TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01.99_net_local-zone.yaml" + +aws cloudformation create-stack \ + --region ${AWS_REGION} \ + --stack-name ${SUBNET_NAME} \ + --template-body ${TPL_URL} \ + --parameters \ + ParameterKey=VpcId,ParameterValue=${VPC_ID} \ + ParameterKey=ZoneName,ParameterValue=${ZONE_NAME} \ + ParameterKey=SubnetName,ParameterValue=${SUBNET_NAME} \ + ParameterKey=PublicSubnetCidr,ParameterValue=${SUBNET_CIDR} \ + ParameterKey=PublicRouteTableId,ParameterValue=${PUBLIC_RTB_ID} +---- + +. Enter the following command to wait for the stack creation to finish: ++ +[source,terminal] +---- +aws cloudformation wait stack-create-complete \ + --region ${AWS_REGION} \ + --stack-name ${SUBNET_NAME} +---- +// TODO: jq +- Export the Local Zone subnet ID and append it to the subnet list. For example: ++ +[source,terminal] +---- +export SUBNET_ID=$(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${SUBNET_NAME} \ + | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicSubnetIds").OutputValue' ) + +# Append the Local Zone Subnet ID to the Subnet List +SUBNETS+=(${SUBNET_ID}) +---- + +.Verification + +* Use `echo` to verify the number of subnets that you have. For example: ++ +[source,terminal] +---- +$ echo ${#SUBNETS[*]} +---- ++ +.Example output +[source,terminal] +---- +7 +---- ++ +If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-vpc-stack.adoc b/modules/install-creating-aws-local-zones-vpc-stack.adoc new file mode 100644 index 000000000000..98e2935747ba --- /dev/null +++ b/modules/install-creating-aws-local-zones-vpc-stack.adoc @@ -0,0 +1,79 @@ +:_content-type: PROCEDURE +[id="install-aws-local-zones-vpc-stack_{context}"] +=== Creating a VPC for AWS Local Zones + +Create a virtual private cloud (VPC) to use with AWS Local Zones. + +.Procedure +// TODO: GitHub links are not okay. +. From a command line, enter the following command to create the stack: ++ +[source,terminal] +---- +INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" +TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01_vpc.yaml" + +aws cloudformation create-stack \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --template-body ${TPL_URL} \ + --parameters \ + ParameterKey=VpcCidr,ParameterValue=${VPC_CIDR} \ + ParameterKey=SubnetBits,ParameterValue=${VPC_SUBNETS_BITS} \ + ParameterKey=AvailabilityZoneCount,ParameterValue=${VPC_SUBNETS_COUNT} +---- + +. Enter the following command to wait for the stack creation to finish: ++ +[source,terminal] +---- +aws cloudformation wait stack-create-complete \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc +---- +// TODO: jq is not okay. +. Enter the following command to export the VPC ID: ++ +[source,terminal] +---- +export VPC_ID=$(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="VpcId").OutputValue' ) +---- +// TODO: jq +. Extract the subnets IDs to the environment variable list `SUBNETS`. For example: ++ +[source,terminal] +---- +mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[0].OutputValue' | tr ',' '\n') +mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[1].OutputValue' | tr ',' '\n') +---- + +// TODO: jq +. Export the public route table ID. For example: ++ +[source,terminal] +---- +export PUBLIC_RTB_ID=$(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicRouteTableId").OutputValue' ) +---- + +.Verification + +* To review the variables that you exported, enter the following command: ++ +[source,terminal] +---- +echo "SUBNETS=${SUBNETS[*]} +VPC_ID=${VPC_ID} +PUBLIC_RTB_ID=${PUBLIC_RTB_ID}" +---- \ No newline at end of file diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc new file mode 100644 index 000000000000..ae05296f064b --- /dev/null +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -0,0 +1,35 @@ +:_content-type: PROCEDURE +[id="install-creating-install-config-aws-local-zones_{context}"] +=== Create an installation configuration file that uses AWS Local Zones subnets + +Create an `install-config.yaml` file that uses AWS Local Zones subnets. + +.Prerequisites + +* You created subnets by using the procedure "Creating an AWS Local Zone subnet". + +.Procedure + +. From a command line, enter the following command to create the `install-config.yaml` file: ++ +[source,terminal] +---- +$ ./openshift-install create install-config --dir ${CLUSTER_NAME} +---- ++ +Follow the prompts that result from running the command. + +. Append the subnets to the value of the `platform.aws.subnets` property. As an example: ++ +[source,terminal] +---- +$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done + subnets: + - subnet-0fc845d8e30fdb431 + - subnet-0a2675b7cbac2e537 + - subnet-01c0ac400e1920b47 + - subnet-0fee60966b7a93da6 + - subnet-002b48c0a91c8c641 + - subnet-093f00deb44ce81f4 + - subnet-0f85ae65796e8d107 +---- \ No newline at end of file diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc new file mode 100644 index 000000000000..0b4418bf0af0 --- /dev/null +++ b/modules/machines-edge-machine-pool.adoc @@ -0,0 +1,103 @@ + +:_content-type: CONCEPT +[id="machines-edge-machine-pool_{context}"] +=== The edge machine pool + +{product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the image type and size limitations on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. + +The default elastic block store (EBS) for Local Zone locations is `gp2`, which differs from the default worker pool. The preferred list of instance types for the edge compute pool follows the same order of worker pools. Depending on the availability of the location, the system chooses one of those instances. The preferred list of instance types for the edge compute pool includes: + +* `m6i.xlarge` +* `m5.xlarge` +* `c5d.2xlarge` + +The edge compute pool creates new labels that developers can use to deploy their applications onto those locations. The new labels are: + +* `node-role.kubernetes.io/edge=''` +* `zone_type=local-zone` +* `zone_group=` + + +By default, the system creates the edge compute pool only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. + +The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec. This practice is demonstrated in the following examples: + +.Example edge pool +[source,yaml] +---- +apiVersion: v1 +baseDomain: devcluster.openshift.com +metadata: + name: ipi-localzone +platform: + aws: + region: us-west-2 + subnets: + - subnet-0fc845d8e30fdb431 + - subnet-0a2675b7cbac2e537 + - subnet-01c0ac400e1920b47 + - subnet-0fee60966b7a93da6 + - subnet-002b48c0a91c8c641 + - subnet-093f00deb44ce81f4 + - subnet-0f85ae65796e8d107 +pullSecret: '{"auths": ...}' +sshKey: ssh-ed25519 AAAA... +---- + +.Example edge pool with a custom instance type +[source,yaml] +---- +apiVersion: v1 +baseDomain: devcluster.openshift.com +metadata: + name: ipi-localzone +compute: +- name: edge + platform: + aws: + type: m5.4xlarge +platform: + aws: + region: us-west-2 + subnets: + - subnet-0fc845d8e30fdb431 + - subnet-0a2675b7cbac2e537 + - subnet-01c0ac400e1920b47 + - subnet-0fee60966b7a93da6 + - subnet-002b48c0a91c8c641 + - subnet-093f00deb44ce81f4 + - subnet-0f85ae65796e8d107 +pullSecret: '{"auths": ...}' +sshKey: ssh-ed25519 AAAA... +---- + +.Example edge pool with a custom EBS type +[source,yaml] +---- +apiVersion: v1 +baseDomain: devcluster.openshift.com +metadata: + name: ipi-localzone +compute: +- name: edge + platform: + aws: + rootVolume: + type: gp3 + size: 120 +platform: + aws: + region: us-west-2 + subnets: + - subnet-0fc845d8e30fdb431 + - subnet-0a2675b7cbac2e537 + - subnet-01c0ac400e1920b47 + - subnet-0fee60966b7a93da6 + - subnet-002b48c0a91c8c641 + - subnet-093f00deb44ce81f4 + - subnet-0f85ae65796e8d107 +pullSecret: '{"auths": ...}' +sshKey: ssh-ed25519 AAAA... +---- + +NOTE: Instance and EBS types can vary by location. \ No newline at end of file diff --git a/modules/nw-aws-local-zones-user-workload-ingress.adoc b/modules/nw-aws-local-zones-user-workload-ingress.adoc new file mode 100644 index 000000000000..1564048f9022 --- /dev/null +++ b/modules/nw-aws-local-zones-user-workload-ingress.adoc @@ -0,0 +1,9 @@ +:content-type: CONCEPT +[id="nw-aws-local-zones-user-workload-ingress_{context}"] +=== User-workload ingress traffic on AWS Local Zones + +Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The ALB Operator is available through the Operator Lifecycle Manager (OLM). + +To optimize application deployment on AWS Local Zone locations, provision at least one new ALB Ingress per location to expose services that are deployed on the zones. + +If the cluster administrator shares ALB Ingress subnets across different locations, end-user latency can increase when traffic routes to back ends are located in different zones than from where the traffic originated. \ No newline at end of file From c5e667aed44fdcef742cd18515066453597f49ec Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:13:51 -0400 Subject: [PATCH 02/42] Beginning re-org of existing content --- installing/installing_aws/installing-aws-localzone.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 608c9373dd12..0b41277a6846 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -82,6 +82,9 @@ 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] +include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] +include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+2] +include::modules/installation-aws-local-zones-ref-deployment.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources @@ -91,7 +94,8 @@ 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 From 169537d5bb070c44176e0c1cf8bd603d0b7b7ec0 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:37:56 -0400 Subject: [PATCH 03/42] Update CloudFormation VPC template --- ...allation-cloudformation-vpc-localzone.adoc | 75 +------------------ 1 file changed, 4 insertions(+), 71 deletions(-) diff --git a/modules/installation-cloudformation-vpc-localzone.adoc b/modules/installation-cloudformation-vpc-localzone.adoc index b0c3b8d8ef58..fa0af34ed2a4 100644 --- a/modules/installation-cloudformation-vpc-localzone.adoc +++ b/modules/installation-cloudformation-vpc-localzone.adoc @@ -18,9 +18,6 @@ AWSTemplateFormatVersion: 2010-09-09 Description: Template for Best Practice VPC with 1-3 AZs Parameters: - ClusterName: - Type: String - Description: ClusterName used to prefix resource names VpcCidr: 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. @@ -55,8 +52,6 @@ Metadata: Parameters: - AvailabilityZoneCount ParameterLabels: - ClusterName: - default: "" AvailabilityZoneCount: default: "Availability Zone Count" VpcCidr: @@ -75,12 +70,6 @@ Resources: EnableDnsSupport: "true" EnableDnsHostnames: "true" CidrBlock: !Ref VpcCidr - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-vpc" ] ] - - Key: !Join [ "", [ "kubernetes.io/cluster/unmanaged" ] ] - Value: "shared" - PublicSubnet: Type: "AWS::EC2::Subnet" Properties: @@ -89,9 +78,6 @@ Resources: AvailabilityZone: !Select - 0 - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-public-1" ] ] PublicSubnet2: Type: "AWS::EC2::Subnet" Condition: DoAz2 @@ -101,9 +87,6 @@ Resources: AvailabilityZone: !Select - 1 - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-public-2" ] ] PublicSubnet3: Type: "AWS::EC2::Subnet" Condition: DoAz3 @@ -111,31 +94,19 @@ Resources: VpcId: !Ref VPC CidrBlock: !Select [2, !Cidr [!Ref VpcCidr, 6, !Ref SubnetBits]] AvailabilityZone: !Select - - 2 - - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-public-3" ] ] - + - 2 + - Fn::GetAZs: !Ref "AWS::Region" InternetGateway: Type: "AWS::EC2::InternetGateway" - Properties: - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-igw" ] ] GatewayToInternet: Type: "AWS::EC2::VPCGatewayAttachment" Properties: VpcId: !Ref VPC InternetGatewayId: !Ref InternetGateway - PublicRouteTable: Type: "AWS::EC2::RouteTable" Properties: VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-rtb-public" ] ] PublicRoute: Type: "AWS::EC2::Route" DependsOn: GatewayToInternet @@ -150,15 +121,16 @@ Resources: RouteTableId: !Ref PublicRouteTable PublicSubnetRouteTableAssociation2: Type: "AWS::EC2::SubnetRouteTableAssociation" + Condition: DoAz2 Properties: SubnetId: !Ref PublicSubnet2 RouteTableId: !Ref PublicRouteTable PublicSubnetRouteTableAssociation3: + Condition: DoAz3 Type: "AWS::EC2::SubnetRouteTableAssociation" Properties: SubnetId: !Ref PublicSubnet3 RouteTableId: !Ref PublicRouteTable - PrivateSubnet: Type: "AWS::EC2::Subnet" Properties: @@ -167,16 +139,10 @@ Resources: AvailabilityZone: !Select - 0 - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-private-1" ] ] PrivateRouteTable: Type: "AWS::EC2::RouteTable" Properties: VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-rtb-private-1" ] ] PrivateSubnetRouteTableAssociation: Type: "AWS::EC2::SubnetRouteTableAssociation" Properties: @@ -192,9 +158,6 @@ Resources: - EIP - AllocationId SubnetId: !Ref PublicSubnet - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-natgw-private-1" ] ] EIP: Type: "AWS::EC2::EIP" Properties: @@ -207,7 +170,6 @@ Resources: DestinationCidrBlock: 0.0.0.0/0 NatGatewayId: Ref: NAT - PrivateSubnet2: Type: "AWS::EC2::Subnet" Condition: DoAz2 @@ -217,17 +179,11 @@ Resources: AvailabilityZone: !Select - 1 - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-private-2" ] ] PrivateRouteTable2: Type: "AWS::EC2::RouteTable" Condition: DoAz2 Properties: VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-rtb-private-2" ] ] PrivateSubnetRouteTableAssociation2: Type: "AWS::EC2::SubnetRouteTableAssociation" Condition: DoAz2 @@ -245,17 +201,11 @@ Resources: - EIP2 - AllocationId SubnetId: !Ref PublicSubnet2 - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-natgw-private-2" ] ] EIP2: Type: "AWS::EC2::EIP" Condition: DoAz2 Properties: Domain: vpc - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-eip-private-2" ] ] Route2: Type: "AWS::EC2::Route" Condition: DoAz2 @@ -265,7 +215,6 @@ Resources: DestinationCidrBlock: 0.0.0.0/0 NatGatewayId: Ref: NAT2 - PrivateSubnet3: Type: "AWS::EC2::Subnet" Condition: DoAz3 @@ -275,17 +224,11 @@ Resources: AvailabilityZone: !Select - 2 - Fn::GetAZs: !Ref "AWS::Region" - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-private-3" ] ] PrivateRouteTable3: Type: "AWS::EC2::RouteTable" Condition: DoAz3 Properties: VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-rtb-private-3" ] ] PrivateSubnetRouteTableAssociation3: Type: "AWS::EC2::SubnetRouteTableAssociation" Condition: DoAz3 @@ -303,17 +246,11 @@ Resources: - EIP3 - AllocationId SubnetId: !Ref PublicSubnet3 - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-natgw-private-3" ] ] EIP3: Type: "AWS::EC2::EIP" Condition: DoAz3 Properties: Domain: vpc - Tags: - - Key: Name - Value: !Join [ "", [ !Ref ClusterName, "-eip-private-3" ] ] Route3: Type: "AWS::EC2::Route" Condition: DoAz3 @@ -323,7 +260,6 @@ Resources: DestinationCidrBlock: 0.0.0.0/0 NatGatewayId: Ref: NAT3 - S3Endpoint: Type: AWS::EC2::VPCEndpoint Properties: @@ -369,8 +305,5 @@ Outputs: PublicRouteTableId: Description: Public Route table ID Value: !Ref PublicRouteTable - PrivateRouteTableId: - Description: Private Route table ID - Value: !Ref PrivateRouteTable ---- ==== From 44dc5a76937cfcc01458a966fbf60de84d92ead5 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:39:53 -0400 Subject: [PATCH 04/42] Update subnet template --- ...ation-cloudformation-subnet-localzone.adoc | 25 +++++++------------ 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/modules/installation-cloudformation-subnet-localzone.adoc b/modules/installation-cloudformation-subnet-localzone.adoc index f37134bc2257..a17c8db68b7d 100644 --- a/modules/installation-cloudformation-subnet-localzone.adoc +++ b/modules/installation-cloudformation-subnet-localzone.adoc @@ -16,25 +16,23 @@ 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-west-2-lax-1a) Type: String - LocalZoneNameShort: - Description: Short name for Local Zone used on tag Name (Example bos1) + SubnetName: + Description: Local Zone Name (Example cluster-usw2-lax-1a) Type: String PublicRouteTableId: Description: Public Route Table ID to associate the Local Zone subnet Type: String PublicSubnetCidr: + # yamllint disable-line rule:line-length 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 @@ -47,12 +45,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 +62,6 @@ Outputs: PublicSubnetIds: Description: Subnet IDs of the public subnets. Value: - !Join [ - "", - [!Ref PublicSubnet] - ] + !Join ["", [!Ref PublicSubnet]] ---- ==== From fe931207355bd6a31113e0c1ac512cecf6a09173 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:40:31 -0400 Subject: [PATCH 05/42] Add IAM policy to assembly prereqs --- .../installing-aws-localzone.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 0b41277a6846..7230533b0345 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -41,6 +41,25 @@ 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": [ + { + "Sid": "Stmt1677614927608", + "Action": [ + "ec2:ModifyAvailabilityZoneGroup" + ], + "Effect": "Allow", + "Resource": "*" + } + ] +} +---- include::modules/cluster-limitations-local-zone.adoc[leveloffset=+1] From 480264c299b7dec842f509651c3f293cc9ed0c27 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:47:14 -0400 Subject: [PATCH 06/42] Add sample deployment ref --- ...lation-aws-local-zones-ref-deployment.adoc | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 modules/installation-aws-local-zones-ref-deployment.adoc diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc new file mode 100644 index 000000000000..fbcb826d9b30 --- /dev/null +++ b/modules/installation-aws-local-zones-ref-deployment.adoc @@ -0,0 +1,62 @@ +:content-type: REFERENCE +[id="installation-aws-local-zones-ref-deployment_{context}"] +== An example application deployment with edge machine pools and AWS Local Zones + +This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: + +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: local-zone-demo +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: local-zone-demo-app-nyc-1 + namespace: local-zone-demo +spec: + selector: + matchLabels: + app: local-zone-demo-app-nyc-1 + replicas: 1 + template: + metadata: + labels: + app: local-zone-demo-app-nyc-1 + machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} + spec: + nodeSelector: + machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} + tolerations: + - key: "node-role.kubernetes.io/edge" + operator: "Equal" + value: "" + effect: "NoSchedule" + containers: + - image: openshift/origin-node + command: + - "/bin/socat" + args: + - TCP4-LISTEN:8080,reuseaddr,fork + - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' + imagePullPolicy: Always + name: echoserver + ports: + - containerPort: 8080 +--- +apiVersion: v1 +kind: Service +metadata: + name: local-zone-demo-app-nyc-1 + namespace: local-zone-demo +spec: + ports: + - port: 80 + targetPort: 8080 + protocol: TCP + type: NodePort + selector: + app: local-zone-demo-app-nyc-1 +---- \ No newline at end of file From fd16f6d9b01c641d5f865d5cb87405689817488a Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 11:53:56 -0400 Subject: [PATCH 07/42] rm working assembly -- no longer needed --- _topic_maps/_topic_map.yml | 2 - .../installing-aws-vpc-local-zones.adoc | 198 ------------------ 2 files changed, 200 deletions(-) delete mode 100644 installing/installing_aws/installing-aws-vpc-local-zones.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 86914d21ba04..c885f3a67c38 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -166,8 +166,6 @@ Topics: File: installing-restricted-networks-aws-installer-provisioned - Name: Installing a cluster on AWS into an existing VPC File: installing-aws-vpc - - Name: Installing a cluster on AWS using AWS Local Zones - File: installing-aws-vpc-local-zones - Name: Installing a private cluster on AWS File: installing-aws-private - Name: Installing a cluster on AWS into a government region diff --git a/installing/installing_aws/installing-aws-vpc-local-zones.adoc b/installing/installing_aws/installing-aws-vpc-local-zones.adoc deleted file mode 100644 index b34a03b0e888..000000000000 --- a/installing/installing_aws/installing-aws-vpc-local-zones.adoc +++ /dev/null @@ -1,198 +0,0 @@ -:_content-type: ASSEMBLY -[id="installing-aws-vpc-local-zones"] -= Installing a cluster on AWS using AWS Local Zones -include::_attributes/common-attributes.adoc[] -:context: installing-aws-vpc-local-zones - -toc::[] - -In {product-title} version {product-version}, you can install a cluster into an existing Amazon Virtual Private Cloud (VPC) on Amazon Web Services (AWS) that uses AWS Local Zones. - -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. - -== 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 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 downloaded the AWS CLI and installed it on your computer. -* 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. -* 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]. -* To use the AWS Local Zone deployment that is described in this document: -** 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": [ - { - "Sid": "Stmt1677614927608", - "Action": [ - "ec2:ModifyAvailabilityZoneGroup" - ], - "Effect": "Allow", - "Resource": "*" - } - ] -} ----- - -** Export the following environment variables: -+ -[source,terminal] ----- -export CLUSTER_NAME="ipi-localzones" - -# AWS Region and extra Local Zone group Information -export AWS_REGION="us-west-2" -export ZONE_GROUP_NAME="us-west-2-lax-1" -export ZONE_NAME="us-west-2-lax-1a" - -# VPC Information -export VPC_CIDR="10.0.0.0/16" -export VPC_SUBNETS_BITS="10" -export VPC_SUBNETS_COUNT="3" - -# Local Zone Subnet information -export SUBNET_CIDR="10.0.192.0/22" -export SUBNET_NAME="${CLUSTER_NAME}-public-usw2-lax-1a" ----- - -include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+1] - - -// TODO: This could just be a nixed w/the children bumped up a level. -:_content-type: PROCEDURE -[id="install-aws-local-zones-vpc-stack"] -== Creating the network stack - -Create a network stack that involves a virtual private cloud (VPC) and an AWS Local Zones subnet. While you can create the VPC by using the instructions in xref:../../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[Installing a cluster on AWS into an existing VPC], the following instructions use xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[CloudFormation templates] that rely on the environment variables you already set. - -include::modules/install-creating-aws-local-zones-vpc-stack.adoc[leveloffset=+2] -include::modules/install-creating-aws-local-zones-subnet.adoc[leveloffset=+2] - -[id="installing-cluster-aws-local-zones"] -== Install the cluster - -To install an OpenShift cluster in an existing VPC with subnets in Local Zones, follow these steps: - -* Generate the `install-config.yaml` file or provide your own. -* Set the option `platform.aws.subnets` to add the subnet IDs. -* Optional: Customize the edge compute pool. - -include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2] -include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/nw-aws-local-zones-user-workload-ingress.adoc[leveloffset=+1] - -// TODO: I would prefer not to have teardown instructions for this guide if we can help it. Would the user likely be able to figure this out on their own or with AWS' docs? - -// :_content-type: PROCEDURE -// == Removing the cluster - -// :_content-type: PROCEDURE -// === Destroying the cluster - -// [source,terminal] -// ---- -// ./openshift-install destroy cluster --dir ${CLUSTER_NAME} -// ---- - -// :_content-type: PROCEDURE -// === Destroying the Local Zone subnets - -// [source,terminal] -// ---- -// aws cloudformation delete-stack \ -// --region ${AWS_REGION} \ -// --stack-name ${SUBNET_NAME} -// ---- - -// :_content-type: PROCEDURE -// === Destroying the VPC - -// [source,terminal] -// ---- -// aws cloudformation delete-stack \ -// --region ${AWS_REGION} \ -// --stack-name ${CLUSTER_NAME}-vpc -// ---- - -// TODO: Shouldn't this be a blog post if anything? - -// :content-type: REFERENCE -// == Use Cases - -// :content-type: REFERENCE -// == A sample application deployment with edge machine pools and AWS Local Zones - -// The example below creates one sample application on the node running in the Local zone, setting the tolerations needed to pin the pod on the correct node: - -// [source,terminal] -// ---- -// cat << EOF | oc create -f - -// apiVersion: v1 -// kind: Namespace -// metadata: -// name: local-zone-demo -// --- -// apiVersion: apps/v1 -// kind: Deployment -// metadata: -// name: local-zone-demo-app-nyc-1 -// namespace: local-zone-demo -// spec: -// selector: -// matchLabels: -// app: local-zone-demo-app-nyc-1 -// replicas: 1 -// template: -// metadata: -// labels: -// app: local-zone-demo-app-nyc-1 -// machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} -// spec: -// nodeSelector: -// machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} -// tolerations: -// - key: "node-role.kubernetes.io/edge" -// operator: "Equal" -// value: "" -// effect: "NoSchedule" -// containers: -// - image: openshift/origin-node -// command: -// - "/bin/socat" -// args: -// - TCP4-LISTEN:8080,reuseaddr,fork -// - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' -// imagePullPolicy: Always -// name: echoserver -// ports: -// - containerPort: 8080 -// --- -// apiVersion: v1 -// kind: Service -// metadata: -// name: local-zone-demo-app-nyc-1 -// namespace: local-zone-demo -// spec: -// ports: -// - port: 80 -// targetPort: 8080 -// protocol: TCP -// type: NodePort -// selector: -// app: local-zone-demo-app-nyc-1 -// EOF -// ---- - From 97951887e480433d1f9d9e83d273aaa7eb5c52b0 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 12:20:40 -0400 Subject: [PATCH 08/42] Add Local Zone note to install-config params mod --- modules/installation-configuration-parameters.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc index 64fc084ef684..58e395781143 100644 --- a/modules/installation-configuration-parameters.adoc +++ b/modules/installation-configuration-parameters.adoc @@ -897,7 +897,7 @@ You can add up to 25 user defined tags during installation. The remaining 25 tag |`platform.aws.subnets` -|If you provide the VPC instead of allowing the installation program to create the VPC for you, specify the subnet for the cluster to use. The subnet must be part of the same `machineNetwork[].cidr` ranges that you specify. For a standard cluster, specify a public and a private subnet for each availability zone. For a private cluster, specify a private subnet for each availability zone. +|If you provide the VPC instead of allowing the installation program to create the VPC for you, specify the subnet for the cluster to use. The subnet must be part of the same `machineNetwork[].cidr` ranges that you specify. For a standard cluster, specify a public and a private subnet for each availability zone. For a private cluster, specify a private subnet for each availability zone. For clusters that use AWS Local Zones, you must add AWS Local Zone subnets to this list to ensure edge machine pool creation. |Valid subnet IDs. |==== From 959b6473b6cf0e5bf4c502a0cb1ad30fe7a81e60 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 12:21:57 -0400 Subject: [PATCH 09/42] Level fixes --- modules/edge-machine-pools-aws-local-zones.adoc | 2 +- modules/installation-aws-local-zones-ref-deployment.adoc | 2 +- modules/machines-edge-machine-pool.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index c8bc8441eca9..d1926f564d14 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -1,6 +1,6 @@ :_content-type: CONCEPT [id="edge-machine-pools-aws-local-zones_{context}"] -== Edge machine pools and AWS Local Zones += Edge machine pools and AWS Local Zones An edge machine pool generates workers that run in AWS Local Zones locations. These workers differ from the those of the default compute pool in the following ways: diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc index fbcb826d9b30..fbd8b0fef723 100644 --- a/modules/installation-aws-local-zones-ref-deployment.adoc +++ b/modules/installation-aws-local-zones-ref-deployment.adoc @@ -1,6 +1,6 @@ :content-type: REFERENCE [id="installation-aws-local-zones-ref-deployment_{context}"] -== An example application deployment with edge machine pools and AWS Local Zones += An example application deployment with edge machine pools and AWS Local Zones This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 0b4418bf0af0..4b6b94849e5e 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -1,7 +1,7 @@ :_content-type: CONCEPT [id="machines-edge-machine-pool_{context}"] -=== The edge machine pool += The edge machine pool {product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the image type and size limitations on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. From 34cde6b10a6eb8bc30173fa6f0bf456988721363 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 13:17:43 -0400 Subject: [PATCH 10/42] Tweak user-infra-generate module language --- modules/installation-user-infra-generate.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/installation-user-infra-generate.adoc b/modules/installation-user-infra-generate.adoc index d27f72edec72..de6a6362cb8f 100644 --- a/modules/installation-user-infra-generate.adoc +++ b/modules/installation-user-infra-generate.adoc @@ -84,7 +84,7 @@ ifdef::aws,gcp[] To install {product-title} on {cp-first} ({cp}) using user-provisioned infrastructure, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install-config.yaml` file, Kubernetes manifests, and Ignition config files. You also have the option to first set up a separate `var` partition during the preparation phases of installation. endif::aws,gcp[] ifdef::localzone[] -To install {product-title} on {cp-first} ({cp}) and use AWS Local Zones, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install-config.yaml` file and Kubernetes manifests. +To install {product-title} on {cp-first} ({cp}) and use AWS Local Zones, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install-config.yaml` file and configure add Local Zone subnets to it. endif::localzone[] ifdef::gcp-shared[] To install {product-title} on {cp-first} ({cp}) into a shared VPC, you must generate the `install-config.yaml` file and modify it so that the cluster uses the correct VPC networks, DNS zones, and project names. From 03c21dc59a5190f11d31d4cb5a13729ce2c8f2aa Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 21 Mar 2023 13:48:03 -0400 Subject: [PATCH 11/42] Add 'create install-config' module --- installing/installing_aws/installing-aws-localzone.adoc | 1 + modules/install-creating-install-config-aws-local-zones.adoc | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 7230533b0345..082898be25f4 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -104,6 +104,7 @@ include::modules/installation-generate-aws-user-infra-install-config.adoc[levelo include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+2] include::modules/installation-aws-local-zones-ref-deployment.adoc[leveloffset=+2] +include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index ae05296f064b..418935cda299 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -1,12 +1,12 @@ :_content-type: PROCEDURE [id="install-creating-install-config-aws-local-zones_{context}"] -=== Create an installation configuration file that uses AWS Local Zones subnets += Create an installation configuration file that uses AWS Local Zones subnets Create an `install-config.yaml` file that uses AWS Local Zones subnets. .Prerequisites -* You created subnets by using the procedure "Creating an AWS Local Zone subnet". +* You created subnets by using the procedure "Creating a subnet in AWS Local Zones". .Procedure From 32f9bafeae634f15f67e5fa56041dba7ce5a438d Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Wed, 22 Mar 2023 18:47:56 -0400 Subject: [PATCH 12/42] Label update --- modules/machines-edge-machine-pool.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 4b6b94849e5e..36c56d6717db 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -14,8 +14,8 @@ The default elastic block store (EBS) for Local Zone locations is `gp2`, which d The edge compute pool creates new labels that developers can use to deploy their applications onto those locations. The new labels are: * `node-role.kubernetes.io/edge=''` -* `zone_type=local-zone` -* `zone_group=` +* `machine.openshift.io/zone-type=local-zone` +* `machine.openshift.io/zone-group=<$ZONE_GROUP_NAME>` By default, the system creates the edge compute pool only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. From bfefd33bbd1b8459705bb1ba522ff1307865ee31 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Wed, 22 Mar 2023 18:48:33 -0400 Subject: [PATCH 13/42] Subnets list update --- modules/machines-edge-machine-pool.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 36c56d6717db..7f6a6b65ba40 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -33,14 +33,14 @@ platform: aws: region: us-west-2 subnets: - - subnet-0fc845d8e30fdb431 - - subnet-0a2675b7cbac2e537 - - subnet-01c0ac400e1920b47 - - subnet-0fee60966b7a93da6 - - subnet-002b48c0a91c8c641 - - subnet-093f00deb44ce81f4 - - subnet-0f85ae65796e8d107 -pullSecret: '{"auths": ...}' + - subnetID-private1 + - subnetID-private2 + - subnetID-private3 + - subnetID-public1 + - subnetID-public2 + - subnetID-public3 + - subnetID-localzone-public1 + pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- From f2631e42f94dd285142ee41d32536c7a61a6cda3 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Wed, 22 Mar 2023 21:08:19 -0400 Subject: [PATCH 14/42] Adding module Likely to remove if the smoother CloudFormation flows can be preserved. --- ...l-adding-aws-local-zones-subnets-list.adoc | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 modules/install-adding-aws-local-zones-subnets-list.adoc diff --git a/modules/install-adding-aws-local-zones-subnets-list.adoc b/modules/install-adding-aws-local-zones-subnets-list.adoc new file mode 100644 index 000000000000..c218baddb3e6 --- /dev/null +++ b/modules/install-adding-aws-local-zones-subnets-list.adoc @@ -0,0 +1,117 @@ +:_content-type: PROCEDURE +[id="install-adding-aws-local-zones-subnets-list_{context}"] += Adding AWS Local Zones subnets to an installation configuration file +// TODO: Not sure I want to use something like this at all. Committing the sketch for posterity... for now. +After you create AWS Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. + +.Prerequisites + +* You created subnets for AWS Local Zones as described in "Creating a subnet in AWS Local Zones". + +.Procedure + +. In your command line environment, define the following environment variables: +** AWS_REGION +** CLUSTER_NAME +** SUBNET_NAME +// TODO: Complete if this is to be used. + +. From a command line, run the following command to extract VPC private subnet IDs from AWS: ++ +[source,terminal] +---- +$ mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --query 'Stacks[0].Outputs[?OutputKey==`PrivateSubnetIds`].OutputValue' \ + --output text | tr ',' '\n') +---- + +. From a command line, run the following command to extract VPC public subnet IDs from AWS: ++ +[source,terminal] +---- +$ mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' \ + --output text | tr ',' '\n') +---- + +. Export the subnet stack IDs: ++ +[source,terminal] +---- +$ export SUBNET_ID=$(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${SUBNET_NAME} \ + --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) +---- + +. Append the the subnet stack IDs to the `SUBNETS` list: ++ +[source,terminal] +---- +$ SUBNETS+=(${SUBNET_ID}) +---- + +. View the subnet IDs: ++ +[source,terminal] +---- +$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done +---- ++ +.Example output +[source,terminal] +---- + subnets: + - subnetID-private1 + - subnetID-private2 + - subnetID-private3 + - subnetID-public1 + - subnetID-public2 + - subnetID-public3 + - subnetID-localzone-public1 +---- + +. Insert the IDs into the `install-config.yaml` file under `platform.aws.subnets`. For example: ++ +.An example installation configuration that includes Local Zones subnets +[source,yaml] +---- +apiVersion: v1 +baseDomain: devcluster.openshift.com +metadata: + name: ipi-localzone +platform: + aws: + region: us-west-2 + subnets: + - subnetID-private1 + - subnetID-private2 + - subnetID-private3 + - subnetID-public1 + - subnetID-public2 + - subnetID-public3 + - subnetID-localzone-public1 +pullSecret: '{"auths": ...}' +sshKey: ssh-ed25519 AAAA... +---- + +.Verification + +* Use `echo` to verify the number of subnets that you have. For example: ++ +[source,terminal] +---- +$ echo ${#SUBNETS[*]} +---- ++ +.Example output +[source,terminal] +---- +7 +---- ++ +If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file From 74cbe3fcac449ac1076be7956e0780c6b244fc19 Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Thu, 30 Mar 2023 20:05:52 -0400 Subject: [PATCH 15/42] Apply first batch of suggestions from dev review Co-authored-by: Marco Braga --- modules/edge-machine-pools-aws-local-zones.adoc | 6 ++---- modules/install-adding-aws-local-zones-subnets-list.adoc | 8 ++++---- modules/install-creating-aws-local-zones-subnet.adoc | 2 +- modules/installation-configuration-parameters.adoc | 8 +++++++- modules/machines-edge-machine-pool.adoc | 2 +- 5 files changed, 15 insertions(+), 11 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index d1926f564d14..b3e1ccb2dda4 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -2,9 +2,7 @@ [id="edge-machine-pools-aws-local-zones_{context}"] = Edge machine pools and AWS Local Zones -An edge machine pool generates workers that run in AWS Local Zones locations. These workers differ from the those of the default compute pool in the following ways: +An edge machine pool is a worker node that runs in AWS Local Zones locations. * AWS Local Zones resources are more expensive than those of normal availability zones. -* Latency between applications and end users are 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. -* Network load balancers do not support Local Zones subnets. -* The time for end users who are close to a metropolitan region to connect to applications that run in Local Zones can be as much as ten times faster than if those applications run in a parent region. \ No newline at end of file +* Latency between applications and end users are 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. \ No newline at end of file diff --git a/modules/install-adding-aws-local-zones-subnets-list.adoc b/modules/install-adding-aws-local-zones-subnets-list.adoc index c218baddb3e6..1d23557bcc4f 100644 --- a/modules/install-adding-aws-local-zones-subnets-list.adoc +++ b/modules/install-adding-aws-local-zones-subnets-list.adoc @@ -2,7 +2,7 @@ [id="install-adding-aws-local-zones-subnets-list_{context}"] = Adding AWS Local Zones subnets to an installation configuration file // TODO: Not sure I want to use something like this at all. Committing the sketch for posterity... for now. -After you create AWS Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. +After you create the VPC and Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. .Prerequisites @@ -38,7 +38,7 @@ $ mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks --output text | tr ',' '\n') ---- -. Export the subnet stack IDs: +. Export the Local Zone subnet ID: + [source,terminal] ---- @@ -48,7 +48,7 @@ $ export SUBNET_ID=$(aws cloudformation describe-stacks \ --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) ---- -. Append the the subnet stack IDs to the `SUBNETS` list: +. Append the Local Zone subnet ID to the VPC's Subnet list `SUBNETS`: + [source,terminal] ---- @@ -83,7 +83,7 @@ $ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done apiVersion: v1 baseDomain: devcluster.openshift.com metadata: - name: ipi-localzone + name: <$CLUSTER_NAME> platform: aws: region: us-west-2 diff --git a/modules/install-creating-aws-local-zones-subnet.adoc b/modules/install-creating-aws-local-zones-subnet.adoc index 15b3f0d26ec1..0f5f7720bc6a 100644 --- a/modules/install-creating-aws-local-zones-subnet.adoc +++ b/modules/install-creating-aws-local-zones-subnet.adoc @@ -53,7 +53,7 @@ aws cloudformation wait stack-create-complete \ export SUBNET_ID=$(aws cloudformation describe-stacks \ --region ${AWS_REGION} \ --stack-name ${SUBNET_NAME} \ - | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicSubnetIds").OutputValue' ) + --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) # Append the Local Zone Subnet ID to the Subnet List SUBNETS+=(${SUBNET_ID}) diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc index 58e395781143..d03ae43a408d 100644 --- a/modules/installation-configuration-parameters.adoc +++ b/modules/installation-configuration-parameters.adoc @@ -897,7 +897,13 @@ You can add up to 25 user defined tags during installation. The remaining 25 tag |`platform.aws.subnets` -|If you provide the VPC instead of allowing the installation program to create the VPC for you, specify the subnet for the cluster to use. The subnet must be part of the same `machineNetwork[].cidr` ranges that you specify. For a standard cluster, specify a public and a private subnet for each availability zone. For a private cluster, specify a private subnet for each availability zone. For clusters that use AWS Local Zones, you must add AWS Local Zone subnets to this list to ensure edge machine pool creation. +|If you provide the VPC instead of allowing the installation program to create the VPC for you, specify the subnet for the cluster to use. The subnet must be part of the same `machineNetwork[].cidr` ranges that you specify. + +For a standard cluster, specify a public and a private subnet for each availability zone. + +For a private cluster, specify a private subnet for each availability zone. + +For clusters that use AWS Local Zones, you must add AWS Local Zone subnets to this list to ensure edge machine pool creation. |Valid subnet IDs. |==== diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 7f6a6b65ba40..0b5e051e32c0 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -71,7 +71,7 @@ pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- -.Example edge pool with a custom EBS type +.Example edge pool with a custom EBS type `gp3` [source,yaml] ---- apiVersion: v1 From 2f7215c9c5a783ed21115e243290b411adf10b2f Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Mon, 17 Apr 2023 09:06:24 -0400 Subject: [PATCH 16/42] Apply some suggestions from dev review Co-authored-by: Yunfei Jiang <61686698+yunjiang29@users.noreply.github.com> Co-authored-by: Marco Braga --- modules/edge-machine-pools-aws-local-zones.adoc | 4 ++-- modules/install-creating-aws-local-zones-subnet.adoc | 4 ++-- modules/machines-edge-machine-pool.adoc | 8 ++------ modules/nw-aws-local-zones-user-workload-ingress.adoc | 2 +- 4 files changed, 7 insertions(+), 11 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index b3e1ccb2dda4..9514eab2f341 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -4,5 +4,5 @@ An edge machine pool is a worker node that runs in AWS Local Zones locations. -* AWS Local Zones resources are more expensive than those of normal availability zones. -* Latency between applications and end users are 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. \ No newline at end of file +* Amazon EC2 instances in the Local Zones are more expensive than Amazon EC2 instances in the Availability Zones +* Latency between applications and end users are 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. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-subnet.adoc b/modules/install-creating-aws-local-zones-subnet.adoc index 0f5f7720bc6a..a8ea8d2fbc3d 100644 --- a/modules/install-creating-aws-local-zones-subnet.adoc +++ b/modules/install-creating-aws-local-zones-subnet.adoc @@ -6,7 +6,7 @@ To create a Local Zone subnet, choose a zone group to enable and opt it in. Then .Procedure -. To opt the zone group in, from a command line, enter the following command: +. To enable a Local Zone, from a command line, enter the following command: + [source,terminal] ---- @@ -18,7 +18,7 @@ $ aws ec2 modify-availability-zone-group \ // TODO: GitHub // TODO: Review yaml--is this only us-west-2-lax-la? -. Create the stack for the Local Zone subnet `us-west-2-lax-1a`. For example: +. Create the stack for the Local Zone subnet. For example: + [source,terminal] ---- diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 0b5e051e32c0..d75c96d50611 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -5,11 +5,7 @@ {product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the image type and size limitations on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. -The default elastic block store (EBS) for Local Zone locations is `gp2`, which differs from the default worker pool. The preferred list of instance types for the edge compute pool follows the same order of worker pools. Depending on the availability of the location, the system chooses one of those instances. The preferred list of instance types for the edge compute pool includes: - -* `m6i.xlarge` -* `m5.xlarge` -* `c5d.2xlarge` +The default elastic block store (EBS) for Local Zone locations is `gp2`, which differs from the default worker pool. The preferred list of instance types for the edge compute pool follows the same order of worker pools, depending on the availability of the location. The edge compute pool creates new labels that developers can use to deploy their applications onto those locations. The new labels are: @@ -18,7 +14,7 @@ The edge compute pool creates new labels that developers can use to deploy their * `machine.openshift.io/zone-group=<$ZONE_GROUP_NAME>` -By default, the system creates the edge compute pool only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. +By default, the system creates the edge compute pool manifests only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec. This practice is demonstrated in the following examples: diff --git a/modules/nw-aws-local-zones-user-workload-ingress.adoc b/modules/nw-aws-local-zones-user-workload-ingress.adoc index 1564048f9022..e223e110bfe1 100644 --- a/modules/nw-aws-local-zones-user-workload-ingress.adoc +++ b/modules/nw-aws-local-zones-user-workload-ingress.adoc @@ -2,7 +2,7 @@ [id="nw-aws-local-zones-user-workload-ingress_{context}"] === User-workload ingress traffic on AWS Local Zones -Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The ALB Operator is available through the Operator Lifecycle Manager (OLM). +Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The AWS Load Balancer Operator is available through the Operator Lifecycle Manager (OLM). To optimize application deployment on AWS Local Zone locations, provision at least one new ALB Ingress per location to expose services that are deployed on the zones. From f506291914b2eb91986583bbc8d8d85daf6e1bee Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 18 Apr 2023 11:29:27 -0400 Subject: [PATCH 17/42] Update edge pools concept mod --- .../install-creating-aws-local-zones-subnet.adoc | 1 - modules/machines-edge-machine-pool.adoc | 14 +++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/modules/install-creating-aws-local-zones-subnet.adoc b/modules/install-creating-aws-local-zones-subnet.adoc index a8ea8d2fbc3d..e8fa942c2b55 100644 --- a/modules/install-creating-aws-local-zones-subnet.adoc +++ b/modules/install-creating-aws-local-zones-subnet.adoc @@ -17,7 +17,6 @@ $ aws ec2 modify-availability-zone-group \ ---- // TODO: GitHub -// TODO: Review yaml--is this only us-west-2-lax-la? . Create the stack for the Local Zone subnet. For example: + [source,terminal] diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index d75c96d50611..da495bb4030c 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -16,9 +16,11 @@ The edge compute pool creates new labels that developers can use to deploy their By default, the system creates the edge compute pool manifests only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. -The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec. This practice is demonstrated in the following examples: +The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec. -.Example edge pool +The following examples show `install-config.yaml` files that use the edge machine pool. + +.Configuration that uses an edge pool with default settings [source,yaml] ---- apiVersion: v1 @@ -40,7 +42,7 @@ platform: sshKey: ssh-ed25519 AAAA... ---- -.Example edge pool with a custom instance type +.Configuration that uses an edge pool with a custom instance type [source,yaml] ---- apiVersion: v1 @@ -67,7 +69,9 @@ pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- -.Example edge pool with a custom EBS type `gp3` +Instance types differ between locations. Check the AWS documentation to verify availability in the Local Zone in which the cluster will run. + +.Configuration that uses an edge pool with a custom EBS type [source,yaml] ---- apiVersion: v1 @@ -96,4 +100,4 @@ pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- -NOTE: Instance and EBS types can vary by location. \ No newline at end of file +EBS types differ between locations. Check the AWS documentation to verify availability in the Local Zone in which the cluster will run. \ No newline at end of file From bd8031cb9635c599508b2ddb590414482c289cde Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 25 Apr 2023 11:08:07 -0400 Subject: [PATCH 18/42] Remove ClusterName from param file --- ...llation-creating-aws-subnet-localzone.adoc | 27 ++++++++----------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index c0726b1ac892..cf493ba1ed37 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -34,10 +34,6 @@ requires: [source,json] ---- [ - { - "ParameterKey": "ClusterName", <1> - "ParameterValue": "mycluster" <2> - }, { "ParameterKey": "VpcId", <3> "ParameterValue": "vpc-" <4> @@ -60,20 +56,19 @@ requires: } ] ---- -<1> A short, representative cluster name to use for hostnames, etc. -<2> Specify the cluster name that you used when you generated the `install-config.yaml` file for the cluster. -<3> The VPC ID in which the Local Zone's subnet will be created. -<4> Specify the `VpcId` value from the output of the CloudFormation template +<1> Specify the cluster name that you used when you generated the `install-config.yaml` file for the cluster. +<2> The VPC ID in which the Local Zone's subnet will be created. +<3> Specify the `VpcId` value from the output of the CloudFormation template for the VPC. -<5> The Public Route Table ID for the VPC. -<6> Specify the `PublicRouteTableId` value from the output of the CloudFormation template for the VPC. -<7> The Local Zone name that the VPC belongs to. -<8> Specify the Local Zone that you opted your AWS account into, such as `us-east-1-nyc-1a`. -<9> The shortname of the AWS Local Zone that the VPC belongs to. -<10> Specify a short name for the AWS Local Zone that you opted your AWS account into, such as ``. For example, `us-east-1-nyc-1a` is shortened to `nyc-1a`. +<4> The Public Route Table ID for the VPC. +<5> Specify the `PublicRouteTableId` value from the output of the CloudFormation template for the VPC. +<6> The Local Zone name that the VPC belongs to. +<7> Specify the Local Zone that you opted your AWS account into, such as `us-east-1-nyc-1a`. +<8> The shortname of the AWS Local Zone that the VPC belongs to. +<9> Specify a short name for the AWS Local Zone that you opted your AWS account into, such as ``. For example, `us-east-1-nyc-1a` is shortened to `nyc-1a`. //How do we determine this shortname? -<11> The CIDR block to allow access to the Local Zone. -<12> Specify a CIDR block in the format `x.x.x.x/16-24`. +<10> The CIDR block to allow access to the Local Zone. +<11> Specify a CIDR block in the format `x.x.x.x/16-24`. //How do we know what this CIDR is? From 60c6b4fcb5abdf87b2349e1cfb1165eb6d9a7a5a Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 25 Apr 2023 11:28:25 -0400 Subject: [PATCH 19/42] Update local zone list command --- modules/installation-aws-add-local-zone-locations.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/modules/installation-aws-add-local-zone-locations.adoc b/modules/installation-aws-add-local-zone-locations.adoc index 41f323342852..6a159105bdc2 100644 --- a/modules/installation-aws-add-local-zone-locations.adoc +++ b/modules/installation-aws-add-local-zone-locations.adoc @@ -27,8 +27,7 @@ $ export CLUSTER_REGION="" <1> + [source,terminal] ---- -$ aws ec2 describe-availability-zones \ - --filters Name=region-name,Values=${CLUSTER_REGION} \ +$ aws --region ${CLUSTER_REGION} ec2 describe-availability-zones \ --query 'AvailabilityZones[].ZoneName' \ --all-availability-zones ---- From c470478e628d8fcd5cfc8f036d3768d0732a06d4 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Tue, 25 Apr 2023 11:50:08 -0400 Subject: [PATCH 20/42] Attempt to address zone_identifier feedback --- modules/installation-aws-add-local-zone-locations.adoc | 6 +++--- modules/installation-creating-aws-subnet-localzone.adoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/installation-aws-add-local-zone-locations.adoc b/modules/installation-aws-add-local-zone-locations.adoc index 6a159105bdc2..91aaaf8178a0 100644 --- a/modules/installation-aws-add-local-zone-locations.adoc +++ b/modules/installation-aws-add-local-zone-locations.adoc @@ -35,7 +35,7 @@ $ aws --region ${CLUSTER_REGION} ec2 describe-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}-LID-N[a-z]`:: Available AWS Local Zones. `${REGION}-LID-N` represents the zone group identifier, and `[a-z]` represents 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: @@ -44,8 +44,8 @@ Depending on the region, the list of available zones can be long. The different ---- $ export ZONE_GROUP_NAME="${CLUSTER_REGION}--" <1> ---- -<1> For `-`, 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. - +<1> For `-`, specify the location identifier and zone identifier for the Local Zone that you selected for your region. For example, specify `nyc-1` to use the US East (New York) Local Zone. +// TODO: Verify "`zone_identifier` stands for `N`" . Opt in to the zone group on your AWS account by running the following command: + [source,terminal] diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index cf493ba1ed37..f6f0375ac76c 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -64,7 +64,7 @@ for the VPC. <5> Specify the `PublicRouteTableId` value from the output of the CloudFormation template for the VPC. <6> The Local Zone name that the VPC belongs to. <7> Specify the Local Zone that you opted your AWS account into, such as `us-east-1-nyc-1a`. -<8> The shortname of the AWS Local Zone that the VPC belongs to. +<8> The shortname of the AWS Local Zone that the VPC belongs to. This name must match the pattern `N[a-z]`. <9> Specify a short name for the AWS Local Zone that you opted your AWS account into, such as ``. For example, `us-east-1-nyc-1a` is shortened to `nyc-1a`. //How do we determine this shortname? <10> The CIDR block to allow access to the Local Zone. From 8322dc763b60083d7730cc1dea306e8205d8c83b Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Tue, 25 Apr 2023 12:21:50 -0400 Subject: [PATCH 21/42] zone group name syntax change Co-authored-by: Yunfei Jiang <61686698+yunjiang29@users.noreply.github.com> --- modules/machines-edge-machine-pool.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index da495bb4030c..0df0465c6e96 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -11,7 +11,7 @@ The edge compute pool creates new labels that developers can use to deploy their * `node-role.kubernetes.io/edge=''` * `machine.openshift.io/zone-type=local-zone` -* `machine.openshift.io/zone-group=<$ZONE_GROUP_NAME>` +* `machine.openshift.io/zone-group=$ZONE_GROUP_NAME` By default, the system creates the edge compute pool manifests only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`. From 926127997d8c7814330f4f6f921ef726e706f53a Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 09:25:37 -0400 Subject: [PATCH 22/42] Remove unused modules --- ...l-adding-aws-local-zones-subnets-list.adoc | 117 ------------------ ...ll-creating-aws-local-zones-vpc-stack.adoc | 79 ------------ ...lation-aws-local-zones-ref-deployment.adoc | 62 ---------- ...aws-local-zones-user-workload-ingress.adoc | 9 -- 4 files changed, 267 deletions(-) delete mode 100644 modules/install-adding-aws-local-zones-subnets-list.adoc delete mode 100644 modules/install-creating-aws-local-zones-vpc-stack.adoc delete mode 100644 modules/installation-aws-local-zones-ref-deployment.adoc delete mode 100644 modules/nw-aws-local-zones-user-workload-ingress.adoc diff --git a/modules/install-adding-aws-local-zones-subnets-list.adoc b/modules/install-adding-aws-local-zones-subnets-list.adoc deleted file mode 100644 index 1d23557bcc4f..000000000000 --- a/modules/install-adding-aws-local-zones-subnets-list.adoc +++ /dev/null @@ -1,117 +0,0 @@ -:_content-type: PROCEDURE -[id="install-adding-aws-local-zones-subnets-list_{context}"] -= Adding AWS Local Zones subnets to an installation configuration file -// TODO: Not sure I want to use something like this at all. Committing the sketch for posterity... for now. -After you create the VPC and Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. - -.Prerequisites - -* You created subnets for AWS Local Zones as described in "Creating a subnet in AWS Local Zones". - -.Procedure - -. In your command line environment, define the following environment variables: -** AWS_REGION -** CLUSTER_NAME -** SUBNET_NAME -// TODO: Complete if this is to be used. - -. From a command line, run the following command to extract VPC private subnet IDs from AWS: -+ -[source,terminal] ----- -$ mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --query 'Stacks[0].Outputs[?OutputKey==`PrivateSubnetIds`].OutputValue' \ - --output text | tr ',' '\n') ----- - -. From a command line, run the following command to extract VPC public subnet IDs from AWS: -+ -[source,terminal] ----- -$ mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' \ - --output text | tr ',' '\n') ----- - -. Export the Local Zone subnet ID: -+ -[source,terminal] ----- -$ export SUBNET_ID=$(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${SUBNET_NAME} \ - --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) ----- - -. Append the Local Zone subnet ID to the VPC's Subnet list `SUBNETS`: -+ -[source,terminal] ----- -$ SUBNETS+=(${SUBNET_ID}) ----- - -. View the subnet IDs: -+ -[source,terminal] ----- -$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done ----- -+ -.Example output -[source,terminal] ----- - subnets: - - subnetID-private1 - - subnetID-private2 - - subnetID-private3 - - subnetID-public1 - - subnetID-public2 - - subnetID-public3 - - subnetID-localzone-public1 ----- - -. Insert the IDs into the `install-config.yaml` file under `platform.aws.subnets`. For example: -+ -.An example installation configuration that includes Local Zones subnets -[source,yaml] ----- -apiVersion: v1 -baseDomain: devcluster.openshift.com -metadata: - name: <$CLUSTER_NAME> -platform: - aws: - region: us-west-2 - subnets: - - subnetID-private1 - - subnetID-private2 - - subnetID-private3 - - subnetID-public1 - - subnetID-public2 - - subnetID-public3 - - subnetID-localzone-public1 -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... ----- - -.Verification - -* Use `echo` to verify the number of subnets that you have. For example: -+ -[source,terminal] ----- -$ echo ${#SUBNETS[*]} ----- -+ -.Example output -[source,terminal] ----- -7 ----- -+ -If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-vpc-stack.adoc b/modules/install-creating-aws-local-zones-vpc-stack.adoc deleted file mode 100644 index 98e2935747ba..000000000000 --- a/modules/install-creating-aws-local-zones-vpc-stack.adoc +++ /dev/null @@ -1,79 +0,0 @@ -:_content-type: PROCEDURE -[id="install-aws-local-zones-vpc-stack_{context}"] -=== Creating a VPC for AWS Local Zones - -Create a virtual private cloud (VPC) to use with AWS Local Zones. - -.Procedure -// TODO: GitHub links are not okay. -. From a command line, enter the following command to create the stack: -+ -[source,terminal] ----- -INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" -TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01_vpc.yaml" - -aws cloudformation create-stack \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --template-body ${TPL_URL} \ - --parameters \ - ParameterKey=VpcCidr,ParameterValue=${VPC_CIDR} \ - ParameterKey=SubnetBits,ParameterValue=${VPC_SUBNETS_BITS} \ - ParameterKey=AvailabilityZoneCount,ParameterValue=${VPC_SUBNETS_COUNT} ----- - -. Enter the following command to wait for the stack creation to finish: -+ -[source,terminal] ----- -aws cloudformation wait stack-create-complete \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc ----- -// TODO: jq is not okay. -. Enter the following command to export the VPC ID: -+ -[source,terminal] ----- -export VPC_ID=$(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="VpcId").OutputValue' ) ----- -// TODO: jq -. Extract the subnets IDs to the environment variable list `SUBNETS`. For example: -+ -[source,terminal] ----- -mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[0].OutputValue' | tr ',' '\n') -mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[1].OutputValue' | tr ',' '\n') ----- - -// TODO: jq -. Export the public route table ID. For example: -+ -[source,terminal] ----- -export PUBLIC_RTB_ID=$(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicRouteTableId").OutputValue' ) ----- - -.Verification - -* To review the variables that you exported, enter the following command: -+ -[source,terminal] ----- -echo "SUBNETS=${SUBNETS[*]} -VPC_ID=${VPC_ID} -PUBLIC_RTB_ID=${PUBLIC_RTB_ID}" ----- \ No newline at end of file diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc deleted file mode 100644 index fbd8b0fef723..000000000000 --- a/modules/installation-aws-local-zones-ref-deployment.adoc +++ /dev/null @@ -1,62 +0,0 @@ -:content-type: REFERENCE -[id="installation-aws-local-zones-ref-deployment_{context}"] -= An example application deployment with edge machine pools and AWS Local Zones - -This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: - -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: local-zone-demo ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: local-zone-demo-app-nyc-1 - namespace: local-zone-demo -spec: - selector: - matchLabels: - app: local-zone-demo-app-nyc-1 - replicas: 1 - template: - metadata: - labels: - app: local-zone-demo-app-nyc-1 - machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} - spec: - nodeSelector: - machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} - tolerations: - - key: "node-role.kubernetes.io/edge" - operator: "Equal" - value: "" - effect: "NoSchedule" - containers: - - image: openshift/origin-node - command: - - "/bin/socat" - args: - - TCP4-LISTEN:8080,reuseaddr,fork - - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' - imagePullPolicy: Always - name: echoserver - ports: - - containerPort: 8080 ---- -apiVersion: v1 -kind: Service -metadata: - name: local-zone-demo-app-nyc-1 - namespace: local-zone-demo -spec: - ports: - - port: 80 - targetPort: 8080 - protocol: TCP - type: NodePort - selector: - app: local-zone-demo-app-nyc-1 ----- \ No newline at end of file diff --git a/modules/nw-aws-local-zones-user-workload-ingress.adoc b/modules/nw-aws-local-zones-user-workload-ingress.adoc deleted file mode 100644 index e223e110bfe1..000000000000 --- a/modules/nw-aws-local-zones-user-workload-ingress.adoc +++ /dev/null @@ -1,9 +0,0 @@ -:content-type: CONCEPT -[id="nw-aws-local-zones-user-workload-ingress_{context}"] -=== User-workload ingress traffic on AWS Local Zones - -Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The AWS Load Balancer Operator is available through the Operator Lifecycle Manager (OLM). - -To optimize application deployment on AWS Local Zone locations, provision at least one new ALB Ingress per location to expose services that are deployed on the zones. - -If the cluster administrator shares ALB Ingress subnets across different locations, end-user latency can increase when traffic routes to back ends are located in different zones than from where the traffic originated. \ No newline at end of file From fe0419b2fd968d54a2abc080eb630c79a4f97326 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 09:46:36 -0400 Subject: [PATCH 23/42] Revert "Remove unused modules" This reverts commit a15f2b93e0a41c0a6b6b2d08cb01b9b938edaef1. --- ...l-adding-aws-local-zones-subnets-list.adoc | 117 ++++++++++++++++++ ...ll-creating-aws-local-zones-vpc-stack.adoc | 79 ++++++++++++ ...lation-aws-local-zones-ref-deployment.adoc | 62 ++++++++++ ...aws-local-zones-user-workload-ingress.adoc | 9 ++ 4 files changed, 267 insertions(+) create mode 100644 modules/install-adding-aws-local-zones-subnets-list.adoc create mode 100644 modules/install-creating-aws-local-zones-vpc-stack.adoc create mode 100644 modules/installation-aws-local-zones-ref-deployment.adoc create mode 100644 modules/nw-aws-local-zones-user-workload-ingress.adoc diff --git a/modules/install-adding-aws-local-zones-subnets-list.adoc b/modules/install-adding-aws-local-zones-subnets-list.adoc new file mode 100644 index 000000000000..1d23557bcc4f --- /dev/null +++ b/modules/install-adding-aws-local-zones-subnets-list.adoc @@ -0,0 +1,117 @@ +:_content-type: PROCEDURE +[id="install-adding-aws-local-zones-subnets-list_{context}"] += Adding AWS Local Zones subnets to an installation configuration file +// TODO: Not sure I want to use something like this at all. Committing the sketch for posterity... for now. +After you create the VPC and Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. + +.Prerequisites + +* You created subnets for AWS Local Zones as described in "Creating a subnet in AWS Local Zones". + +.Procedure + +. In your command line environment, define the following environment variables: +** AWS_REGION +** CLUSTER_NAME +** SUBNET_NAME +// TODO: Complete if this is to be used. + +. From a command line, run the following command to extract VPC private subnet IDs from AWS: ++ +[source,terminal] +---- +$ mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --query 'Stacks[0].Outputs[?OutputKey==`PrivateSubnetIds`].OutputValue' \ + --output text | tr ',' '\n') +---- + +. From a command line, run the following command to extract VPC public subnet IDs from AWS: ++ +[source,terminal] +---- +$ mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' \ + --output text | tr ',' '\n') +---- + +. Export the Local Zone subnet ID: ++ +[source,terminal] +---- +$ export SUBNET_ID=$(aws cloudformation describe-stacks \ + --region ${AWS_REGION} \ + --stack-name ${SUBNET_NAME} \ + --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) +---- + +. Append the Local Zone subnet ID to the VPC's Subnet list `SUBNETS`: ++ +[source,terminal] +---- +$ SUBNETS+=(${SUBNET_ID}) +---- + +. View the subnet IDs: ++ +[source,terminal] +---- +$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done +---- ++ +.Example output +[source,terminal] +---- + subnets: + - subnetID-private1 + - subnetID-private2 + - subnetID-private3 + - subnetID-public1 + - subnetID-public2 + - subnetID-public3 + - subnetID-localzone-public1 +---- + +. Insert the IDs into the `install-config.yaml` file under `platform.aws.subnets`. For example: ++ +.An example installation configuration that includes Local Zones subnets +[source,yaml] +---- +apiVersion: v1 +baseDomain: devcluster.openshift.com +metadata: + name: <$CLUSTER_NAME> +platform: + aws: + region: us-west-2 + subnets: + - subnetID-private1 + - subnetID-private2 + - subnetID-private3 + - subnetID-public1 + - subnetID-public2 + - subnetID-public3 + - subnetID-localzone-public1 +pullSecret: '{"auths": ...}' +sshKey: ssh-ed25519 AAAA... +---- + +.Verification + +* Use `echo` to verify the number of subnets that you have. For example: ++ +[source,terminal] +---- +$ echo ${#SUBNETS[*]} +---- ++ +.Example output +[source,terminal] +---- +7 +---- ++ +If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-vpc-stack.adoc b/modules/install-creating-aws-local-zones-vpc-stack.adoc new file mode 100644 index 000000000000..98e2935747ba --- /dev/null +++ b/modules/install-creating-aws-local-zones-vpc-stack.adoc @@ -0,0 +1,79 @@ +:_content-type: PROCEDURE +[id="install-aws-local-zones-vpc-stack_{context}"] +=== Creating a VPC for AWS Local Zones + +Create a virtual private cloud (VPC) to use with AWS Local Zones. + +.Procedure +// TODO: GitHub links are not okay. +. From a command line, enter the following command to create the stack: ++ +[source,terminal] +---- +INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" +TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01_vpc.yaml" + +aws cloudformation create-stack \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc \ + --template-body ${TPL_URL} \ + --parameters \ + ParameterKey=VpcCidr,ParameterValue=${VPC_CIDR} \ + ParameterKey=SubnetBits,ParameterValue=${VPC_SUBNETS_BITS} \ + ParameterKey=AvailabilityZoneCount,ParameterValue=${VPC_SUBNETS_COUNT} +---- + +. Enter the following command to wait for the stack creation to finish: ++ +[source,terminal] +---- +aws cloudformation wait stack-create-complete \ + --region ${AWS_REGION} \ + --stack-name ${CLUSTER_NAME}-vpc +---- +// TODO: jq is not okay. +. Enter the following command to export the VPC ID: ++ +[source,terminal] +---- +export VPC_ID=$(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="VpcId").OutputValue' ) +---- +// TODO: jq +. Extract the subnets IDs to the environment variable list `SUBNETS`. For example: ++ +[source,terminal] +---- +mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[0].OutputValue' | tr ',' '\n') +mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[1].OutputValue' | tr ',' '\n') +---- + +// TODO: jq +. Export the public route table ID. For example: ++ +[source,terminal] +---- +export PUBLIC_RTB_ID=$(aws cloudformation describe-stacks \ + --region us-west-2 \ + --stack-name ${CLUSTER_NAME}-vpc \ + | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicRouteTableId").OutputValue' ) +---- + +.Verification + +* To review the variables that you exported, enter the following command: ++ +[source,terminal] +---- +echo "SUBNETS=${SUBNETS[*]} +VPC_ID=${VPC_ID} +PUBLIC_RTB_ID=${PUBLIC_RTB_ID}" +---- \ No newline at end of file diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc new file mode 100644 index 000000000000..fbd8b0fef723 --- /dev/null +++ b/modules/installation-aws-local-zones-ref-deployment.adoc @@ -0,0 +1,62 @@ +:content-type: REFERENCE +[id="installation-aws-local-zones-ref-deployment_{context}"] += An example application deployment with edge machine pools and AWS Local Zones + +This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: + +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: local-zone-demo +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: local-zone-demo-app-nyc-1 + namespace: local-zone-demo +spec: + selector: + matchLabels: + app: local-zone-demo-app-nyc-1 + replicas: 1 + template: + metadata: + labels: + app: local-zone-demo-app-nyc-1 + machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} + spec: + nodeSelector: + machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} + tolerations: + - key: "node-role.kubernetes.io/edge" + operator: "Equal" + value: "" + effect: "NoSchedule" + containers: + - image: openshift/origin-node + command: + - "/bin/socat" + args: + - TCP4-LISTEN:8080,reuseaddr,fork + - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' + imagePullPolicy: Always + name: echoserver + ports: + - containerPort: 8080 +--- +apiVersion: v1 +kind: Service +metadata: + name: local-zone-demo-app-nyc-1 + namespace: local-zone-demo +spec: + ports: + - port: 80 + targetPort: 8080 + protocol: TCP + type: NodePort + selector: + app: local-zone-demo-app-nyc-1 +---- \ No newline at end of file diff --git a/modules/nw-aws-local-zones-user-workload-ingress.adoc b/modules/nw-aws-local-zones-user-workload-ingress.adoc new file mode 100644 index 000000000000..e223e110bfe1 --- /dev/null +++ b/modules/nw-aws-local-zones-user-workload-ingress.adoc @@ -0,0 +1,9 @@ +:content-type: CONCEPT +[id="nw-aws-local-zones-user-workload-ingress_{context}"] +=== User-workload ingress traffic on AWS Local Zones + +Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The AWS Load Balancer Operator is available through the Operator Lifecycle Manager (OLM). + +To optimize application deployment on AWS Local Zone locations, provision at least one new ALB Ingress per location to expose services that are deployed on the zones. + +If the cluster administrator shares ALB Ingress subnets across different locations, end-user latency can increase when traffic routes to back ends are located in different zones than from where the traffic originated. \ No newline at end of file From ab9bbcac5134cca4a0ff2c7dc783ebab5110f49d Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 10:00:28 -0400 Subject: [PATCH 24/42] Redo on the rms --- ...l-adding-aws-local-zones-subnets-list.adoc | 117 ------------------ ...stall-creating-aws-local-zones-subnet.adoc | 76 ------------ ...ll-creating-aws-local-zones-vpc-stack.adoc | 79 ------------ ...aws-local-zones-user-workload-ingress.adoc | 9 -- 4 files changed, 281 deletions(-) delete mode 100644 modules/install-adding-aws-local-zones-subnets-list.adoc delete mode 100644 modules/install-creating-aws-local-zones-subnet.adoc delete mode 100644 modules/install-creating-aws-local-zones-vpc-stack.adoc delete mode 100644 modules/nw-aws-local-zones-user-workload-ingress.adoc diff --git a/modules/install-adding-aws-local-zones-subnets-list.adoc b/modules/install-adding-aws-local-zones-subnets-list.adoc deleted file mode 100644 index 1d23557bcc4f..000000000000 --- a/modules/install-adding-aws-local-zones-subnets-list.adoc +++ /dev/null @@ -1,117 +0,0 @@ -:_content-type: PROCEDURE -[id="install-adding-aws-local-zones-subnets-list_{context}"] -= Adding AWS Local Zones subnets to an installation configuration file -// TODO: Not sure I want to use something like this at all. Committing the sketch for posterity... for now. -After you create the VPC and Local Zones subnets, insert their IDs into the installation configuration file that you use to deploy your cluster. - -.Prerequisites - -* You created subnets for AWS Local Zones as described in "Creating a subnet in AWS Local Zones". - -.Procedure - -. In your command line environment, define the following environment variables: -** AWS_REGION -** CLUSTER_NAME -** SUBNET_NAME -// TODO: Complete if this is to be used. - -. From a command line, run the following command to extract VPC private subnet IDs from AWS: -+ -[source,terminal] ----- -$ mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --query 'Stacks[0].Outputs[?OutputKey==`PrivateSubnetIds`].OutputValue' \ - --output text | tr ',' '\n') ----- - -. From a command line, run the following command to extract VPC public subnet IDs from AWS: -+ -[source,terminal] ----- -$ mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' \ - --output text | tr ',' '\n') ----- - -. Export the Local Zone subnet ID: -+ -[source,terminal] ----- -$ export SUBNET_ID=$(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${SUBNET_NAME} \ - --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) ----- - -. Append the Local Zone subnet ID to the VPC's Subnet list `SUBNETS`: -+ -[source,terminal] ----- -$ SUBNETS+=(${SUBNET_ID}) ----- - -. View the subnet IDs: -+ -[source,terminal] ----- -$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done ----- -+ -.Example output -[source,terminal] ----- - subnets: - - subnetID-private1 - - subnetID-private2 - - subnetID-private3 - - subnetID-public1 - - subnetID-public2 - - subnetID-public3 - - subnetID-localzone-public1 ----- - -. Insert the IDs into the `install-config.yaml` file under `platform.aws.subnets`. For example: -+ -.An example installation configuration that includes Local Zones subnets -[source,yaml] ----- -apiVersion: v1 -baseDomain: devcluster.openshift.com -metadata: - name: <$CLUSTER_NAME> -platform: - aws: - region: us-west-2 - subnets: - - subnetID-private1 - - subnetID-private2 - - subnetID-private3 - - subnetID-public1 - - subnetID-public2 - - subnetID-public3 - - subnetID-localzone-public1 -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... ----- - -.Verification - -* Use `echo` to verify the number of subnets that you have. For example: -+ -[source,terminal] ----- -$ echo ${#SUBNETS[*]} ----- -+ -.Example output -[source,terminal] ----- -7 ----- -+ -If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-subnet.adoc b/modules/install-creating-aws-local-zones-subnet.adoc deleted file mode 100644 index e8fa942c2b55..000000000000 --- a/modules/install-creating-aws-local-zones-subnet.adoc +++ /dev/null @@ -1,76 +0,0 @@ -:_content-type: PROCEDURE -[id="install-creating-aws-local-zones-subnet"] -=== Creating an AWS Local Zone subnet - -To create a Local Zone subnet, choose a zone group to enable and opt it in. Then, create the subnet. - -.Procedure - -. To enable a Local Zone, from a command line, enter the following command: -+ -[source,terminal] ----- -$ aws ec2 modify-availability-zone-group \ - --region ${AWS_REGION} \ - --group-name ${ZONE_GROUP_NAME} \ - --opt-in-status opted-in ----- - -// TODO: GitHub -. Create the stack for the Local Zone subnet. For example: -+ -[source,terminal] ----- -INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" -TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01.99_net_local-zone.yaml" - -aws cloudformation create-stack \ - --region ${AWS_REGION} \ - --stack-name ${SUBNET_NAME} \ - --template-body ${TPL_URL} \ - --parameters \ - ParameterKey=VpcId,ParameterValue=${VPC_ID} \ - ParameterKey=ZoneName,ParameterValue=${ZONE_NAME} \ - ParameterKey=SubnetName,ParameterValue=${SUBNET_NAME} \ - ParameterKey=PublicSubnetCidr,ParameterValue=${SUBNET_CIDR} \ - ParameterKey=PublicRouteTableId,ParameterValue=${PUBLIC_RTB_ID} ----- - -. Enter the following command to wait for the stack creation to finish: -+ -[source,terminal] ----- -aws cloudformation wait stack-create-complete \ - --region ${AWS_REGION} \ - --stack-name ${SUBNET_NAME} ----- -// TODO: jq -- Export the Local Zone subnet ID and append it to the subnet list. For example: -+ -[source,terminal] ----- -export SUBNET_ID=$(aws cloudformation describe-stacks \ - --region ${AWS_REGION} \ - --stack-name ${SUBNET_NAME} \ - --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' --output text) - -# Append the Local Zone Subnet ID to the Subnet List -SUBNETS+=(${SUBNET_ID}) ----- - -.Verification - -* Use `echo` to verify the number of subnets that you have. For example: -+ -[source,terminal] ----- -$ echo ${#SUBNETS[*]} ----- -+ -.Example output -[source,terminal] ----- -7 ----- -+ -If you choose 3 AZs to be created on the VPC stack, you should have 7 subnets on this list. \ No newline at end of file diff --git a/modules/install-creating-aws-local-zones-vpc-stack.adoc b/modules/install-creating-aws-local-zones-vpc-stack.adoc deleted file mode 100644 index 98e2935747ba..000000000000 --- a/modules/install-creating-aws-local-zones-vpc-stack.adoc +++ /dev/null @@ -1,79 +0,0 @@ -:_content-type: PROCEDURE -[id="install-aws-local-zones-vpc-stack_{context}"] -=== Creating a VPC for AWS Local Zones - -Create a virtual private cloud (VPC) to use with AWS Local Zones. - -.Procedure -// TODO: GitHub links are not okay. -. From a command line, enter the following command to create the stack: -+ -[source,terminal] ----- -INSTALLER_URL="https://raw.githubusercontent.com/openshift/installer/master" -TPL_URL="${INSTALLER_URL}/upi/aws/cloudformation/01_vpc.yaml" - -aws cloudformation create-stack \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc \ - --template-body ${TPL_URL} \ - --parameters \ - ParameterKey=VpcCidr,ParameterValue=${VPC_CIDR} \ - ParameterKey=SubnetBits,ParameterValue=${VPC_SUBNETS_BITS} \ - ParameterKey=AvailabilityZoneCount,ParameterValue=${VPC_SUBNETS_COUNT} ----- - -. Enter the following command to wait for the stack creation to finish: -+ -[source,terminal] ----- -aws cloudformation wait stack-create-complete \ - --region ${AWS_REGION} \ - --stack-name ${CLUSTER_NAME}-vpc ----- -// TODO: jq is not okay. -. Enter the following command to export the VPC ID: -+ -[source,terminal] ----- -export VPC_ID=$(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="VpcId").OutputValue' ) ----- -// TODO: jq -. Extract the subnets IDs to the environment variable list `SUBNETS`. For example: -+ -[source,terminal] ----- -mapfile -t SUBNETS < <(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[0].OutputValue' | tr ',' '\n') -mapfile -t -O "${#SUBNETS[@]}" SUBNETS < <(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[1].OutputValue' | tr ',' '\n') ----- - -// TODO: jq -. Export the public route table ID. For example: -+ -[source,terminal] ----- -export PUBLIC_RTB_ID=$(aws cloudformation describe-stacks \ - --region us-west-2 \ - --stack-name ${CLUSTER_NAME}-vpc \ - | jq -r '.Stacks[0].Outputs[] | select(.OutputKey=="PublicRouteTableId").OutputValue' ) ----- - -.Verification - -* To review the variables that you exported, enter the following command: -+ -[source,terminal] ----- -echo "SUBNETS=${SUBNETS[*]} -VPC_ID=${VPC_ID} -PUBLIC_RTB_ID=${PUBLIC_RTB_ID}" ----- \ No newline at end of file diff --git a/modules/nw-aws-local-zones-user-workload-ingress.adoc b/modules/nw-aws-local-zones-user-workload-ingress.adoc deleted file mode 100644 index e223e110bfe1..000000000000 --- a/modules/nw-aws-local-zones-user-workload-ingress.adoc +++ /dev/null @@ -1,9 +0,0 @@ -:content-type: CONCEPT -[id="nw-aws-local-zones-user-workload-ingress_{context}"] -=== User-workload ingress traffic on AWS Local Zones - -Developers must use an external Load Balancer, such as AWS Application Load Balancers (ALB), to enable internet access to applications on AWS Local Zones. The AWS Load Balancer Operator is available through the Operator Lifecycle Manager (OLM). - -To optimize application deployment on AWS Local Zone locations, provision at least one new ALB Ingress per location to expose services that are deployed on the zones. - -If the cluster administrator shares ALB Ingress subnets across different locations, end-user latency can increase when traffic routes to back ends are located in different zones than from where the traffic originated. \ No newline at end of file From 88eb252e683e3f316cc7192f01997d3632dc8a6a Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Thu, 27 Apr 2023 10:11:03 -0400 Subject: [PATCH 25/42] Apply suggestions from review Co-authored-by: Marco Braga --- .../installing-aws-localzone.adoc | 1 - .../edge-machine-pools-aws-local-zones.adoc | 4 +-- ...lation-aws-local-zones-ref-deployment.adoc | 2 +- modules/machines-edge-machine-pool.adoc | 36 +++++++++---------- 4 files changed, 21 insertions(+), 22 deletions(-) diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 082898be25f4..8e6be4f3ed70 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -50,7 +50,6 @@ Be sure to also review this site list if you are configuring a proxy. "Version": "2012-10-17", "Statement": [ { - "Sid": "Stmt1677614927608", "Action": [ "ec2:ModifyAvailabilityZoneGroup" ], diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index 9514eab2f341..502efe4bd500 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -1,8 +1,8 @@ :_content-type: CONCEPT [id="edge-machine-pools-aws-local-zones_{context}"] -= Edge machine pools and AWS Local Zones += Edge compute pools and AWS Local Zones -An edge machine pool is a worker node that runs in AWS Local Zones locations. +Edge worker nodes are tainted worker nodes that run in AWS Local Zones locations. * Amazon EC2 instances in the Local Zones are more expensive than Amazon EC2 instances in the Availability Zones * Latency between applications and end users are 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. \ No newline at end of file diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc index fbd8b0fef723..f0ff8ac787b3 100644 --- a/modules/installation-aws-local-zones-ref-deployment.adoc +++ b/modules/installation-aws-local-zones-ref-deployment.adoc @@ -1,6 +1,6 @@ :content-type: REFERENCE [id="installation-aws-local-zones-ref-deployment_{context}"] -= An example application deployment with edge machine pools and AWS Local Zones += An example application deployment with edge compute pool and AWS Local Zones This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 0df0465c6e96..2d6ea5ac3d52 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -1,13 +1,13 @@ :_content-type: CONCEPT [id="machines-edge-machine-pool_{context}"] -= The edge machine pool += The edge compute pool -{product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the image type and size limitations on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. +{product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the type and size limitations of resources like EC2 and EBS on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. -The default elastic block store (EBS) for Local Zone locations is `gp2`, which differs from the default worker pool. The preferred list of instance types for the edge compute pool follows the same order of worker pools, depending on the availability of the location. +The default Elastic Block Store (EBS) for Local Zone locations is `gp2`, which differs from the regular worker pool. The instance type used for each Local Zone on edge compute pool also may differ from worker pools, depending on the instance offerings on the zone. -The edge compute pool creates new labels that developers can use to deploy their applications onto those locations. The new labels are: +The edge compute pool creates new labels that developers can use to deploy applications onto AWS Local Zone nodes. The new labels are: * `node-role.kubernetes.io/edge=''` * `machine.openshift.io/zone-type=local-zone` @@ -31,13 +31,13 @@ platform: aws: region: us-west-2 subnets: - - subnetID-private1 - - subnetID-private2 - - subnetID-private3 - - subnetID-public1 - - subnetID-public2 - - subnetID-public3 - - subnetID-localzone-public1 + - publicSubnetId-1 + - publicSubnetId-2 + - publicSubnetId-3 + - privateSubnetId-1 + - privateSubnetId-2 + - privateSubnetId-3 + - publicSubnetId-LocalZone-1 pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- @@ -58,13 +58,13 @@ platform: aws: region: us-west-2 subnets: - - subnet-0fc845d8e30fdb431 - - subnet-0a2675b7cbac2e537 - - subnet-01c0ac400e1920b47 - - subnet-0fee60966b7a93da6 - - subnet-002b48c0a91c8c641 - - subnet-093f00deb44ce81f4 - - subnet-0f85ae65796e8d107 + - publicSubnetId-1 + - publicSubnetId-2 + - publicSubnetId-3 + - privateSubnetId-1 + - privateSubnetId-2 + - privateSubnetId-3 + - publicSubnetId-LocalZone-1 pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- From daaca3565dfdda3c4397a5e984ed807d3fb095e7 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 16:11:11 -0400 Subject: [PATCH 26/42] Remove installation-aws-local-zones-ref-deployment --- .../installing-aws-localzone.adoc | 1 - ...lation-aws-local-zones-ref-deployment.adoc | 62 ------------------- 2 files changed, 63 deletions(-) delete mode 100644 modules/installation-aws-local-zones-ref-deployment.adoc diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 8e6be4f3ed70..2550e7b7dcd3 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -102,7 +102,6 @@ include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2] include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2] include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+2] -include::modules/installation-aws-local-zones-ref-deployment.adoc[leveloffset=+2] include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2] [role="_additional-resources"] diff --git a/modules/installation-aws-local-zones-ref-deployment.adoc b/modules/installation-aws-local-zones-ref-deployment.adoc deleted file mode 100644 index f0ff8ac787b3..000000000000 --- a/modules/installation-aws-local-zones-ref-deployment.adoc +++ /dev/null @@ -1,62 +0,0 @@ -:content-type: REFERENCE -[id="installation-aws-local-zones-ref-deployment_{context}"] -= An example application deployment with edge compute pool and AWS Local Zones - -This example deployment creates one sample application on the node that runs in the Local zone and sets the tolerations required to pin the pod on the correct node: - -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: local-zone-demo ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: local-zone-demo-app-nyc-1 - namespace: local-zone-demo -spec: - selector: - matchLabels: - app: local-zone-demo-app-nyc-1 - replicas: 1 - template: - metadata: - labels: - app: local-zone-demo-app-nyc-1 - machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} - spec: - nodeSelector: - machine.openshift.io/zone-group: ${ZONE_GROUP_NAME} - tolerations: - - key: "node-role.kubernetes.io/edge" - operator: "Equal" - value: "" - effect: "NoSchedule" - containers: - - image: openshift/origin-node - command: - - "/bin/socat" - args: - - TCP4-LISTEN:8080,reuseaddr,fork - - EXEC:'/bin/bash -c \"printf \\\"HTTP/1.0 200 OK\r\n\r\n\\\"; sed -e \\\"/^\r/q\\\"\"' - imagePullPolicy: Always - name: echoserver - ports: - - containerPort: 8080 ---- -apiVersion: v1 -kind: Service -metadata: - name: local-zone-demo-app-nyc-1 - namespace: local-zone-demo -spec: - ports: - - port: 80 - targetPort: 8080 - protocol: TCP - type: NodePort - selector: - app: local-zone-demo-app-nyc-1 ----- \ No newline at end of file From 0877d58f49e7c52186538a2f48876c3f8d8162cb Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 16:29:59 -0400 Subject: [PATCH 27/42] Update subnets in example --- modules/machines-edge-machine-pool.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index 2d6ea5ac3d52..f9dee8b94a69 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -89,13 +89,13 @@ platform: aws: region: us-west-2 subnets: - - subnet-0fc845d8e30fdb431 - - subnet-0a2675b7cbac2e537 - - subnet-01c0ac400e1920b47 - - subnet-0fee60966b7a93da6 - - subnet-002b48c0a91c8c641 - - subnet-093f00deb44ce81f4 - - subnet-0f85ae65796e8d107 + - publicSubnetId-1 + - publicSubnetId-2 + - publicSubnetId-3 + - privateSubnetId-1 + - privateSubnetId-2 + - privateSubnetId-3 + - publicSubnetId-LocalZone-1 pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- From 1898040387cddf50149cd3ab88577a78a367e3e5 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 16:42:27 -0400 Subject: [PATCH 28/42] Repurpose 'add subnets to config' mod --- ...-creating-install-config-aws-local-zones.adoc | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 418935cda299..2ceb614f6509 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -1,25 +1,17 @@ :_content-type: PROCEDURE [id="install-creating-install-config-aws-local-zones_{context}"] -= Create an installation configuration file that uses AWS Local Zones subnets += Modify an installation configuration file to use AWS Local Zones subnets -Create an `install-config.yaml` file that uses 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 -. From a command line, enter the following command to create the `install-config.yaml` file: -+ -[source,terminal] ----- -$ ./openshift-install create install-config --dir ${CLUSTER_NAME} ----- -+ -Follow the prompts that result from running the command. - -. Append the subnets to the value of the `platform.aws.subnets` property. As an example: +* Append the subnets to the value of the `platform.aws.subnets` property. As an example: + [source,terminal] ---- From 8bef9f2be37e2fd99f22e40b820493dd56e5a372 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 17:01:34 -0400 Subject: [PATCH 29/42] fixup! Repurpose 'add subnets to config' mod --- ...eating-install-config-aws-local-zones.adoc | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 2ceb614f6509..61a5329d2842 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -13,15 +13,20 @@ Modify an `install-config.yaml` file to include AWS Local Zones subnets. * Append the subnets to the value of the `platform.aws.subnets` property. As an example: + -[source,terminal] +[source,yaml] ---- -$ echo " subnets:"; for SB in ${SUBNETS[*]}; do echo " - $SB"; done - subnets: - - subnet-0fc845d8e30fdb431 - - subnet-0a2675b7cbac2e537 - - subnet-01c0ac400e1920b47 - - subnet-0fee60966b7a93da6 - - subnet-002b48c0a91c8c641 - - subnet-093f00deb44ce81f4 - - subnet-0f85ae65796e8d107 ----- \ No newline at end of file +... +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 AWS Local Zones subnets \ No newline at end of file From f8c1b5f1a4443cb29f20f1e4a050e86e4cd48ac5 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 17:04:11 -0400 Subject: [PATCH 30/42] Change level for Edge compute pools mod --- installing/installing_aws/installing-aws-localzone.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index 2550e7b7dcd3..a03596e3f905 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -101,7 +101,7 @@ include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2] include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2] include::modules/machines-edge-machine-pool.adoc[leveloffset=+2] -include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+2] +include::modules/edge-machine-pools-aws-local-zones.adoc[leveloffset=+3] include::modules/install-creating-install-config-aws-local-zones.adoc[leveloffset=+2] [role="_additional-resources"] From 310869794e71b2b859a5ccafa75efd2c0f51690c Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Thu, 27 Apr 2023 20:43:31 -0400 Subject: [PATCH 31/42] Correct subnets list callout Co-authored-by: Marco Braga --- modules/install-creating-install-config-aws-local-zones.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 61a5329d2842..5e9951dab910 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -29,4 +29,4 @@ platform: - publicSubnetId-LocalZone-1 ... ---- -<1> List of AWS Local Zones subnets \ No newline at end of file +<1> List of subnets created in the Availability and Local Zones. \ No newline at end of file From 72d7161fe7dd03585948cfd31b1cb443b5bcac8b Mon Sep 17 00:00:00 2001 From: Marco Braga Date: Thu, 27 Apr 2023 21:51:04 -0300 Subject: [PATCH 32/42] simplifying the Zone group explanation for Local Zones OSDOCS-5240 (#3) * simplifying the zone group explanation * Update modules/installation-aws-add-local-zone-locations.adoc Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> --------- Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> --- ...allation-aws-add-local-zone-locations.adoc | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/modules/installation-aws-add-local-zone-locations.adoc b/modules/installation-aws-add-local-zone-locations.adoc index 91aaaf8178a0..a020e9d45880 100644 --- a/modules/installation-aws-add-local-zone-locations.adoc +++ b/modules/installation-aws-add-local-zone-locations.adoc @@ -24,28 +24,33 @@ $ export CLUSTER_REGION="" <1> <1> For ``, 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 --region ${CLUSTER_REGION} ec2 describe-availability-zones \ - --query 'AvailabilityZones[].ZoneName' \ + --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` represents the zone group identifier, and `[a-z]` represents 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}--" <1> +$ export ZONE_GROUP_NAME="" <1> ---- -<1> For `-`, specify the location identifier and zone identifier for the Local Zone that you selected for your region. For example, specify `nyc-1` to use the US East (New York) Local Zone. -// TODO: Verify "`zone_identifier` stands for `N`" ++ +where: + +:: 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: + [source,terminal] From e6722a9fb9141cba02e17cad5052ebb2755b8e46 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 27 Apr 2023 21:22:14 -0400 Subject: [PATCH 33/42] Subnets module attempt 1 --- ...reating-install-config-aws-local-zones.adoc | 2 +- ...generate-aws-user-infra-install-config.adoc | 18 ------------------ 2 files changed, 1 insertion(+), 19 deletions(-) diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 5e9951dab910..98dd024ed889 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -11,7 +11,7 @@ Modify an `install-config.yaml` file to include AWS Local Zones subnets. .Procedure -* Append the subnets to the value of the `platform.aws.subnets` property. As an example: +* Add the VPC and Local Zone subnets as the values of the `platform.aws.subnets` property. As an example: + [source,yaml] ---- diff --git a/modules/installation-generate-aws-user-infra-install-config.adoc b/modules/installation-generate-aws-user-infra-install-config.adoc index 9501617b1345..b81cf578cecc 100644 --- a/modules/installation-generate-aws-user-infra-install-config.adoc +++ b/modules/installation-generate-aws-user-infra-install-config.adoc @@ -130,24 +130,6 @@ publish: Internal By setting this option, you create an internal Ingress Controller and a private load balancer. endif::restricted[] -ifdef::localzone[] -. Edit the `install-config.yaml` file to provide the subnets for the availability zones that your VPC uses: -+ -[source,yaml] ----- -platform: - aws: - subnets: <1> - - publicSubnetId-1 - - publicSubnetId-2 - - publicSubnetId-3 - - privateSubnetId-1 - - privateSubnetId-2 - - privateSubnetId-3 ----- -<1> Add the `subnets` section and specify the `PrivateSubnetIds` and `PublicSubnetIds` values from the outputs of the CloudFormation template for the VPC. Do not include the Local Zone subnets here. -endif::localzone[] - ifdef::three-node-cluster[] . If you are installing a three-node cluster, modify the `install-config.yaml` file by setting the `compute.replicas` parameter to `0`. This ensures that the cluster's control planes are schedulable. For more information, see "Installing a three-node cluster on AWS". endif::three-node-cluster[] From a0b08c1580385337606f1e24cbe2df89a22c3d79 Mon Sep 17 00:00:00 2001 From: Marco Braga Date: Fri, 28 Apr 2023 14:59:31 -0300 Subject: [PATCH 34/42] OSDOCS-5240 #57427: review rendered page with important fixes on the structure (#4) * OSDOCS-5240 #57427: review rendered page with important fixes on the structure * Apply suggestions from code review Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> --------- Co-authored-by: Max Bridges <50179998+maxwelldb@users.noreply.github.com> --- .../installing-aws-localzone.adoc | 20 ++++--- .../edge-machine-pools-aws-local-zones.adoc | 17 +++++- ...ation-cloudformation-subnet-localzone.adoc | 5 +- ...allation-cloudformation-vpc-localzone.adoc | 4 +- ...llation-creating-aws-subnet-localzone.adoc | 42 +++++--------- ...stallation-creating-aws-vpc-localzone.adoc | 31 ++++------ modules/machine-edge-pool-review-nodes.adoc | 56 +++++++++++++++++++ modules/machines-edge-machine-pool.adoc | 2 +- 8 files changed, 117 insertions(+), 60 deletions(-) create mode 100644 modules/machine-edge-pool-review-nodes.adoc diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc index a03596e3f905..2e6120ddaeeb 100644 --- a/installing/installing_aws/installing-aws-localzone.adoc +++ b/installing/installing_aws/installing-aws-localzone.adoc @@ -69,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] @@ -100,8 +100,16 @@ 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"] @@ -115,11 +123,6 @@ 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] -[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] @@ -137,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"] @@ -147,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]. diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index 502efe4bd500..267b45346c64 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -4,5 +4,20 @@ 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 are 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. \ No newline at end of file +* Latency between applications and end users are 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. + ++ +[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. 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 could provide additional features, like IPsec, that also must be decreased the MTU. Check the documentation for additional information. +==== diff --git a/modules/installation-cloudformation-subnet-localzone.adoc b/modules/installation-cloudformation-subnet-localzone.adoc index a17c8db68b7d..47503db35a56 100644 --- a/modules/installation-cloudformation-subnet-localzone.adoc +++ b/modules/installation-cloudformation-subnet-localzone.adoc @@ -23,16 +23,15 @@ Parameters: Description: VPC Id Type: String ZoneName: - Description: Local Zone Name (Example us-west-2-lax-1a) + Description: Local Zone Name (Example us-east-1-nyc-1a) Type: String SubnetName: - Description: Local Zone Name (Example cluster-usw2-lax-1a) + 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 Type: String PublicSubnetCidr: - # yamllint disable-line rule:line-length 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 diff --git a/modules/installation-cloudformation-vpc-localzone.adoc b/modules/installation-cloudformation-vpc-localzone.adoc index fa0af34ed2a4..e242a8f0f46d 100644 --- a/modules/installation-cloudformation-vpc-localzone.adoc +++ b/modules/installation-cloudformation-vpc-localzone.adoc @@ -4,10 +4,10 @@ :_content-type: REFERENCE [id="installation-cloudformation-vpc-localzone_{context}"] -= CloudFormation template for the VPC that uses AWS Local Zones += CloudFormation template for the VPC You can use the following CloudFormation template to deploy the VPC that -you need for your {product-title} cluster that uses AWS Local Zones. +you need for your {product-title} cluster. .CloudFormation template for the VPC [%collapsible] diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index f6f0375ac76c..928a54bae6d8 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -35,42 +35,30 @@ requires: ---- [ { - "ParameterKey": "VpcId", <3> - "ParameterValue": "vpc-" <4> + "ParameterKey": "VpcId", + "ParameterValue": "" <1> }, { - "ParameterKey": "PublicRouteTableId", <5> - "ParameterValue": "" <6> + "ParameterKey": "PublicRouteTableId", + "ParameterValue": "" <2> }, { - "ParameterKey": "LocalZoneName", <7> - "ParameterValue": "--" <8> + "ParameterKey": "LocalZoneName", + "ParameterValue": "" <3> }, { - "ParameterKey": "LocalZoneNameShort", <9> - "ParameterValue": "" <10> - }, - { - "ParameterKey": "PublicSubnetCidr", <11> - "ParameterValue": "10.0.128.0/20" <12> + "ParameterKey": "PublicSubnetCidr", + "ParameterValue": "10.0.192.0/20" <4> } ] ---- -<1> Specify the cluster name that you used when you generated the `install-config.yaml` file for the cluster. -<2> The VPC ID in which the Local Zone's subnet will be created. -<3> Specify the `VpcId` value from the output of the CloudFormation template +<1> Specify the VPC ID, which is the value `VpcID` in the output of the CloudFormation template. for the VPC. -<4> The Public Route Table ID for the VPC. -<5> Specify the `PublicRouteTableId` value from the output of the CloudFormation template for the VPC. -<6> The Local Zone name that the VPC belongs to. -<7> Specify the Local Zone that you opted your AWS account into, such as `us-east-1-nyc-1a`. -<8> The shortname of the AWS Local Zone that the VPC belongs to. This name must match the pattern `N[a-z]`. -<9> Specify a short name for the AWS Local Zone that you opted your AWS account into, such as ``. For example, `us-east-1-nyc-1a` is shortened to `nyc-1a`. -//How do we determine this shortname? -<10> The CIDR block to allow access to the Local Zone. -<11> Specify a CIDR block in the format `x.x.x.x/16-24`. -//How do we know what this CIDR is? - +<2> Specify the Route Table ID, which is the value of the `PublicRouteTableId` in the CloudFormation stack +for the VPC. +```suggestion +<3> Specify the AWS Local Zone name, which is the value of the `ZoneName` field in the `AvailabilityZones` object that you retrieve in the section "Opting into AWS Local Zones". +<4> Specify a CIDR block that is used to create the Local Zone subnet. This block must be part of the VPC CIDR block `VpcCidr`. . Copy the template from the *CloudFormation template for the subnet* section of this topic and save it as a YAML file on your computer. This template @@ -99,7 +87,7 @@ parameters JSON file. .Example output [source,terminal] ---- -arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-lz-nyc1/dbedae40-2fd3-11eb-820e-12a48460849f +arn:aws:cloudformation:us-east-1:123456789012:stack//dbedae40-2fd3-11eb-820e-12a48460849f ---- . Confirm that the template components exist by running the following command: diff --git a/modules/installation-creating-aws-vpc-localzone.adoc b/modules/installation-creating-aws-vpc-localzone.adoc index 3b4e12689de0..1cca351d8450 100644 --- a/modules/installation-creating-aws-vpc-localzone.adoc +++ b/modules/installation-creating-aws-vpc-localzone.adoc @@ -35,32 +35,25 @@ requires: ---- [ { - "ParameterKey": "ClusterName", <1> - "ParameterValue": "mycluster" <2> + "ParameterKey": "VpcCidr", <1> + "ParameterValue": "10.0.0.0/16" <2> }, { - "ParameterKey": "VpcCidr", <3> - "ParameterValue": "10.0.0.0/16" <4> + "ParameterKey": "AvailabilityZoneCount", <3> + "ParameterValue": "3" <4> }, { - "ParameterKey": "AvailabilityZoneCount", <5> - "ParameterValue": "3" <6> - }, - { - "ParameterKey": "SubnetBits", <7> - "ParameterValue": "12" <8> + "ParameterKey": "SubnetBits", <5> + "ParameterValue": "12" <6> } ] ---- -<1> A short, representative cluster name to use for hostnames, etc. -<2> Specify the cluster name that you used when you generated the -`install-config.yaml` file for the cluster. -<3> The CIDR block for the VPC. -<4> Specify a CIDR block in the format `x.x.x.x/16-24`. -<5> The number of availability zones to deploy the VPC in. -<6> Specify an integer between `1` and `3`. -<7> The size of each subnet in each availability zone. -<8> Specify an integer between `5` and `13`, where `5` is `/27` and `13` is `/19`. +<1> The CIDR block for the VPC. +<2> Specify a CIDR block in the format `x.x.x.x/16-24`. +<3> The number of availability zones to deploy the VPC in. +<4> Specify an integer between `1` and `3`. +<5> The size of each subnet in each availability zone. +<6> Specify an integer between `5` and `13`, where `5` is `/27` and `13` is `/19`. . Copy the template from the *CloudFormation template for the VPC* section of this topic and save it as a YAML file on your computer. This template diff --git a/modules/machine-edge-pool-review-nodes.adoc b/modules/machine-edge-pool-review-nodes.adoc new file mode 100644 index 000000000000..df63fedc5816 --- /dev/null +++ b/modules/machine-edge-pool-review-nodes.adoc @@ -0,0 +1,56 @@ + +:_content-type: PROCEDURE +[id="machine-edge-pool-review-nodes_{context}"] += Verifying nodes that were created with edge compute pool + +After your install a cluster that uses AWS Local Zones, check the status of the machine that was created by the machine set manifests created at install time. + +. To check the machine sets created from the subnet you added to the `install-config.yaml` file, enter the following command: ++ +[source,terminal] +---- +$ oc get machineset -n openshift-machine-api --show-labels +---- ++ +.Example output +[source,terminal] +---- +NAME DESIRED CURRENT READY AVAILABLE AGE LABELS +cluster-7xw5g-edge-us-east-1-nyc-1a 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g +cluster-7xw5g-worker-us-east-1a 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g +cluster-7xw5g-worker-us-east-1b 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g +cluster-7xw5g-worker-us-east-1c 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g +---- + +. To check the machines that were created from the machine sets, enter the following command: ++ +[source,terminal] +---- +$ oc get machines -n openshift-machine-api +---- ++ +.Example output +---- +NAME PHASE TYPE REGION ZONE AGE +cluster-7xw5g-edge-us-east-1-nyc-1a-wbclh Running c5d.2xlarge us-east-1 us-east-1-nyc-1a 3h +cluster-7xw5g-master-0 Running m6i.xlarge us-east-1 us-east-1a 3h4m +cluster-7xw5g-master-1 Running m6i.xlarge us-east-1 us-east-1b 3h4m +cluster-7xw5g-master-2 Running m6i.xlarge us-east-1 us-east-1c 3h4m +cluster-7xw5g-worker-us-east-1a-rtp45 Running m6i.xlarge us-east-1 us-east-1a 3h +cluster-7xw5g-worker-us-east-1b-glm7c Running m6i.xlarge us-east-1 us-east-1b 3h +cluster-7xw5g-worker-us-east-1c-qfvz4 Running m6i.xlarge us-east-1 us-east-1c 3h +---- + +. To check nodes with edge roles, enter the following command: ++ +[source,terminal] +---- +$ oc get nodes -l node-role.kubernetes.io/edge +---- ++ +.Example output +[source,terminal] +---- +NAME STATUS ROLES AGE VERSION +ip-10-0-207-188.ec2.internal Ready edge,worker 172m v1.25.2+d2e245f +---- \ No newline at end of file diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index f9dee8b94a69..d2b954db75a5 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -1,7 +1,7 @@ :_content-type: CONCEPT [id="machines-edge-machine-pool_{context}"] -= The edge compute pool += The edge compute pool for AWS Local Zones {product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the type and size limitations of resources like EC2 and EBS on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. From 0157b14d94384d4ab523b9e1f71b8f1e622a04d2 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Fri, 28 Apr 2023 14:10:19 -0400 Subject: [PATCH 35/42] Remove errant markup from GH suggestion --- modules/installation-creating-aws-subnet-localzone.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index 928a54bae6d8..1b2d2078c2ec 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -56,7 +56,6 @@ requires: for the VPC. <2> Specify the Route Table ID, which is the value of the `PublicRouteTableId` in the CloudFormation stack for the VPC. -```suggestion <3> Specify the AWS Local Zone name, which is the value of the `ZoneName` field in the `AvailabilityZones` object that you retrieve in the section "Opting into AWS Local Zones". <4> Specify a CIDR block that is used to create the Local Zone subnet. This block must be part of the VPC CIDR block `VpcCidr`. From 903d2869507df68186de7437d322a32ee452173a Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Fri, 28 Apr 2023 14:18:57 -0400 Subject: [PATCH 36/42] Nits --- modules/edge-machine-pools-aws-local-zones.adoc | 1 - modules/installation-aws-add-local-zone-locations.adoc | 3 +-- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index 267b45346c64..dd31113ad9e6 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -10,7 +10,6 @@ When deploying a cluster that uses Local Zones: * Latency between applications and end users are 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. -+ [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. See link:https://docs.aws.amazon.com/local-zones/latest/ug/how-local-zones-work.html[How Local Zones work] in the AWS documentation. diff --git a/modules/installation-aws-add-local-zone-locations.adoc b/modules/installation-aws-add-local-zone-locations.adoc index a020e9d45880..691e858b509c 100644 --- a/modules/installation-aws-add-local-zone-locations.adoc +++ b/modules/installation-aws-add-local-zone-locations.adoc @@ -23,8 +23,7 @@ $ export CLUSTER_REGION="" <1> ---- <1> For ``, 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: +. List the zones that are available in your region by running the following command: + [source,terminal] ---- From ea6b7c574a76ea7011048d7c637b4695072fe791 Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Fri, 28 Apr 2023 15:22:30 -0400 Subject: [PATCH 37/42] Apply suggestions from code review Co-authored-by: Marco Braga --- modules/edge-machine-pools-aws-local-zones.adoc | 2 +- modules/machine-edge-pool-review-nodes.adoc | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index dd31113ad9e6..3b367bf287b5 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -8,7 +8,7 @@ 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 are 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. +* 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] ==== diff --git a/modules/machine-edge-pool-review-nodes.adoc b/modules/machine-edge-pool-review-nodes.adoc index df63fedc5816..b81583809f3e 100644 --- a/modules/machine-edge-pool-review-nodes.adoc +++ b/modules/machine-edge-pool-review-nodes.adoc @@ -9,17 +9,17 @@ After your install a cluster that uses AWS Local Zones, check the status of the + [source,terminal] ---- -$ oc get machineset -n openshift-machine-api --show-labels +$ oc get machineset -n openshift-machine-api ---- + .Example output [source,terminal] ---- -NAME DESIRED CURRENT READY AVAILABLE AGE LABELS -cluster-7xw5g-edge-us-east-1-nyc-1a 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g -cluster-7xw5g-worker-us-east-1a 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g -cluster-7xw5g-worker-us-east-1b 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g -cluster-7xw5g-worker-us-east-1c 1 1 1 1 3h4m machine.openshift.io/cluster-api-cluster=cluster-7xw5g +NAME DESIRED CURRENT READY AVAILABLE AGE +cluster-7xw5g-edge-us-east-1-nyc-1a 1 1 1 1 3h4m +cluster-7xw5g-worker-us-east-1a 1 1 1 1 3h4m +cluster-7xw5g-worker-us-east-1b 1 1 1 1 3h4m +cluster-7xw5g-worker-us-east-1c 1 1 1 1 3h4m ---- . To check the machines that were created from the machine sets, enter the following command: From 0e0c8de8fcee56817ba3f0b69873008691f6885f Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Mon, 8 May 2023 10:24:17 -0400 Subject: [PATCH 38/42] Apply some suggestions from code review Co-authored-by: Yunfei Jiang <61686698+yunjiang29@users.noreply.github.com> --- modules/installation-creating-aws-subnet-localzone.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index 1b2d2078c2ec..570ce427bf22 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -43,8 +43,8 @@ requires: "ParameterValue": "" <2> }, { - "ParameterKey": "LocalZoneName", - "ParameterValue": "" <3> + "ParameterKey": "ZoneName", + "ParameterValue": "" <3> }, { "ParameterKey": "PublicSubnetCidr", From c6042fe0d0e4c4812b3d150224b1d8bf276aa61f Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Mon, 8 May 2023 11:16:32 -0400 Subject: [PATCH 39/42] Gerund form for procedure --- modules/install-creating-install-config-aws-local-zones.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 98dd024ed889..656007201885 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -1,6 +1,6 @@ :_content-type: PROCEDURE [id="install-creating-install-config-aws-local-zones_{context}"] -= Modify an installation configuration file to use AWS Local Zones subnets += Modifying an installation configuration file to use AWS Local Zones subnets Modify an `install-config.yaml` file to include AWS Local Zones subnets. From 1d32964915c6bb41a9998fed4d112c8c6dd79713 Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Tue, 9 May 2023 10:59:16 -0400 Subject: [PATCH 40/42] Update param key and val block Co-authored-by: Yunfei Jiang <61686698+yunjiang29@users.noreply.github.com> --- modules/installation-creating-aws-subnet-localzone.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/installation-creating-aws-subnet-localzone.adoc b/modules/installation-creating-aws-subnet-localzone.adoc index 570ce427bf22..9546ed8e3d8d 100644 --- a/modules/installation-creating-aws-subnet-localzone.adoc +++ b/modules/installation-creating-aws-subnet-localzone.adoc @@ -46,6 +46,10 @@ requires: "ParameterKey": "ZoneName", "ParameterValue": "" <3> }, + { + "ParameterKey": "SubnetName", + "ParameterValue": "" + }, { "ParameterKey": "PublicSubnetCidr", "ParameterValue": "10.0.192.0/20" <4> From 1859354c709c4bb9162dd6e2963bc342b63f3d0b Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Thu, 11 May 2023 15:21:28 -0400 Subject: [PATCH 41/42] Add module use comment --- modules/edge-machine-pools-aws-local-zones.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index 3b367bf287b5..b8984ba9540b 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -1,3 +1,6 @@ +// 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 From f42d1a2d00ec944448e203d3be85cb62e0ef79d8 Mon Sep 17 00:00:00 2001 From: Max Bridges <50179998+maxwelldb@users.noreply.github.com> Date: Thu, 11 May 2023 15:33:07 -0400 Subject: [PATCH 42/42] Apply suggestions from peer review --- modules/edge-machine-pools-aws-local-zones.adoc | 8 ++++---- ...nstall-creating-install-config-aws-local-zones.adoc | 3 +++ modules/machine-edge-pool-review-nodes.adoc | 10 ++++++---- modules/machines-edge-machine-pool.adoc | 6 ++++-- 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/modules/edge-machine-pools-aws-local-zones.adoc b/modules/edge-machine-pools-aws-local-zones.adoc index b8984ba9540b..302d29b2b059 100644 --- a/modules/edge-machine-pools-aws-local-zones.adoc +++ b/modules/edge-machine-pools-aws-local-zones.adoc @@ -9,17 +9,17 @@ 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 are 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. +* 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. See link:https://docs.aws.amazon.com/local-zones/latest/ug/how-local-zones-work.html[How Local Zones work] in the AWS documentation. +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 could provide additional features, like IPsec, that also must be decreased the MTU. Check the documentation for additional information. +The network plugin can provide additional features, like IPsec, that also must be decreased the MTU. For additional information, see the documentation. ==== diff --git a/modules/install-creating-install-config-aws-local-zones.adoc b/modules/install-creating-install-config-aws-local-zones.adoc index 656007201885..4ea327ea350c 100644 --- a/modules/install-creating-install-config-aws-local-zones.adoc +++ b/modules/install-creating-install-config-aws-local-zones.adoc @@ -1,3 +1,6 @@ +// 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 diff --git a/modules/machine-edge-pool-review-nodes.adoc b/modules/machine-edge-pool-review-nodes.adoc index b81583809f3e..de108e5aaa10 100644 --- a/modules/machine-edge-pool-review-nodes.adoc +++ b/modules/machine-edge-pool-review-nodes.adoc @@ -1,11 +1,13 @@ +// Module included in the following assemblies +// * installing/installing_aws/installing-aws-localzone.adoc :_content-type: PROCEDURE [id="machine-edge-pool-review-nodes_{context}"] = Verifying nodes that were created with edge compute pool -After your install a cluster that uses AWS Local Zones, check the status of the machine that was created by the machine set manifests created at install time. +After you install a cluster that uses AWS Local Zones, check the status of the machine that was created by the machine set manifests created at install time. -. To check the machine sets created from the subnet you added to the `install-config.yaml` file, enter the following command: +. To check the machine sets created from the subnet you added to the `install-config.yaml` file, run the following command: + [source,terminal] ---- @@ -22,7 +24,7 @@ cluster-7xw5g-worker-us-east-1b 1 1 1 1 3h cluster-7xw5g-worker-us-east-1c 1 1 1 1 3h4m ---- -. To check the machines that were created from the machine sets, enter the following command: +. To check the machines that were created from the machine sets, run the following command: + [source,terminal] ---- @@ -41,7 +43,7 @@ cluster-7xw5g-worker-us-east-1b-glm7c Running m6i.xlarge us-east-1 cluster-7xw5g-worker-us-east-1c-qfvz4 Running m6i.xlarge us-east-1 us-east-1c 3h ---- -. To check nodes with edge roles, enter the following command: +. To check nodes with edge roles, run the following command: + [source,terminal] ---- diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc index d2b954db75a5..5054d3529c72 100644 --- a/modules/machines-edge-machine-pool.adoc +++ b/modules/machines-edge-machine-pool.adoc @@ -1,3 +1,5 @@ +// Module included in the following assemblies +// * installing/installing_aws/installing-aws-localzone.adoc :_content-type: CONCEPT [id="machines-edge-machine-pool_{context}"] @@ -5,7 +7,7 @@ {product-title} 4.12 introduced a new compute pool, _edge_, that is designed for use in remote zones. The edge compute pool configuration is common between AWS Local Zone locations. However, due to the type and size limitations of resources like EC2 and EBS on Local Zone resources, the default instance type that is created can vary from the traditional worker pool. -The default Elastic Block Store (EBS) for Local Zone locations is `gp2`, which differs from the regular worker pool. The instance type used for each Local Zone on edge compute pool also may differ from worker pools, depending on the instance offerings on the zone. +The default Elastic Block Store (EBS) for Local Zone locations is `gp2`, which differs from the regular worker pool. The instance type used for each Local Zone on edge compute pool also might differ from worker pools, depending on the instance offerings on the zone. The edge compute pool creates new labels that developers can use to deploy applications onto AWS Local Zone nodes. The new labels are: @@ -69,7 +71,7 @@ pullSecret: '{"auths": ...}' sshKey: ssh-ed25519 AAAA... ---- -Instance types differ between locations. Check the AWS documentation to verify availability in the Local Zone in which the cluster will run. +Instance types differ between locations. To verify availability in the Local Zone in which the cluster will run, see the AWS documentation. .Configuration that uses an edge pool with a custom EBS type [source,yaml]