Skip to content

Commit 8250879

Browse files
kishorjTimothy-Dougherty
kishorj
authored and
Timothy-Dougherty
committed
update nlb target type annotation (kubernetes-sigs#1894)
1 parent 0b440a4 commit 8250879

File tree

10 files changed

+104
-32
lines changed

10 files changed

+104
-32
lines changed

‎controllers/service/eventhandlers/service_events.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ func (h *enqueueRequestsForServiceEvent) isServiceSupported(service *corev1.Serv
6565
}
6666
var lbTargetType string
6767
_ = h.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixTargetType, &lbTargetType, service.Annotations)
68-
if lbType == svcpkg.LoadBalancerTypeExternal && (lbTargetType == svcpkg.LoadBalancerTargetTypeNLBIP ||
69-
lbTargetType == svcpkg.LoadBalancerTargetTypeNLBInstance) {
68+
if lbType == svcpkg.LoadBalancerTypeExternal && (lbTargetType == svcpkg.LoadBalancerTargetTypeIP ||
69+
lbTargetType == svcpkg.LoadBalancerTargetTypeInstance) {
7070
return true
7171
}
7272
return false

‎docs/guide/service/annotations.md

Lines changed: 77 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,11 @@
1111
## Annotations
1212
| Name | Type | Default | Notes |
1313
|--------------------------------------------------------------------------------------------------|-------------------------|---------------------------|--------------------------------------------------------|
14-
| service.beta.kubernetes.io/aws-load-balancer-type | string | | |
15-
| service.beta.kubernetes.io/aws-load-balancer-internal | boolean | false | |
14+
| [service.beta.kubernetes.io/load-balancer-source-ranges](#lb-source-ranges) | stringList | | |
15+
| [service.beta.kubernetes.io/aws-load-balancer-type](#lb-type) | string | | |
16+
| [service.beta.kubernetes.io/aws-load-balancer-nlb-target-type](#nlb-target-type) | string | | |
17+
| service.beta.kubernetes.io/aws-load-balancer-name | string | | |
18+
| [service.beta.kubernetes.io/aws-load-balancer-internal](#lb-internal) | boolean | false | |
1619
| [service.beta.kubernetes.io/aws-load-balancer-proxy-protocol](#proxy-protocol-v2) | string | | Set to `"*"` to enable |
1720
| service.beta.kubernetes.io/aws-load-balancer-ip-address-type | string | ipv4 | ipv4 \| dualstack |
1821
| service.beta.kubernetes.io/aws-load-balancer-access-log-enabled | boolean | false | |
@@ -32,15 +35,47 @@
3235
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-port | integer \| traffic-port | traffic-port | |
3336
| service.beta.kubernetes.io/aws-load-balancer-healthcheck-path | string | "/" for HTTP(S) protocols | |
3437
| service.beta.kubernetes.io/aws-load-balancer-eip-allocations | stringList | | Public Facing lb only. Length/order must match subnets |
35-
| service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses | stringList | | Internal lb only. Length/order must match subnets |
38+
| service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses | stringList | | Internal lb only. Length/order must match subnets |
3639
| [service.beta.kubernetes.io/aws-load-balancer-target-group-attributes](#target-group-attributes) | stringMap | | |
3740
| [service.beta.kubernetes.io/aws-load-balancer-subnets](#subnets) | stringList | | |
3841
| [service.beta.kubernetes.io/aws-load-balancer-alpn-policy](#alpn-policy) | stringList | | |
42+
| [service.beta.kubernetes.io/aws-load-balancer-target-node-labels](#target-node-labels) | stringMap | | |
3943

4044

4145
## Traffic Routing
4246
Traffic Routing can be controlled with following annotations:
4347

48+
- <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`.
49+
50+
!!!note ""
51+
- For `nlb-ip` type, controller will provision NLB with IP targets. This value is supported for backwards compatibility
52+
- For `external` type, NLB target type depend on the annotation [nlb-target-type](#nlb-target-type)
53+
54+
!!!warning "limitations"
55+
- This annotation should not be modified after service creation.
56+
57+
!!!example
58+
```
59+
service.beta.kubernetes.io/aws-load-balancer-type: external
60+
```
61+
62+
- <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
63+
`instance` and `ip`.
64+
- `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.
65+
66+
!!!note ""
67+
service must be of type "NodePort" or "LoadBalancer" for `instance` targets
68+
69+
- `ip` mode will route traffic directly to the pod IP.
70+
71+
!!!note ""
72+
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).
73+
74+
!!!example
75+
```
76+
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
77+
```
78+
4479
- <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)
4580
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.
4681

@@ -58,6 +93,7 @@ the NLB will route traffic to. See [Network Load Balancers](https://docs.aws.ama
5893
```
5994
service.beta.kubernetes.io/aws-load-balancer-subnets: subnet-xxxx, mySubnet
6095
```
96+
6197
- <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)
6298
on the load balancer.
6399

@@ -76,8 +112,15 @@ on the load balancer.
76112
service.beta.kubernetes.io/aws-load-balancer-alpn-policy: HTTP2Preferred
77113
```
78114

115+
- <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.
116+
117+
!!!example
118+
```
119+
service.beta.kubernetes.io/aws-load-balancer-target-node-labels: label1=value1, label2=value2
120+
```
121+
79122
## Resource attributes
80-
NLB target group attributes can be controlled via the following annotations:
123+
NLB resource attributes can be controlled via the following annotations:
81124

82125
- <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.
83126
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.
109152
- enable [client IP preservation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#client-ip-preservation)
110153
```
111154
service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true
112-
```
155+
```
156+
157+
## Access control
158+
Load balancer access can be controllerd via following annotations:
159+
160+
- <a name="lb-source-ranges">`service.beta.kubernetes.io/load-balancer-source-ranges`</a> specifies the CIDRs that are allowed to access the NLB.
161+
162+
!!!tip
163+
we recommend specifying CIDRs in the service `Spec.LoadBalancerSourceRanges` instead
164+
165+
!!!note "Default"
166+
- `0.0.0.0/0` will be used if the IPAddressType is "ipv4"
167+
- `0.0.0.0/0` and `::/0` will be used if the IPAddressType is "dualstack"
168+
169+
!!!warning ""
170+
This annotation will be ignored in case preserve client IP is not enabled.
171+
- preserve client IP is disabled by default for `IP` targets
172+
- preserve client IP is enabled by default for `instance` targets
173+
174+
!!!example
175+
```
176+
service.beta.kubernetes.io/load-balancer-source-ranges: 10.0.0.0/24
177+
```
178+
179+
- <a name="lb-internal">`service.beta.kubernetes.io/aws-load-balancer-internal`</a> specifies whether the NLB will be internet-facing or internal.
180+
181+
!!!example
182+
```
183+
service.beta.kubernetes.io/aws-load-balancer-internal: "true"
184+
```

‎pkg/annotations/constants.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,10 +49,11 @@ const (
4949
// prefixes service.beta.kubernetes.io, service.kubernetes.io
5050
SvcLBSuffixSourceRanges = "load-balancer-source-ranges"
5151
SvcLBSuffixLoadBalancerType = "aws-load-balancer-type"
52-
SvcLBSuffixInternal = "aws-load-balancer-internal"
53-
SvcLBSuffixIPAddressType = "aws-load-balancer-ip-address-type"
52+
SvcLBSuffixTargetType = "aws-load-balancer-nlb-target-type"
5453
SvcLBSuffixLoadBalancerName = "aws-load-balancer-name"
54+
SvcLBSuffixInternal = "aws-load-balancer-internal"
5555
SvcLBSuffixProxyProtocol = "aws-load-balancer-proxy-protocol"
56+
SvcLBSuffixIPAddressType = "aws-load-balancer-ip-address-type"
5657
SvcLBSuffixAccessLogEnabled = "aws-load-balancer-access-log-enabled"
5758
SvcLBSuffixAccessLogS3BucketName = "aws-load-balancer-access-log-s3-bucket-name"
5859
SvcLBSuffixAccessLogS3BucketPrefix = "aws-load-balancer-access-log-s3-bucket-prefix"
@@ -74,6 +75,5 @@ const (
7475
SvcLBSuffixTargetGroupAttributes = "aws-load-balancer-target-group-attributes"
7576
SvcLBSuffixSubnets = "aws-load-balancer-subnets"
7677
SvcLBSuffixALPNPolicy = "aws-load-balancer-alpn-policy"
77-
SvcLBSuffixTargetType = "aws-load-balancer-target-type"
7878
SvcLBSuffixTargetNodeLabels = "aws-load-balancer-target-node-labels"
7979
)

‎pkg/ingress/model_build_target_group_test.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -614,7 +614,7 @@ func Test_defaultModelBuildTask_buildTargetGroupBindingNodeSelector(t *testing.T
614614
},
615615
},
616616
},
617-
svc: &corev1.Service{},
617+
svc: &corev1.Service{},
618618
targetType: elbv2model.TargetTypeInstance,
619619
},
620620
wantErr: errors.New("failed to parse stringMap annotation, alb.ingress.kubernetes.io/target-node-labels: key1"),

‎pkg/service/model_build_target_group.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -325,10 +325,10 @@ func (t *defaultModelBuildTask) buildTargetType(_ context.Context) (elbv2model.T
325325
_ = t.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixLoadBalancerType, &lbType, t.service.Annotations)
326326
var lbTargetType string
327327
_ = t.annotationParser.ParseStringAnnotation(annotations.SvcLBSuffixTargetType, &lbTargetType, t.service.Annotations)
328-
if lbType == LoadBalancerTargetTypeNLBIP || (lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeNLBIP) {
328+
if lbType == LoadBalancerTypeNLBIP || (lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeIP) {
329329
return elbv2model.TargetTypeIP, nil
330330
}
331-
if lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeNLBInstance {
331+
if lbType == LoadBalancerTypeExternal && lbTargetType == LoadBalancerTargetTypeInstance {
332332
return elbv2model.TargetTypeInstance, nil
333333
}
334334
return "", errors.Errorf("unsupported target type \"%v\" for load balancer type \"%v\"", lbTargetType, lbType)

‎pkg/service/model_build_target_group_test.go

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -966,8 +966,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
966966
svc: &corev1.Service{
967967
ObjectMeta: metav1.ObjectMeta{
968968
Annotations: map[string]string{
969-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
970-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
969+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
970+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
971971
},
972972
},
973973
},
@@ -978,8 +978,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
978978
svc: &corev1.Service{
979979
ObjectMeta: metav1.ObjectMeta{
980980
Annotations: map[string]string{
981-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
982-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-ip",
981+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
982+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "ip",
983983
},
984984
},
985985
},
@@ -1001,8 +1001,8 @@ func Test_defaultModelBuilder_buildTargetType(t *testing.T) {
10011001
svc: &corev1.Service{
10021002
ObjectMeta: metav1.ObjectMeta{
10031003
Annotations: map[string]string{
1004-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1005-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "unknown",
1004+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1005+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "unknown",
10061006
},
10071007
},
10081008
},

‎pkg/service/model_builder.go

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ import (
1414
)
1515

1616
const (
17-
LoadBalancerTypeNLBIP = "nlb-ip"
18-
LoadBalancerTypeExternal = "external"
19-
LoadBalancerTargetTypeNLBIP = "nlb-ip"
20-
LoadBalancerTargetTypeNLBInstance = "nlb-instance"
17+
LoadBalancerTypeNLBIP = "nlb-ip"
18+
LoadBalancerTypeExternal = "external"
19+
LoadBalancerTargetTypeIP = "ip"
20+
LoadBalancerTargetTypeInstance = "instance"
2121
)
2222

2323
// ModelBuilder builds the model stack for the service resource.

‎pkg/service/model_builder_test.go

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,8 +1022,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
10221022
Name: "service-deleted",
10231023
Namespace: "doesnt-exist",
10241024
Annotations: map[string]string{
1025-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1026-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-ip",
1025+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1026+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "ip",
10271027
},
10281028
DeletionTimestamp: &metav1.Time{
10291029
Time: time.Now(),
@@ -1044,8 +1044,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
10441044
Name: "instance-mode",
10451045
Namespace: "default",
10461046
Annotations: map[string]string{
1047-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1048-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
1047+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1048+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
10491049
},
10501050
UID: "2dc098f0-ae33-4378-af7b-83e2a0424495",
10511051
},
@@ -1352,8 +1352,8 @@ func Test_defaultModelBuilderTask_Build(t *testing.T) {
13521352
Name: "traffic-local",
13531353
Namespace: "app",
13541354
Annotations: map[string]string{
1355-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1356-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
1355+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
1356+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
13571357
},
13581358
UID: "2dc098f0-ae33-4378-af7b-83e2a0424495",
13591359
},

‎test/e2e/service/nlb_instance_target.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,8 @@ func (s *NLBInstanceTestStack) buildServiceSpec(ctx context.Context, annotations
9595
ObjectMeta: metav1.ObjectMeta{
9696
Name: defaultName,
9797
Annotations: map[string]string{
98-
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
99-
"service.beta.kubernetes.io/aws-load-balancer-target-type": "nlb-instance",
98+
"service.beta.kubernetes.io/aws-load-balancer-type": "external",
99+
"service.beta.kubernetes.io/aws-load-balancer-nlb-target-type": "instance",
100100
},
101101
},
102102
Spec: corev1.ServiceSpec{

‎test/e2e/service/nlb_ip_target_test.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -303,7 +303,7 @@ var _ = Describe("k8s service reconciled by the aws load balancer", func() {
303303
})
304304
Context("NLB IP Load Balancer with name", func() {
305305
var (
306-
svc *corev1.Service
306+
svc *corev1.Service
307307
lbName string
308308
)
309309
BeforeEach(func() {

0 commit comments

Comments
 (0)