Add support for NLB target group attributes (ProxyProtocolV2, PreserveClientIP)

This change adds support for configuring two NLB-specific target group attributes:

1. Proxy Protocol v2: Enable with `--nlb-proxy-protocol-v2` flag (default: false)
   - Enables Proxy Protocol v2 for NLB target groups
   - Opt-in feature, disabled by default

2. Preserve Client IP: Configure with `--nlb-preserve-client-ip` flag (default: true)
   - Preserves client IP address in NLB target group connections
   - Enabled by default

These attributes are only applied to Network Load Balancer target groups and do not
affect Application Load Balancers.

BREAKING CHANGE:

The `preserve_client_ip` attribute is now explicitly set to true by the controller
on all NLB target groups. Previously, this attribute was not explicitly set, which
relied on AWS NLB's default behavior (which is also true).

If your NLB target groups currently have `preserve_client_ip=false` set outside of
the controller, updating to this version will override it to true. To maintain the
previous behavior of `preserve_client_ip=false`, pass the `--nlb-preserve-client-ip=false`
flag when running the controller.

Changes:
- Add NLB attribute flags to controller CLI
- Extend AWS adapter with WithNLBProxyProtocolV2() and WithNLBPreserveClientIP() methods
- Update CloudFormation template generation to conditionally add NLB attributes
- Add comprehensive test coverage (5 test cases)
- Update README with v0.20 upgrade notes and breaking change documentation

Signed-off-by: speruri <surya.srikar.peruri@zalando.de>

Author: speruri

README.md

@@ -43,9 +43,28 @@ This information is used to manage AWS resources for each ingress objects of the
 - Support for `ipv4` and `ipv6` target group IP address types for ALB and NLB
     - set default target group IP address type using `--target-group-ip-address-type=ipv6`
     - IPv6 targets require dualstack load balancers (`--ip-addr-type=dualstack`)
+- Support for NLB target group attributes (Network Load Balancers only)
+    - Proxy Protocol v2: enable with `--nlb-proxy-protocol-v2` (default: false)
+    - Preserve Client IP: configure with `--nlb-preserve-client-ip` (default: true, matching AWS NLB default)
 
 ## Upgrade
 
+### <v0.20 to >=v0.20
+
+Version `v0.20` adds support for NLB target group attributes:
+
+- **Proxy Protocol v2**: Enable with `--nlb-proxy-protocol-v2` flag (default: false, disabled)
+  - Enables Proxy Protocol v2 for Network Load Balancer target groups
+  - Only applies to NLBs; ALBs do not support this feature
+
+- **Preserve Client IP**: Configure with `--nlb-preserve-client-ip` flag (default: true, enabled)
+  - Preserves client IP address in NLB target group connections
+  - Defaults to true, matching AWS NLB default behavior
+  - Set to false to override and disable this feature
+  - **Breaking change**: Previously this attribute was not explicitly set. Updating to v0.20 will set `preserve_client_ip.enabled=true` on all NLB target groups. For setups that require it disabled, use `--nlb-preserve-client-ip=false`
+
+These attributes are only applied to Network Load Balancer target groups. Application Load Balancers are not affected.
+
 ### <v0.19 to >=v0.19
 
 Version `v0.19` adds support for IPv6 target group IP address type. When using IPv6 targets, ensure your load balancer is configured as dualstack (`--ip-addr-type=dualstack` or `alb.ingress.kubernetes.io/ip-address-type: dualstack`). IPv4-only load balancers cannot route to IPv6 targets and will fail with a clear error message.

VERSION

@@ -1 +1 @@
-v0.19
+v0.20

aws/adapter.go

