From 12c0eda8c95394bab453b2980328d5c815818459 Mon Sep 17 00:00:00 2001 From: Jim Dial <48702557+jimdial-aws@users.noreply.github.com> Date: Thu, 6 Apr 2023 12:47:22 -0400 Subject: [PATCH] NLB documentation edits (#3129) --- docs/guide/service/nlb.md | 78 +++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/guide/service/nlb.md b/docs/guide/service/nlb.md index a47bdd9f4..7be72736b 100644 --- a/docs/guide/service/nlb.md +++ b/docs/guide/service/nlb.md @@ -1,54 +1,54 @@ # Network Load Balancer -AWS Load Balancer Controller supports reconciliation for Kubernetes Services resources of type `LoadBalancer` by Network Load Balancer (NLB) with `instance` or `ip` target type. +The AWS Load Balancer Controller (LBC) supports reconciliation for Kubernetes Service resources of type `LoadBalancer` by provisioning an AWS Network Load Balancer (NLB) with an `instance` or `ip` [target type](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#target-type). -!!! info "secure by default" - Since [:octicons-tag-24: v2.2.0](https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/tag/v2.2.0) release, the AWS Load balancer controller provisions an `internal` NLB by default. +!!! info "Secure by default" + Since the [:octicons-tag-24: v2.2.0](https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/tag/v2.2.0) release, the LBC provisions an `internal` NLB by default. - To create an `internet-facing` NLB, following annotation is required on your service: + To create an `internet-facing` NLB, the following annotation is required on your service: ```yaml service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing ``` !!! tip "" - For backwards compatibility, if the [`service.beta.kubernetes.io/aws-load-balancer-scheme`](./annotations.md#lb-scheme) annotation is absent, existing NLB's scheme will remain unchanged. + For backwards compatibility, if the [`service.beta.kubernetes.io/aws-load-balancer-scheme`](./annotations.md#lb-scheme) annotation is absent, an existing NLB's scheme remains unchanged. ## Prerequisites -* AWS Load Balancer Controller >= v2.2.0 -* For Kubernetes Services resources of type `LoadBalancer`: +* LBC >= v2.2.0 +* For Kubernetes Service resources of type `LoadBalancer`: * Kubernetes >= v1.20 or * Kubernetes >= v1.19.10 for 1.19 or * Kubernetes >= v1.18.18 for 1.18 or * EKS >= v1.16 -* For Kubernetes Services resources of type `NodePort`: +* For Kubernetes Service resources of type `NodePort`: * Kubernetes >= v1.16 * For `ip` target type: - * Pods have native AWS VPC networking configured, see [Amazon VPC CNI plugin](https://github.com/aws/amazon-vpc-cni-k8s) + * Pods have native AWS VPC networking configured. For more information, see the [Amazon VPC CNI plugin](https://github.com/aws/amazon-vpc-cni-k8s#readme) documentation. ## Configuration -By default, Kubernetes Service resources of type `LoadBalancer` gets reconciled by the Kubernetes controller built into the CloudProvider component of the kube-controller-manager or the cloud-controller-manager(a.k.a. the in-tree controller). +By default, Kubernetes Service resources of type `LoadBalancer` get reconciled by the Kubernetes controller built into the `CloudProvider` component of the `kube-controller-manager` or the `cloud-controller-manager`(also known as the in-tree controller). -In order to let AWS Load Balancer Controller manage the reconciliation for Kubernetes Services resources of type `LoadBalancer`, you need to offload the reconciliation from in-tree controller to AWS Load Balancer Controller explicitly. +In order for the LBC to manage the reconciliation of Kubernetes Service resources of type `LoadBalancer`, you need to offload the reconciliation from the in-tree controller to the LBC, explicitly. === "With LoadBalancerClass" - AWS Load Balancer Controller supports `LoadBalancerClass` feature since [:octicons-tag-24: v2.4.0](https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/tag/v2.4.0) release for Kubernetes v1.22+ clusters. + The LBC supports the `LoadBalancerClass` feature since the [:octicons-tag-24: v2.4.0](https://github.com/kubernetes-sigs/aws-load-balancer-controller/releases/tag/v2.4.0) release for Kubernetes v1.22+ clusters. - `LoadBalancerClass` feature provides a CloudProvider agnostic way of offloading the reconciliation for Kubernetes Services resources of type `LoadBalancer` to an external controller. + The `LoadBalancerClass` feature provides a `CloudProvider` agnostic way of offloading the reconciliation for Kubernetes Service resources of type `LoadBalancer` to an external controller. - When you specify the `spec.loadBalancerClass` to be `service.k8s.aws/nlb` on a Kubernetes Service resource of type `LoadBalancer`, the AWS Load Balancer Controller takes charge of reconciliation by provision an NLB. + When you specify the `spec.loadBalancerClass` to be `service.k8s.aws/nlb` on a Kubernetes Service resource of type `LoadBalancer`, the LBC takes charge of reconciliation by provisioning an NLB. !!! warning - - If you modify a Service resource with matching `spec.loadBalancerClass` by changing its `type` from `LoadBalancer` to anything else, the controller will cleanup provioned NLB for that Service. + - If you modify a Service resource with matching `spec.loadBalancerClass` by changing its `type` from `LoadBalancer` to anything else, the controller will cleanup the provioned NLB for that Service. - - If the `spec.loadBalancerClass` is set to a loadBalancerClass that is not recognized by this controller, it will ignore the Service resource regardless of the `service.beta.kubernetes.io/aws-load-balancer-type` annotation. + - If the `spec.loadBalancerClass` is set to a `loadBalancerClass` that isn't recognized by the LBC, it ignores the Service resource, regardless of the `service.beta.kubernetes.io/aws-load-balancer-type` annotation. !!! tip - - By default, the NLB will use `instance` target-type, you can customize it via the [`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type` annotation](./annotations.md#nlb-target-type) + - By default, the NLB uses the `instance` target type. You can customize it using the [`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type` annotation](./annotations.md#nlb-target-type). - - This controller uses `service.k8s.aws/nlb` as the default `LoadBalancerClass`, you can customize it to a different value via the controller flag `--load-balancer-class`. + - The LBC uses `service.k8s.aws/nlb` as the default `LoadBalancerClass`. You can customize it to a different value using the controller flag `--load-balancer-class`. !!! example "Example: instance mode" ```yaml hl_lines="6 15" @@ -89,17 +89,17 @@ In order to let AWS Load Balancer Controller manage the reconciliation for Kuber ``` === "With `service.beta.kubernetes.io/aws-load-balancer-type` annotation" - The AWS in-tree controller supports an AWS specific way of offloading the reconciliation for Kubernetes Services resources of type `LoadBalancer` to an external controller. + The AWS in-tree controller supports an AWS specific way of offloading the reconciliation for Kubernetes Service resources of type `LoadBalancer` to an external controller. - When you specify the [`service.beta.kubernetes.io/aws-load-balancer-type` annotation](./annotations.md#lb-type) to be `external` on a Kubernetes Service resource of type `LoadBalancer`, the in-tree controller will ignore the Service resource. In addition, If you specify the [`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type` annotation](./annotations.md#nlb-target-type) on the Service resource, the AWS Load Balancer Controller takes charge of reconciliation by provision an NLB. + When you specify the [`service.beta.kubernetes.io/aws-load-balancer-type` annotation](./annotations.md#lb-type) to be `external` on a Kubernetes Service resource of type `LoadBalancer`, the in-tree controller ignores the Service resource. In addition, if you specify the [`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type` annotation](./annotations.md#nlb-target-type) on the Service resource, the LBC takes charge of reconciliation by provisioning an NLB. !!! warning - - It's not recommended to modify or add the `service.beta.kubernetes.io/aws-load-balancer-type` annotation on an existing Service resource. Instead, delete the existing Service resource and recreate a new one if a change is desired. + - It's not recommended to modify or add the `service.beta.kubernetes.io/aws-load-balancer-type` annotation on an existing Service resource. If a change is desired, delete the existing Service resource and create a new one instead of modifying an existing Service. - - If you modify this annotation on a existing Service resource, you might end up with leaked AWS Load Balancer resources. + - If you modify this annotation on an existing Service resource, you might end up with leaked LBC resources. !!! note "backwards compatibility for `nlb-ip` type" - For backwards compatibility, both in-tree and AWS Load Balancer controller supports `nlb-ip` as value of `service.beta.kubernetes.io/aws-load-balancer-type` annotation. The controllers treats it as if you specified both annotation below: + For backwards compatibility, both the in-tree and LBC controller supports `nlb-ip` as a value for the `service.beta.kubernetes.io/aws-load-balancer-type` annotation. The controllers treats it as if you specified both of the following annotations: ``` service.beta.kubernetes.io/aws-load-balancer-type: external service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip @@ -144,54 +144,54 @@ In order to let AWS Load Balancer Controller manage the reconciliation for Kuber ``` ## Protocols -Controller supports both TCP and UDP protocols. Controller also configures TLS termination on NLB if you configure service with certificate annotation. +The LBC supports both TCP and UDP protocols. The controller also configures TLS termination on your NLB if you configure the Service with a certificate annotation. -In case of TCP, NLB with IP targets does not pass the client source IP address unless specifically configured via target group attributes. Your application pods might not see the actual client IP address even if NLB passes it along, for example instance mode with `externalTrafficPolicy` set to `Cluster`. -In such cases, you can configure [NLB proxy protocl v2](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol) via [annotation](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-protocol-support-on-aws) if you need visibility into +In the case of TCP, an NLB with IP targets doesn't pass the client source IP address, unless you specifically configure it to using target group attributes. Your application pods might not see the actual client IP address, even if the NLB passes it along. For example, if you're using instance mode with `externalTrafficPolicy` set to `Cluster`. +In such cases, you can configure [NLB proxy protocol v2](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol) using an [annotation](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-protocol-support-on-aws) if you need visibility into the client source IP address on your application pods. -To enable proxy protocol v2, apply the following annotation to your service: +To enable proxy protocol v2, apply the following annotation to your Service: ```yaml service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*" ``` !!!note "" - If you enable proxy protocol v2, NLB health check with HTTP/HTTPS works only if the health check port supports proxy protocol v2. Due to this behavior, you should not configure proxy protocol v2 with NLB instance mode and `externalTrafficPolicy` set to `Local`. + If you enable proxy protocol v2, NLB health checks with HTTP/HTTPS only work if the health check port supports proxy protocol v2. Due to this behavior, you shouldn't configure proxy protocol v2 with NLB instance mode and `externalTrafficPolicy` set to `Local`. ## Subnet tagging requirements -See [Subnet Discovery](../../deploy/subnet_discovery.md) for details on configuring ELB for public or private placement. +See [Subnet Discovery](../../deploy/subnet_discovery.md) for details on configuring Elastic Load Balancing for public or private placement. ## Security group -AWS currently does not support attaching security groups to NLB. To allow inbound traffic from NLB, the controller automatically adds inbound rules to the worker node security groups by default. +AWS doesn't support attaching security groups to NLBs. To allow inbound traffic from an NLB, the controller automatically adds inbound rules to the worker node security groups, by default. !!! tip "disable worker node security group rule management" - You can disable the worker node security group rule management via [annotation](./annotations.md#manage-backend-sg-rules). + You can disable the worker node security group rule management using an [annotation](./annotations.md#manage-backend-sg-rules). ### Worker node security groups selection -The controller automatically selects the worker node security groups that will be modified to allow inbound traffic with following rules: +The controller automatically selects the worker node security groups that it modifies to allow inbound traffic using the following rules: -* for `instance` mode, the security group of the each backend worker node's primary ENI will be selected. -* for `ip` mode, the security group of each backend pod's ENI will be selected. +* For `instance` mode, the security group of each backend worker node's primary elastic network interface (ENI) is selected. +* For `ip` mode, the security group of each backend pod's ENI is selected. -!!! important "multiple security groups on an ENI" +!!! important "Multiple security groups on an ENI" - if there are multiple security groups attached on an ENI, the controller expects only one security group tagged with following tags: + If there are multiple security groups attached to an ENI, the controller expects only one security group tagged with following tags: | Key | Value | | --------------------------------------- | ------------------- | | `kubernetes.io/cluster/${cluster-name}` | `owned` or `shared` | - `${cluster-name}` is the name of the kubernetes cluster + `${cluster-name}` is the name of the Kubernetes cluster. ### Worker node security groups rules -=== "when Client IP preservation enabled" +=== "When client IP preservation is enabled" | Rule | Protocol | Port(s) | IpRanges(s) | | -------------------- | ------------------------ | ------------------------------------------------------- | --------------------------------------------------- | | Client Traffic | `spec.ports[*].protocol` | `spec.ports[*].port` | [Traffic Source CIDRs](./annotations.md#lb-source-ranges) | | Health Check Traffic | TCP | [Health Check Ports](./annotations.md#healthcheck-port) | NLB Subnet CIDRs | -=== "when Client IP preservation disabled" +=== "When client IP preservation is disabled" | Rule | Protocol | Port(s) | IpRange(s) | | -------------------- | ------------------------ | ------------------------------------------------------- | ------------ |