revise install guide (#2704)

* revise install guide

* fixup

* fixup

Author: geoffcline

docs/deploy/installation.md

@@ -1,72 +1,74 @@
 # Load Balancer Controller Installation
 
-## Kubernetes version requirements
+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 LBC is supported by AWS. Some clusters may using legeacy "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.
+
+## 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+
 
-!!!warning "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.
+## Deployment Considerations
 
-!!!note "Security updates"
-    The controller doesn't receive security updates automatically. You need to manually upgrade to a newer version when it becomes available.
+### Additional Requirements for non-EKS clusters:
 
-!!!note "non-EKS cluster"
-    You can run the controller on a non-EKS cluster, for example kops or vanilla k8s. Here are the things to consider -
+* 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.
 
-    - In lieu of IAM for service account, you will have to manually attach the IAM permissions to your worker nodes IAM roles
-    - 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.
+### 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.
 
-!!!note "security group configuration"
-    If you do not use `eksctl`, you need to ensure worker nodes security group permit access to TCP port 9443 from the kubernetes control plane for the webhook access.
+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>
+```
 
-## Using metadata server version 2 (IMDSv2)
-If you are using the IMDSv2 you must set the hop limit to 2 or higher in order to allow the AWS Load Balancer Controller to perform the metadata introspection. Otherwise you have to manually specify the AWS region and the VPC via the controller flags `--aws-region` and `--aws-vpc-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`.
 
+## Configure IAM
 
-!!!tip
-    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>
-    ```
+The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB APIs via IAM permissions.
 
-## 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.
 
-#### Setup IAM role for service accounts
-The controller runs on the worker nodes, so it needs access to the AWS ALB/NLB resources via IAM permissions.
-The IAM permissions can either be setup via IAM roles for ServiceAccount or can be attached directly to the worker node IAM roles.
+### Option A: IAM Roles for Service Accounts (IRSA)
 
-!!!warning "Permissions with the least privileges"
-    The reference IAM policies contain the following permissive configuration:
-    ```
-    {
-        "Effect": "Allow",
-        "Action": [
-            "ec2:AuthorizeSecurityGroupIngress",
-            "ec2:RevokeSecurityGroupIngress"
-        ],
-        "Resource": "*"
-    },
-    ```
-    We recommend to further scope down this configuration based on the VPC ID. Replace REGION, ACCOUNT and VPC-ID with appropriate values
-    and add it to the above IAM permissions.
-    ```
-        "Condition": {
-           "ArnEquals": {
-                "ec2:Vpc": "arn:aws:ec2:REGION:ACCOUNT:vpc/VPC-ID"
-            }
+The reference IAM policies contain the following permissive configuration:
+```
+{
+    "Effect": "Allow",
+    "Action": [
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:RevokeSecurityGroupIngress"
+    ],
+    "Resource": "*"
+},
+```
+
+We recommend to further scope down this configuration based on the VPC ID or cluster name resource tag. 
+
+Example condition for VPC ID:
+```
+    "Condition": {
+        "ArnEquals": {
+            "ec2:Vpc": "arn:aws:ec2:<REGION>:<ACCOUNT-ID>:vpc/<VPC-ID>"
         }
-    ```
-    OR restrict access to the security groups tagged for the particular k8s cluster. Replace CLUSTER-NAME with the name of your k8s cluster and add it to the above IAM permissions.
-    ```
-        "Condition": {
-            "Null": {
-                "aws:ResourceTag/kubernetes.io/cluster/CLUSTER-NAME": "false"
-            }
+    }
+```
+
+Example condition for cluster name resource tag:
+```
+    "Condition": {
+        "Null": {
+            "aws:ResourceTag/kubernetes.io/cluster/<CLUSTER-NAME>": "false"
         }
-    ```
+    }
+```
 
 1. Create IAM OIDC provider
     ```
@@ -100,13 +102,14 @@ The IAM permissions can either be setup via IAM roles for ServiceAccount or can
     --region <region-code> \
     --approve
     ```
-#### Setup IAM manually
+    
+### Option B: Attach IAM Policies to Nodes
 If not setting up IAM for ServiceAccount, apply the IAM policies from the following URL at minimum.
 ```
 curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.2/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:
+*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:*
 
 ```
 {
@@ -130,13 +133,23 @@ curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-lo
     "Version": "2012-10-17"
 }
 ```
+
+
+
+## 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 9943 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
 
-!!!note "Use Fargate"
-    If you want to run the controller on Fargate, use Helm chart since it does not depend on the cert-manager.
+We recommend using the Helm chart. This supports Fargate and facilitates updating the controller.
 
 === "Via Helm"
 
+    If you want to run the controller on Fargate, use the Helm chart since it does not 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.
 
@@ -147,21 +160,21 @@ curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-lo
     helm repo add eks https://aws.github.io/eks-charts
     ```
     1. Install the TargetGroupBinding CRDs if upgrading the chart via `helm upgrade`.
+
     ```
     kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller//crds?ref=master"
     ```
 
         !!!tip
             The `helm install` command automatically applies the CRDs, but `helm upgrade` doesn't.
 
-        !!!tip
-            Only run one of the two following `helm install` commands depending on whether or not your cluster uses IAM roles for service accounts.
 
-    1. Install the helm chart if using IAM roles for service accounts. **NOTE** you need to specify both of the chart values `serviceAccount.create=false` and `serviceAccount.name=aws-load-balancer-controller`
+    Helm command for clusters with IRSA: 
     ```
     helm install aws-load-balancer-controller eks/aws-load-balancer-controller -n kube-system --set clusterName=<cluster-name> --set serviceAccount.create=false --set serviceAccount.name=aws-load-balancer-controller
     ```
-    1. Install the helm chart if **not** using IAM roles for service accounts
+
+    Helm command for clusters not using IRSA:
     ```
     helm install aws-load-balancer-controller eks/aws-load-balancer-controller -n kube-system --set clusterName=<cluster-name>
     ```
@@ -204,3 +217,9 @@ curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-lo
     ```
     kubectl apply -f v2_4_1_full.yaml
     ```
+
+## Create Update Strategy
+
+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.