@@ -70,6 +70,8 @@ type Adapter struct {
 	httpRedirectToHTTPS         bool
 	nlbCrossZone                bool
 	nlbHTTPEnabled              bool
+	nlbProxyProtocolV2Enabled   bool
+	nlbPreserveClientIPEnabled  bool
 	customFilter                string
 	internalDomains             []string
 	denyInternalDomains         bool
@@ -495,6 +497,20 @@ func (a *Adapter) WithNLBHTTPEnabled(nlbHTTPEnabled bool) *Adapter {
 	return a
 }
 
+// WithNLBProxyProtocolV2 returns the receiver adapter after setting the
+// nlbProxyProtocolV2Enabled config.
+func (a *Adapter) WithNLBProxyProtocolV2(nlbProxyProtocolV2Enabled bool) *Adapter {
+	a.nlbProxyProtocolV2Enabled = nlbProxyProtocolV2Enabled
+	return a
+}
+
+// WithNLBPreserveClientIP returns the receiver adapter after setting the
+// nlbPreserveClientIPEnabled config.
+func (a *Adapter) WithNLBPreserveClientIP(nlbPreserveClientIPEnabled bool) *Adapter {
+	a.nlbPreserveClientIPEnabled = nlbPreserveClientIPEnabled
+	return a
+}
+
 // WithCustomFilter returns the receiver adapter after setting a custom filter expression
 func (a *Adapter) WithCustomFilter(customFilter string) *Adapter {
 	a.customFilter = customFilter
@@ -841,6 +857,8 @@ func (a *Adapter) CreateStack(ctx context.Context, certificateARNs []string, sch
 		httpRedirectToHTTPS:               a.httpRedirectToHTTPS,
 		nlbCrossZone:                      a.nlbCrossZone,
 		nlbZoneAffinity:                   a.nlbZoneAffinity,
+		nlbProxyProtocolV2Enabled:         a.nlbProxyProtocolV2Enabled,
+		nlbPreserveClientIPEnabled:        a.nlbPreserveClientIPEnabled,
 		http2:                             http2,
 		tags:                              a.stackTags,
 		internalDomains:                   a.internalDomains,
@@ -903,6 +921,8 @@ func (a *Adapter) UpdateStack(ctx context.Context, stackName string, certificate
 		httpRedirectToHTTPS:               a.httpRedirectToHTTPS,
 		nlbCrossZone:                      a.nlbCrossZone,
 		nlbZoneAffinity:                   a.nlbZoneAffinity,
+		nlbProxyProtocolV2Enabled:         a.nlbProxyProtocolV2Enabled,
+		nlbPreserveClientIPEnabled:        a.nlbPreserveClientIPEnabled,
 		http2:                             http2,
 		tags:                              a.stackTags,
 		internalDomains:                   a.internalDomains,

aws/cf.go

@@ -191,6 +191,8 @@ type stackSpec struct {
 	albLogsS3Prefix                   string
 	wafWebAclId                       string
 	nlbZoneAffinity                   string
+	nlbProxyProtocolV2Enabled         bool
+	nlbPreserveClientIPEnabled        bool
 	cwAlarms                          CloudWatchAlarmList
 	httpRedirectToHTTPS               bool
 	nlbCrossZone                      bool

aws/cf_template.go

@@ -487,13 +487,32 @@ func newTargetGroup(spec *stackSpec, targetPortParameter string) *cloudformation
 		healthCheckProtocol = "HTTPS"
 	}
 
-	targetGroup := &cloudformation.ElasticLoadBalancingV2TargetGroup{
-		TargetGroupAttributes: &cloudformation.ElasticLoadBalancingV2TargetGroupTargetGroupAttributeList{
-			{
-				Key:   cloudformation.String("deregistration_delay.timeout_seconds"),
-				Value: cloudformation.String(fmt.Sprintf("%d", spec.deregistrationDelayTimeoutSeconds)),
-			},
+	// Build target group attributes
+	attrsList := cloudformation.ElasticLoadBalancingV2TargetGroupTargetGroupAttributeList{
+		{
+			Key:   cloudformation.String("deregistration_delay.timeout_seconds"),
+			Value: cloudformation.String(fmt.Sprintf("%d", spec.deregistrationDelayTimeoutSeconds)),
 		},
+	}
+
+	// Add NLB-specific attributes
+	if spec.loadbalancerType == LoadBalancerTypeNetwork {
+		if spec.nlbProxyProtocolV2Enabled {
+			attrsList = append(attrsList, cloudformation.ElasticLoadBalancingV2TargetGroupTargetGroupAttribute{
+				Key:   cloudformation.String("proxy_protocol_v2.enabled"),
+				Value: cloudformation.String("true"),
+			})
+		}
+		if spec.nlbPreserveClientIPEnabled {
+			attrsList = append(attrsList, cloudformation.ElasticLoadBalancingV2TargetGroupTargetGroupAttribute{
+				Key:   cloudformation.String("preserve_client_ip.enabled"),
+				Value: cloudformation.String("true"),
+			})
+		}
+	}
+
+	targetGroup := &cloudformation.ElasticLoadBalancingV2TargetGroup{
+		TargetGroupAttributes: &attrsList,
 		HealthCheckIntervalSeconds: cloudformation.Ref(parameterTargetGroupHealthCheckIntervalParameter).Integer(),
 		HealthCheckPath:            cloudformation.Ref(parameterTargetGroupHealthCheckPathParameter).String(),
 		HealthCheckPort:            cloudformation.Ref(parameterTargetGroupHealthCheckPortParameter).String(),

aws/cf_test.go

@@ -932,3 +932,69 @@ func TestShouldDelete(t *testing.T) {
 	}
 
 }
+
+func TestNLBTargetGroupAttributes(t *testing.T) {
+	for _, ti := range []struct {
+		name                          string
+		givenSpec                     stackSpec
+		expectedAttrCount             int
+	}{
+		{
+			name: "ALB-with-nlb-flags-ignored",
+			givenSpec: stackSpec{
+				loadbalancerType:            LoadBalancerTypeApplication,
+				nlbProxyProtocolV2Enabled:   true,
+				nlbPreserveClientIPEnabled:  true,
+				deregistrationDelayTimeoutSeconds: 30,
+			},
+			expectedAttrCount: 1, // only deregistration delay
+		},
+		{
+			name: "NLB-with-proxy-protocol-v2",
+			givenSpec: stackSpec{
+				loadbalancerType:           LoadBalancerTypeNetwork,
+				nlbProxyProtocolV2Enabled:  true,
+				nlbPreserveClientIPEnabled: false,
+				deregistrationDelayTimeoutSeconds: 30,
+			},
+			expectedAttrCount: 2, // deregistration delay + proxy protocol v2
+		},
+		{
+			name: "NLB-with-preserve-client-ip",
+			givenSpec: stackSpec{
+				loadbalancerType:           LoadBalancerTypeNetwork,
+				nlbProxyProtocolV2Enabled:  false,
+				nlbPreserveClientIPEnabled: true,
+				deregistrationDelayTimeoutSeconds: 30,
+			},
+			expectedAttrCount: 2, // deregistration delay + preserve client ip
+		},
+		{
+			name: "NLB-with-both-attributes",
+			givenSpec: stackSpec{
+				loadbalancerType:           LoadBalancerTypeNetwork,
+				nlbProxyProtocolV2Enabled:  true,
+				nlbPreserveClientIPEnabled: true,
+				deregistrationDelayTimeoutSeconds: 30,
+			},
+			expectedAttrCount: 3, // deregistration delay + both NLB attributes
+		},
+		{
+			name: "NLB-with-no-extra-attributes",
+			givenSpec: stackSpec{
+				loadbalancerType:           LoadBalancerTypeNetwork,
+				nlbProxyProtocolV2Enabled:  false,
+				nlbPreserveClientIPEnabled: false,
+				deregistrationDelayTimeoutSeconds: 30,
+			},
+			expectedAttrCount: 1, // only deregistration delay
+		},
+	} {
+		t.Run(ti.name, func(t *testing.T) {
+			tg := newTargetGroup(&ti.givenSpec, "TargetPort")
+			assert.NotNil(t, tg)
+			assert.NotNil(t, tg.TargetGroupAttributes)
+			assert.Equal(t, ti.expectedAttrCount, len(*tg.TargetGroupAttributes), "target group attributes count mismatch")
+		})
+	}
+}

controller.go

@@ -81,6 +81,8 @@ var (
 	nlbZoneAffinity               string
 	nlbCrossZone                  bool
 	nlbHTTPEnabled                bool
+	nlbProxyProtocolV2Enabled     bool
+	nlbPreserveClientIPEnabled    bool
 	ingressAPIVersion             string
 	internalDomains               []string
 	targetAccessMode              string
@@ -183,6 +185,10 @@ func loadSettings() error {
 		Default("false").BoolVar(&nlbCrossZone)
 	kingpin.Flag("nlb-http-enabled", "Enable HTTP (port 80) for Network Load Balancers. By default this is disabled as NLB can't provide HTTP -> HTTPS redirect.").
 		Default("false").BoolVar(&nlbHTTPEnabled)
+	kingpin.Flag("nlb-proxy-protocol-v2", "Enable Proxy Protocol v2 for Network Load Balancers. This setting only applies to 'network' Load Balancers.").
+		Default("false").BoolVar(&nlbProxyProtocolV2Enabled)
+	kingpin.Flag("nlb-preserve-client-ip", "Enable preserve client IP address for Network Load Balancers. This setting only applies to 'network' Load Balancers.").
+		Default("true").BoolVar(&nlbPreserveClientIPEnabled)
 	kingpin.Flag("deny-internal-domains", "Sets a rule on ALB's Listeners that denies requests with the Host header as a internal domain. Domains can be set with the -internal-domains flag.").
 		Default("false").BoolVar(&denyInternalDomains)
 	kingpin.Flag("internal-domains", "Define the internal domains to be blocked when -deny-internal-domains is set to true. Set it multiple times for multiple domains. The maximum size of each name is 128 characters. The following wildcard characters are supported: * (matches 0 or more characters) and ? (matches exactly 1 character).").
@@ -346,6 +352,8 @@ func main() {
 		WithNLBCrossZone(nlbCrossZone).
 		WithNLBZoneAffinity(nlbZoneAffinity).
 		WithNLBHTTPEnabled(nlbHTTPEnabled).
+		WithNLBProxyProtocolV2(nlbProxyProtocolV2Enabled).
+		WithNLBPreserveClientIP(nlbPreserveClientIPEnabled).
 		WithCustomFilter(customFilter).
 		WithStackTags(additionalStackTags).
 		WithInternalDomains(internalDomains).