Update nlb target type annotation

controllers/service/eventhandlers/service_events.go

@@ -65,8 +65,8 @@ func (h *enqueueRequestsForServiceEvent) isServiceSupported(service *corev1.Serv
 	}
 	var lbTargetType string
 	_ = h.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixTargetType, &lbTargetType, service.Annotations)
-	if lbType == svcpkg.LoadBalancerTypeExternal && (lbTargetType == svcpkg.LoadBalancerTargetTypeNLBIP ||
-		lbTargetType == svcpkg.LoadBalancerTargetTypeNLBInstance) {
+	if lbType == svcpkg.LoadBalancerTypeExternal && (lbTargetType == svcpkg.LoadBalancerTargetTypeIP ||
+		lbTargetType == svcpkg.LoadBalancerTargetTypeInstance) {
 		return true
 	}
 	return false

docs/guide/service/annotations.md

@@ -11,8 +11,11 @@
 ## Annotations
 | Name                                                                                             | Type                    | Default                   | Notes                                                  |
 |--------------------------------------------------------------------------------------------------|-------------------------|---------------------------|--------------------------------------------------------|
-| service.beta.kubernetes.io/aws-load-balancer-type                                                | string                  |                           |                                                        |
-| service.beta.kubernetes.io/aws-load-balancer-internal                                            | boolean                 | false                     |                                                        |
+| [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-name                                                | string                  |                           |                                                        |
+| [service.beta.kubernetes.io/aws-load-balancer-internal](#lb-internal)                            | boolean                 | false                     |                                                        |
 | [service.beta.kubernetes.io/aws-load-balancer-proxy-protocol](#proxy-protocol-v2)                | string                  |                           | Set to `"*"` to enable                                 |
 | service.beta.kubernetes.io/aws-load-balancer-ip-address-type                                     | string                  | ipv4                      | ipv4 \| dualstack                                      |
 | service.beta.kubernetes.io/aws-load-balancer-access-log-enabled                                  | boolean                 | false                     |                                                        |
@@ -32,15 +35,47 @@
 | service.beta.kubernetes.io/aws-load-balancer-healthcheck-port                                    | integer \| traffic-port | traffic-port              |                                                        |
 | service.beta.kubernetes.io/aws-load-balancer-healthcheck-path                                    | string                  | "/" for HTTP(S) protocols |                                                        |
 | service.beta.kubernetes.io/aws-load-balancer-eip-allocations                                     | stringList              |                           | Public Facing lb only. Length/order must match subnets |
-| service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses                                | stringList              |                           | Internal lb only. Length/order must match subnets      |
+| service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses                              | stringList              |                           | Internal lb only. Length/order must match subnets      |
 | [service.beta.kubernetes.io/aws-load-balancer-target-group-attributes](#target-group-attributes) | stringMap               |                           |                                                        |
 | [service.beta.kubernetes.io/aws-load-balancer-subnets](#subnets)                                 | stringList              |                           |                                                        |
 | [service.beta.kubernetes.io/aws-load-balancer-alpn-policy](#alpn-policy)                         | stringList              |                           |                                                        |
+| [service.beta.kubernetes.io/aws-load-balancer-target-node-labels](#target-node-labels)           | stringMap               |                           |                                                        |
 
 
 ## Traffic Routing
 Traffic Routing can be controlled with following annotations:
 
+- <a name="lb-type">`service.beta.kubernetes.io/aws-load-balancer-type`</a> specifies the load balancer type. This controller reconciles those service resources with this annotation set to either `nlb-ip` or `external`.
+
+    !!!note ""
+        - For `nlb-ip` type, controller will provision NLB with IP targets. This value is supported for backwards compatibility
+        - For `external` type, NLB target type depend on the annotation [nlb-target-type](#nlb-target-type)
+
+    !!!warning "limitations"
+        - This annotation should not be modified after service creation.
+
+    !!!example
+        ```
+        service.beta.kubernetes.io/aws-load-balancer-type: external
+        ```
+
+- <a name="nlb-target-type">`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type`</a> specifies the target type to configure for NLB. You can choose between
+`instance` and `ip`.
+    - `instance` mode will route traffic to all EC2 instances within cluster on the [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) opened for your service.
+
+        !!!note ""
+            service must be of type "NodePort" or "LoadBalancer" for `instance` targets
+
+    - `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).
+
+    !!!example
+        ```
+        service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
+        ```
+
 - <a name="subnets">`service.beta.kubernetes.io/aws-load-balancer-subnets`</a> specifies the [Availability Zone](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
 the NLB will route traffic to. See [Network Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancers.html#availability-zones) for more details.
 
@@ -58,6 +93,7 @@ the NLB will route traffic to. See [Network Load Balancers](https://docs.aws.ama
         ```
         service.beta.kubernetes.io/aws-load-balancer-subnets: subnet-xxxx, mySubnet
         ```
+
 - <a name="alpn-policy">`service.beta.kubernetes.io/aws-load-balancer-alpn-policy`</a> allows you to configure the [ALPN policies](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html#alpn-policies)
 on the load balancer.
 
@@ -76,8 +112,15 @@ on the load balancer.
         service.beta.kubernetes.io/aws-load-balancer-alpn-policy: HTTP2Preferred
         ```
 
+- <a name="target-node-labels">`service.beta.kubernetes.io/aws-load-balancer-target-node-labels`</a> specifies which nodes to include in the target group registration for `instance` target type.
+
+    !!!example
+        ```
+        service.beta.kubernetes.io/aws-load-balancer-target-node-labels: label1=value1, label2=value2
+        ```
+
 ## Resource attributes
-NLB target group attributes can be controlled via the following annotations:
+NLB resource attributes can be controlled via the following annotations:
 
 - <a name="proxy-protocol-v2">service.beta.kubernetes.io/aws-load-balancer-proxy-protocol</a> specifies whether to enable proxy protocol v2 on the target group.
 Set to '*' to enable proxy protocol v2. This annotation takes precedence over the annotation `service.beta.kubernetes.io/aws-load-balancer-target-group-attributes`
@@ -109,4 +152,33 @@ for proxy protocol v2 configuration.
         - enable [client IP preservation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#client-ip-preservation)
             ```
             service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true
-            ```
+            ```
+
+## Access control
+Load balancer access can be controllerd via following annotations:
+
+- <a name="lb-source-ranges">`service.beta.kubernetes.io/load-balancer-source-ranges`</a> specifies the CIDRs that are allowed to access the NLB.
+
+    !!!tip
+        we recommend specifying CIDRs in the service `Spec.LoadBalancerSourceRanges` instead
+
+    !!!note "Default"
+        - `0.0.0.0/0` will be used if the IPAddressType is "ipv4"
+        - `0.0.0.0/0` and `::/0` will be used if the IPAddressType is "dualstack"
+
+    !!!warning ""
+        This annotation will be ignored in case preserve client IP is not enabled.
+        - preserve client IP is disabled by default for `IP` targets
+        - preserve client IP is enabled by default for `instance` targets
+
+    !!!example
+        ```
+        service.beta.kubernetes.io/load-balancer-source-ranges: 10.0.0.0/24
+        ```
+
+- <a name="lb-internal">`service.beta.kubernetes.io/aws-load-balancer-internal`</a> specifies whether the NLB will be internet-facing or internal.
+
+    !!!example
+        ```
+        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
+        ```

pkg/annotations/constants.go

@@ -49,10 +49,11 @@ const (
 	// prefixes service.beta.kubernetes.io, service.kubernetes.io
 	SvcLBSuffixSourceRanges                  = "load-balancer-source-ranges"
 	SvcLBSuffixLoadBalancerType              = "aws-load-balancer-type"
-	SvcLBSuffixInternal                      = "aws-load-balancer-internal"
-	SvcLBSuffixIPAddressType                 = "aws-load-balancer-ip-address-type"
+	SvcLBSuffixTargetType                    = "aws-load-balancer-nlb-target-type"
 	SvcLBSuffixLoadBalancerName              = "aws-load-balancer-name"
+	SvcLBSuffixInternal                      = "aws-load-balancer-internal"
 	SvcLBSuffixProxyProtocol                 = "aws-load-balancer-proxy-protocol"
+	SvcLBSuffixIPAddressType                 = "aws-load-balancer-ip-address-type"
 	SvcLBSuffixAccessLogEnabled              = "aws-load-balancer-access-log-enabled"
 	SvcLBSuffixAccessLogS3BucketName         = "aws-load-balancer-access-log-s3-bucket-name"
 	SvcLBSuffixAccessLogS3BucketPrefix       = "aws-load-balancer-access-log-s3-bucket-prefix"
@@ -74,6 +75,5 @@ const (
 	SvcLBSuffixTargetGroupAttributes         = "aws-load-balancer-target-group-attributes"
 	SvcLBSuffixSubnets                       = "aws-load-balancer-subnets"
 	SvcLBSuffixALPNPolicy                    = "aws-load-balancer-alpn-policy"
-	SvcLBSuffixTargetType                    = "aws-load-balancer-target-type"
 	SvcLBSuffixTargetNodeLabels              = "aws-load-balancer-target-node-labels"
 )

pkg/ingress/model_build_target_group_test.go

@@ -614,7 +614,7 @@ func Test_defaultModelBuildTask_buildTargetGroupBindingNodeSelector(t *testing.T
 						},
 					},
 				},
-				svc: &corev1.Service{},
+				svc:        &corev1.Service{},
 				targetType: elbv2model.TargetTypeInstance,
 			},
 			wantErr: errors.New("failed to parse stringMap annotation, alb.ingress.kubernetes.io/target-node-labels: key1"),

pkg/service/model_build_target_group.go

@@ -325,10 +325,10 @@ func (t *defaultModelBuildTask) buildTargetType(_ context.Context) (elbv2model.T
 	_ = t.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixLoadBalancerType, &lbType, t.service.Annotations)
 	var lbTargetType string
 	_ = t.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixTargetType, &lbTargetType, t.service.Annotations)
-	if lbType == LoadBalancerTargetTypeNLBIP || (lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeNLBIP) {
+	if lbType == LoadBalancerTypeNLBIP || (lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeIP) {
 		return elbv2model.TargetTypeIP, nil
 	}
-	if lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeNLBInstance {
+	if lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeInstance {
 		return elbv2model.TargetTypeInstance, nil
 	}
 	return "", errors.Errorf("unsupported target type \"%v\" for load balancer type \"%v\"", lbTargetType, lbType)

pkg/service/model_build_target_group_test.go

@@ -966,8 +966,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
 			svc: &corev1.Service{
 				ObjectMeta: metav1.ObjectMeta{
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
 					},
 				},
 			},
@@ -978,8 +978,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
 			svc: &corev1.Service{
 				ObjectMeta: metav1.ObjectMeta{
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-ip",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "ip",
 					},
 				},
 			},
@@ -1001,8 +1001,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
 			svc: &corev1.Service{
 				ObjectMeta: metav1.ObjectMeta{
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "unknown",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "unknown",
 					},
 				},
 			},

pkg/service/model_builder.go

@@ -14,10 +14,10 @@ import (
 )
 
 const (
-	LoadBalancerTypeNLBIP             = "nlb-ip"
-	LoadBalancerTypeExternal          = "external"
-	LoadBalancerTargetTypeNLBIP       = "nlb-ip"
-	LoadBalancerTargetTypeNLBInstance = "nlb-instance"
+	LoadBalancerTypeNLBIP          = "nlb-ip"
+	LoadBalancerTypeExternal       = "external"
+	LoadBalancerTargetTypeIP       = "ip"
+	LoadBalancerTargetTypeInstance = "instance"
 )
 
 // ModelBuilder builds the model stack for the service resource.

pkg/service/model_builder_test.go

@@ -1022,8 +1022,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
 					Name:      "service-deleted",
 					Namespace: "doesnt-exist",
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-ip",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "ip",
 					},
 					DeletionTimestamp: &metav1.Time{
 						Time: time.Now(),
@@ -1044,8 +1044,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
 					Name:      "instance-mode",
 					Namespace: "default",
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
 					},
 					UID: "2dc098f0-ae33-4378-af7b-83e2a0424495",
 				},
@@ -1352,8 +1352,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
 					Name:      "traffic-local",
 					Namespace: "app",
 					Annotations: map[string]string{
-						"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-						"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
+						"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+						"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
 					},
 					UID: "2dc098f0-ae33-4378-af7b-83e2a0424495",
 				},

test/e2e/service/nlb_instance_target.go

@@ -95,8 +95,8 @@ func (s *NLBInstanceTestStack) buildServiceSpec(ctx context.Context, annotations
 		ObjectMeta: metav1.ObjectMeta{
 			Name: defaultName,
 			Annotations: map[string]string{
-				"service.beta.kubernetes.io/aws-load-balancer-type":        "external",
-				"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
+				"service.beta.kubernetes.io/aws-load-balancer-type":            "external",
+				"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
 			},
 		},
 		Spec: corev1.ServiceSpec{

test/e2e/service/nlb_ip_target_test.go

@@ -303,7 +303,7 @@ var _ = Describe("k8s service reconciled by the aws load balancer", func() {
 	})
 	Context("NLB IP Load Balancer with name", func() {
 		var (
-			svc *corev1.Service
+			svc    *corev1.Service
 			lbName string
 		)
 		BeforeEach(func() {