doc updates for v2.4.0 (kubernetes-sigs#2506)

kishorj · Timothy-Dougherty · commit 3bed45f99526 · 2023-11-09T11:29:08.000+11:00
* doc updates for v2.4.0

* update external dns example
diff --git a/docs/deploy/configurations.md b/docs/deploy/configurations.md
@@ -93,6 +93,7 @@ Currently, you can set only 1 namespace to watch in this flag. See [this Kuberne
 |kubeconfig                             | string                          | in-cluster config | Path to the kubeconfig file containing authorization and API server information |
 |leader-election-id                     | string                          | aws-load-balancer-controller-leader | Name of the leader election ID to use for this controller |
 |leader-election-namespace              | string                          |                 | Name of the leader election ID to use for this controller |
+|load-balancer-class                    | string                          | service.k8s.aws/nlb| Name of the load balancer class specified in service `spec.loadBalancerClass` reconciled by this controller |
 |log-level                              | string                          | info            | Set the controller log level - info, debug |
 |metrics-bind-addr                      | string                          | :8080           | The address the metric endpoint binds to |
 |service-max-concurrent-reconciles      | int                             | 3               | Maximum number of concurrently running reconcile loops for service |
@@ -140,5 +141,6 @@ They are a set of kye=value pairs that describe AWS load balance controller feat
 
 |Features-gate Supported Key            | Type                            | Default Value   | Description |
 |---------------------------------------|---------------------------------|-----------------|-------------|
-|ListenerRulesTagging                   | string                          | true            | Enable or disable tagging AWS load balancer listeners and rules |
-|WeightedTargetGroups                   | string                          | true            | Enable or disable weighted target groups |
+| ListenerRulesTagging                  | string                          | true           | Enable or disable tagging AWS load balancer listeners and rules |
+| WeightedTargetGroups                  | string                          | true           | Enable or disable weighted target groups |
+| ServiceTypeLoadBalancerOnly           | string                          | false          | If enabled, controller will be limited to reconciling service of type `LoadBalancer`|
diff --git a/docs/deploy/installation.md b/docs/deploy/installation.md
@@ -19,6 +19,9 @@
     - 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.
 
+!!!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.
+
 ## 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`.
 
diff --git a/docs/examples/echo_server.md b/docs/examples/echo_server.md
@@ -86,9 +86,9 @@ In this walkthrough, you'll
 1.  Deploy all the echoserver resources (namespace, service, deployment)
 
     ```bash
-    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/echoservice/echoserver-namespace.yaml &&\
-    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/echoservice/echoserver-service.yaml &&\
-    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/echoservice/echoserver-deployment.yaml
+    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/examples/echoservice/echoserver-namespace.yaml &&\
+    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/examples/echoservice/echoserver-service.yaml &&\
+    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/examples/echoservice/echoserver-deployment.yaml
     ```
 
 1.  List all the resources to ensure they were created.
@@ -112,7 +112,7 @@ In this walkthrough, you'll
 1.  Download the echoserver ingress manifest locally.
 
     ```bash
-    wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/echoservice/echoserver-ingress.yaml
+    wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/examples/echoservice/echoserver-ingress.yaml
     ```
 
 1.  Configure the subnets, either by add annotation to the ingress or add tags to subnets. This step is optional in lieu of auto-discovery.
@@ -223,7 +223,7 @@ In this walkthrough, you'll
 1.  Download external-dns to manage Route 53.
 
     ```bash
-    wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/examples/external-dns.yaml
+    wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/examples/external-dns.yaml
     ```
 
 1.  Edit the `--domain-filter` flag to include your hosted zone(s)
@@ -294,7 +294,7 @@ In this walkthrough, you'll
 follow below steps if you want to use kube2iam to provide the AWS credentials
 
 1. configure the proper policy
-    The policy to be used can be fetched from https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.0.0/docs/install/iam_policy.json
+    The policy to be used can be fetched from https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/install/iam_policy.json
 
 1. configure the proper role and create the trust relationship
     You have to find which role is associated with your K8S nodes. Once you found take note of the full arn:
diff --git a/docs/examples/external-dns.yaml b/docs/examples/external-dns.yaml
@@ -3,7 +3,7 @@ kind: ServiceAccount
 metadata:
   name: external-dns
 ---
-apiVersion: rbac.authorization.k8s.io/v1beta1
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
   name: external-dns
@@ -24,7 +24,7 @@ rules:
   resources: ["endpoints"]
   verbs: ["get","watch","list"]
 ---
-apiVersion: rbac.authorization.k8s.io/v1beta1
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
   name: external-dns-viewer
diff --git a/docs/guide/service/annotations.md b/docs/guide/service/annotations.md
@@ -17,7 +17,7 @@
 |--------------------------------------------------------------------------------------------------|-------------------------|---------------------------|--------------------------------------------------------|
 | [service.beta.kubernetes.io/load-balancer-source-ranges](#lb-source-ranges)                      | stringList              |                           |                                                        |
 | [service.beta.kubernetes.io/aws-load-balancer-type](#lb-type)                                    | string                  |                           |                                                        |
-| [service.beta.kubernetes.io/aws-load-balancer-nlb-target-type](#nlb-target-type)                 | string                  |                           |                                                        |
+| [service.beta.kubernetes.io/aws-load-balancer-nlb-target-type](#nlb-target-type)                 | string                  |                           | default `instance` in case of LoadBalancerClass        |
 | [service.beta.kubernetes.io/aws-load-balancer-name](#load-balancer-name)                         | string                  |                           |                                                        |
 | [service.beta.kubernetes.io/aws-load-balancer-internal](#lb-internal)                            | boolean                 | false                     | deprecated, in favor of [aws-load-balancer-scheme](#lb-scheme)|
 | [service.beta.kubernetes.io/aws-load-balancer-scheme](#lb-scheme)                                | string                  | internal                  |                                                        |
@@ -83,9 +83,13 @@ Traffic Routing can be controlled with following annotations:
     - `instance` mode will route traffic to all EC2 instances within cluster on the [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport) opened for your service.
 
         !!!note ""
-            service must be of type `NodePort` or `LoadBalancer` for `instance` targets
+            - service must be of type `NodePort` or `LoadBalancer` for `instance` targets
+            - for k8s 1.22 and later if `spec.allocateLoadBalancerNodePorts` is set to `false`, `NodePort` must be allocated manually
 
-    - `ip` mode will route traffic directly to the pod IP.
+        !!!note "default value"
+            If you configure `spec.loadBalancerClass`, the controller defaults to `instance` target type
+
+      - `ip` mode will route traffic directly to the pod IP.
 
         !!!note ""
             network plugin must use native AWS VPC networking configuration for pod IP, for example [Amazon VPC CNI plugin](https://github.com/aws/amazon-vpc-cni-k8s).
diff --git a/docs/guide/service/nlb.md b/docs/guide/service/nlb.md
@@ -59,6 +59,8 @@ NLB IP mode is determined based on the `service.beta.kubernetes.io/aws-load-bala
 
 ### Instance mode
 Similar to the IP mode, the instance mode is based on the annotation `service.beta.kubernetes.io/aws-load-balancer-nlb-target-type` value `instance`. Here is a sample manifest snippet:
+!!!warning "NodePort allocation"
+    k8s version 1.22 and later support disabling NodePort allocation by setting the service field `spec.allocateLoadBalancerNodePorts` to `false`. If the NodePort is not allocated for a service port, the controller will fail to reconcile instance mode NLB.
 
 ```yaml
     metadata:
@@ -95,3 +97,10 @@ security groups, the controller expects only one security group tagged with the
 | `kubernetes.io/cluster/${cluster-name}` | `owned` or `shared`   |
 
 `${cluster-name}` is the name of the kubernetes cluster
+
+## Load Balancer Class
+The AWS Load Balancer Controller supports `LoadBalancerClass` starting v2.4.0 release on k8s 1.22 or later clusters. The LoadBalancerClass provides a cloudprovider agnostic way of offloading the load balancer reconciliation to an external controller. This controller uses the `service.k8s.aws/nlb` as the default class,
+you can configure it to a different value via the controller flag `--load-balancer-class`.
+
+When you specify the `spec.loadBalancerClass` on a service of type `LoadBalancer` during service creation, this controller creates an internal NLB with instance targets by default. If the LoadBalancerClass is not the configured for this controller, this controller ignores the service resource completely regardless of the annotation
+`service.beta.kubernetes.io/aws-load-balancer-type`. If you modify the service, with `spec.loadBalancerClass`, type from `LoadBalancer` to anything else, the controller will cleanup the NLB.
