cherry pick #3121 and update the version to 2.4.7 (#3122)

Co-authored-by: Jim Dial <48702557+jimdial-aws@users.noreply.github.com>
kubernetes-sigs · Mar 24, 2023 · beb89ec · beb89ec
1 parent 2ba14d1
commit beb89ec
Showing 1 changed file with 54 additions and 46 deletions.
diff --git a/docs/deploy/installation.md b/docs/deploy/installation.md
@@ -1,42 +1,42 @@
-# Load Balancer Controller Installation
+# AWS Load Balancer Controller installation
 
-The Load Balancer controller (LBC) provisions AWS Network Load Balancer (NLB) and Application Load Balancer (ALB) resources. The LBC watches for new service or ingress kubernetes resources, and configures AWS resources.
+The AWS Load Balancer controller (LBC) provisions AWS Network Load Balancer (NLB) and Application Load Balancer (ALB) resources. The LBC watches for new `service` or `ingress` Kubernetes resources and configures AWS resources.
 
-The LBC is supported by AWS. Some clusters may using legacy "in-tree" functionality to provision AWS load balancers. The AWS Load Balancer Controller should be installed instead. 
+The LBC is supported by AWS. Some clusters may be using the legacy "in-tree" functionality to provision AWS load balancers. The AWS Load Balancer Controller should be installed instead. 
 
 !!!question "Existing AWS ALB Ingress Controller users"
-    AWS ALB Ingress controller must be uninstalled before installing AWS Load Balancer Controller.
-    Please follow our [migration guide](upgrade/migrate_v1_v2.md) to do migration.
+    The AWS ALB Ingress controller must be uninstalled before installing the AWS Load Balancer Controller.
+    Please follow our [migration guide](upgrade/migrate_v1_v2.md) to do a migration.
 
-## Supported Kubernetes Versions 
+## Supported Kubernetes versions 
 * AWS Load Balancer Controller v2.0.0~v2.1.3 requires Kubernetes 1.15+
 * AWS Load Balancer Controller v2.2.0~v2.3.1 requires Kubernetes 1.16-1.21
 * AWS Load Balancer Controller v2.4.0+ requires Kubernetes 1.19+
 
-## Deployment Considerations
+## Deployment considerations
 
-### Additional Requirements for non-EKS clusters:
+### Additional requirements for non-EKS clusters:
 
 * Ensure subnets are tagged appropriately for auto-discovery to work
-* For IP targets, pods must have IPs from the VPC subnets. You can configure `amazon-vpc-cni-k8s` plugin for this purpose.
+* For IP targets, pods must have IPs from the VPC subnets. You can configure the [`amazon-vpc-cni-k8s`](https://github.com/aws/amazon-vpc-cni-k8s#readme) plugin for this purpose.
 
-### Using metadata server version 2 (IMDSv2)
-If you are using the [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) you must set the hop limit to 2 or higher in order to allow the AWS Load Balancer Controller to perform the metadata introspection.
+### Using the Amazon EC2 instance metadata server version 2 (IMDSv2)
+If you are using the [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html), set the hop limit to 2 or higher in order to allow the LBC to perform the metadata introspection.
 
 You can set the IMDSv2 hop limit as follows:
 ```
 aws ec2 modify-instance-metadata-options --http-put-response-hop-limit 2 --region <region> --instance-id <instance-id>
 ```
 
-Instead of depending on IMDSv2, you alternatively may specify the AWS region and the VPC via the controller flags `--aws-region` and `--aws-vpc-id`.
+Instead of depending on IMDSv2, you can specify the AWS Region and the VPC via the controller flags `--aws-region` and `--aws-vpc-id`.
 
 ## Configure IAM
 
-The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB APIs via IAM permissions.
+The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB APIs with IAM permissions.
 
-The IAM permissions can either be setup via [IAM roles for ServiceAccount (IRSA)](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/setting-up-enable-IAM.html) or can be attached directly to the worker node IAM roles. If you are using kops or vanilla k8s, polices must be manually attached to node instances.
+The IAM permissions can either be setup using [IAM roles for service accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) or can be attached directly to the worker node IAM roles. This is the recommended method if you're using Amazon EKS. If you're using kOps or self-hosted Kubernetes, you must manually attach polices to node instances.
 
-### Option A: IAM Roles for Service Accounts (IRSA)
+### Option A: IAM roles for service accounts (IRSA)
 
 The reference IAM policies contain the following permissive configuration:
 ```
@@ -50,7 +50,7 @@ The reference IAM policies contain the following permissive configuration:
 },
 ```
 
-We recommend to further scope down this configuration based on the VPC ID or cluster name resource tag. 
+We recommend further scoping down this configuration based on the VPC ID or cluster name resource tag. 
 
 Example condition for VPC ID:
 ```
@@ -70,28 +70,37 @@ Example condition for cluster name resource tag:
     }
 ```
 
-1. Create IAM OIDC provider
+1. Create an IAM OIDC provider. You can skip this step if you already have one for your cluster.
     ```
     eksctl utils associate-iam-oidc-provider \
         --region <region-code> \
         --cluster <your-cluster-name> \
         --approve
     ```
 
-1. Download IAM policy for the AWS Load Balancer Controller
+2. Download an IAM policy for the LBC using one of the following commands:<p>
+    If your cluster is in a US Gov Cloud region:
     ```
-    curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
+    curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy_us-gov.json
+    ```
+    If your cluster is in a China region:
+    ```
+    curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy_cn.json 
+    ```
+    If your cluster is in any other region:
+    ```
+    curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json  
     ```
 
-1. Create an IAM policy called AWSLoadBalancerControllerIAMPolicy
+3. Create an IAM policy named `AWSLoadBalancerControllerIAMPolicy`. If you downloaded a different policy, replace `iam-policy` with the name of the policy that you downloaded. 
     ```
     aws iam create-policy \
         --policy-name AWSLoadBalancerControllerIAMPolicy \
         --policy-document file://iam-policy.json
     ```
-    Take note of the policy ARN that is returned
+    Take note of the policy ARN that's returned.
 
-1. Create a IAM role and ServiceAccount for the AWS Load Balancer controller, use the ARN from the step above
+4. Create an IAM role and Kubernetes `ServiceAccount` for the LBC. Use the ARN from the previous step.
     ```
     eksctl create iamserviceaccount \
     --cluster=<cluster-name> \
@@ -103,13 +112,13 @@ Example condition for cluster name resource tag:
     --approve
     ```
     
-### Option B: Attach IAM Policies to Nodes
-If not setting up IAM for ServiceAccount, apply the IAM policies from the following URL at minimum.
+### Option B: Attach IAM policies to nodes
+If you're not setting up IAM roles for service accounts, apply the IAM policies from the following URL at a minimum.
 ```
 curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.7/docs/install/iam_policy.json
 ```
 
-*IAM permission subset for those who use *TargetGroupBinding* only and don't plan to use the AWS Load Balancer Controller to manage security group rules:*
+The following IAM permissions subset is for those using `TargetGroupBinding` only and don't plan to use the LBC to manage security group rules:
 
 ```
 {
@@ -134,32 +143,30 @@ curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-lo
 }
 ```
 
+## Network configuration
 
-
-## Network Configuration
-
-Review the [worker nodes security group](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) docs. The node security group must permit incoming traffic on TCP port 9443 from the kubernetes control plane. This is needed for webhook access. 
+Review the [worker nodes security group](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) docs. Your node security group must permit incoming traffic on TCP port 9443 from the Kubernetes control plane. This is needed for webhook access. 
 
 If you use [eksctl](https://eksctl.io/usage/vpc-networking/), this is the default configuration. 
 
-## Add Controller to Cluster
+## Add controller to cluster
 
-We recommend using the Helm chart. This supports Fargate and facilitates updating the controller.
+We recommend using the Helm chart to install the controller. The chart supports Fargate and facilitates updating the controller.
 
-=== "Via Helm"
+=== "Helm"
 
-    If you want to run the controller on Fargate, use the Helm chart since it does not depend on the cert-manager.
+    If you want to run the controller on Fargate, use the Helm chart, since it doesn't depend on the `cert-manager`.
 
-    ### Detailed Instructions
-    Follow the instructions in [aws-load-balancer-controller](https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller) helm chart.
+    ### Detailed instructions
+    Follow the instructions in the [aws-load-balancer-controller](https://github.com/aws/eks-charts/tree/master/stable/aws-load-balancer-controller) Helm chart.
 
     ### Summary
 
-    1. Add the EKS chart repo to helm
+    1. Add the EKS chart repo to Helm
     ```
     helm repo add eks https://aws.github.io/eks-charts
     ```
-    1. Install the TargetGroupBinding CRDs if upgrading the chart via `helm upgrade`.
+    2. If upgrading the chart via `helm upgrade`, install the `TargetGroupBinding` CRDs.
     ```
     kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller//crds?ref=master"
     ```
@@ -180,19 +187,20 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin
 
 
 
-=== "Via YAML manifests"
-    ### Install cert-manager
+=== "YAML manifests"<p>
+    
+    ### Install `cert-manager`
 
     ```
     kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.yaml
     ```
 
     ### Apply YAML
-    1. Download spec for load balancer controller.
+    1. Download the spec for the LBC.
     ```
     wget https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.4.7/v2_4_7_full.yaml
     ```
-    1. Edit the saved yaml file, go to the Deployment spec, and set the controller --cluster-name arg value to your EKS cluster name
+    2. Edit the saved yaml file, go to the Deployment spec, and set the controller `--cluster-name` arg value to your EKS cluster name
     ```
     apiVersion: apps/v1
     kind: Deployment
@@ -207,20 +215,20 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin
                     - args:
                         - --cluster-name=<INSERT_CLUSTER_NAME>
     ```
-    1. If you use IAM roles for service accounts, we recommend that you delete the ServiceAccount from the yaml spec. This will preserve the eksctl created iamserviceaccount if you delete the installation section from the yaml spec.
+    3. If you use IAM roles for service accounts, we recommend that you delete the `ServiceAccount` from the yaml spec. If you delete the installation section from the yaml spec, deleting the `ServiceAccount` preserves the `eksctl` created `iamserviceaccount`.
     ```
     apiVersion: v1
     kind: ServiceAccount
     ```
-    1. Apply the yaml file
+    4. Apply the yaml file
     ```
     kubectl apply -f v2_4_7_full.yaml
     ```
-    1. Optionally download the default ingressclass and ingressclass params
+    5. Optionally download the default ingressclass and ingressclass params
     ```
     wget https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/download/v2.4.7/v2_4_7_ingclass.yaml
     ```
-    1. Apply the ingressclass and params
+    6. Apply the ingressclass and params
     ```
     kubectl apply -f v2_4_7_ingclass.yaml
     ```
@@ -229,4 +237,4 @@ We recommend using the Helm chart. This supports Fargate and facilitates updatin
 
 The controller doesn't receive security updates automatically. You need to manually upgrade to a newer version when it becomes available.
 
-This can be done using [`helm upgrade`](https://helm.sh/docs/helm/helm_upgrade/) or another strategy to manage the controller deployment.
+You can upgrade using [`helm upgrade`](https://helm.sh/docs/helm/helm_upgrade/) or another strategy to manage the controller deployment.