[feat] Add IPv6 public backends for NodeBalancers

[komer3]

Summary

• add IPv6 backend support for NodeBalancer services, including VPC-backed NodeBalancers when VPC backends are enabled
• keep NodeBalancer VPC config in create/update requests when IPv6 backends are selected
• add controller/chart/docs and e2e coverage for the IPv6 backend behavior

Behavior

• introduces --enable-ipv6-for-nodebalancer-backends as a global controller flag
• introduces service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends as a per-service override
• applies IPv6 backend selection to both VPC-backed and non-VPC-backed NodeBalancer services
• preserves VPC backend config when VPC-backed NodeBalancers are enabled
• enabling the global flag can migrate existing eligible services from IPv4 to IPv6 backends during reconcile
• requires the selected IPv6 backend address on each backend node and returns an error instead of silently falling back to IPv4
• uses IPv6-safe backend host:port formatting for NodeBalancer node addresses

Code Changes

• add the new service annotation constant in cloud/annotations/annotations.go
• add the new controller option in cloud/linode/options/options.go and register the flag in main.go
• update cloud/linode/loadbalancers.go to:
  • resolve IPv6 backend selection from the service annotation first, then the global flag
  • choose IPv6 node addresses using the existing node-address path while preserving VPC backend config
  • allow VPC-backed NodeBalancers to reconcile with IPv6 backends instead of dropping VPC settings
  • rebuild backend node configs with IPv6-safe address formatting
• add Helm chart support for the new controller flag in deploy/chart/templates/daemonset.yaml and deploy/chart/values.yaml
• document the feature and backend behavior in docs/configuration/loadbalancer.md, docs/configuration/environment.md, and docs/configuration/annotations.md
• ignore local generated cluster artifacts in .gitignore

Tests

Unit

• extend cloud/linode/loadbalancers_test.go with coverage for:
  • IPv4 backend selection for the existing path
  • IPv6 backend selection from node IPv6 addresses
  • preserving VPC backend config when IPv6 backends are requested via annotation or global flag
  • failing when IPv6 backends are requested and a node lacks the required IPv6 address
  • global flag and service annotation precedence
  • IPv6-safe backend address formatting

E2E

• add a new Chainsaw scenario under e2e/test/lb-with-ipv6-backends/
• deploy a dual-stack LoadBalancer service annotated with linode-loadbalancer-enable-ipv6-backends: "true"
• verify NodeBalancer backend node addresses returned by the Linode API are IPv6
• verify traffic still reaches both backend pods through the service

Verification

• go test ./cloud/linode/...
• make test

[codecov]

Codecov Report

❌ Patch coverage is 84.09091% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.54%. Comparing base (481c36e) to head (513ac94).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
cloud/linode/loadbalancers.go	84.09%	5 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #545      +/-   ##
==========================================
+ Coverage   73.43%   73.54%   +0.11%     
==========================================
  Files          19       19              
  Lines        2906     2930      +24     
==========================================
+ Hits         2134     2155      +21     
- Misses        523      525       +2     
- Partials      249      250       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds support for selecting public IPv6 addresses as NodeBalancer backend node targets (with global flag + per-Service annotation), including for VPC-backed NodeBalancers, and extends unit/e2e/docs/chart coverage around the new behavior.

Changes:

• Add --enable-ipv6-for-nodebalancer-backends and service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends to control IPv6 backend selection.
• Update NodeBalancer reconciliation to build backend node addresses using IPv6-safe host:port formatting and preserve VPC config when IPv6 backends are enabled.
• Add Helm/docs and unit + Chainsaw e2e coverage for IPv6 backend behavior.

Reviewed changes

Copilot reviewed 14 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
main.go	Registers new controller flag for IPv6 NodeBalancer backends.
cloud/annotations/annotations.go	Adds the per-service annotation constant for enabling IPv6 backends.
cloud/linode/options/options.go	Adds a global options field to enable IPv6 NodeBalancer backends.
cloud/linode/loadbalancers.go	Core logic: resolves IPv6-backend enablement, selects node backend IPs, preserves VPC config, and formats backend addresses safely for IPv6.
cloud/linode/loadbalancers_test.go	Adds unit tests for IPv6 backend selection, precedence rules, VPC preservation, and address formatting.
deploy/chart/templates/daemonset.yaml	Plumbs the new flag into the Helm chart DaemonSet args.
deploy/chart/values.yaml	Documents the new Helm value for enabling IPv6 NodeBalancer backends.
docs/configuration/loadbalancer.md	Documents frontend vs backend IPv6 behavior and operational requirements for IPv6 backends.
docs/configuration/environment.md	Documents the new controller flag and its behavior/requirements.
docs/configuration/annotations.md	Documents the new service annotation for IPv6 backends.
e2e/test/lb-with-ipv6-backends/create-pods-services.yaml	Adds an e2e workload + dual-stack Service annotated to enable IPv6 backends.
e2e/test/lb-with-ipv6-backends/chainsaw-test.yaml	Adds a Chainsaw scenario validating backend node addresses are IPv6 and traffic still reaches pods.
devbox.json	Pins clusterctl version in the devbox environment.
devbox.lock	Updates the devbox lockfile to reflect the pinned clusterctl version.
Makefile	Updates cluster-api related versions and ensures clusterctl is used via a configured path.
.gitignore	Ignores local generated cluster artifacts/kubeconfigs.

[Copilot]

Pull request overview

Adds support for using public IPv6 addresses as NodeBalancer backend targets (optionally enabled globally or per-Service), while keeping existing VPC-backed NodeBalancer configuration intact during create/update and adding related test/helm/docs coverage.

Changes:

• Introduces a new controller flag and Service annotation to opt services into IPv6 NodeBalancer backends (annotation takes precedence).
• Updates NodeBalancer backend-node building to select IPv6 NodeExternalIP and format backend addresses IPv6-safely.
• Extends unit/e2e tests plus chart/docs updates to cover and document IPv6 backend behavior.

Reviewed changes

Copilot reviewed 14 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
main.go	Registers the new --enable-ipv6-for-nodebalancer-backends flag.
cloud/linode/options/options.go	Adds a new global option field for IPv6 backend enablement.
cloud/annotations/annotations.go	Adds the new per-Service annotation constant for IPv6 backends.
cloud/linode/loadbalancers.go	Implements IPv6 backend selection, annotation/flag precedence, and IPv6-safe host:port formatting; preserves VPC config during reconcile.
cloud/linode/loadbalancers_test.go	Adds unit tests for IPv6 backend selection, precedence, VPC preservation, and address formatting.
deploy/chart/templates/daemonset.yaml	Wires Helm values to pass the new controller flag.
deploy/chart/values.yaml	Documents the new Helm value for enabling IPv6 backends.
docs/configuration/loadbalancer.md	Documents IPv6 backend behavior and recommended dual-stack Service setup.
docs/configuration/environment.md	Documents the new controller flag and its implications.
docs/configuration/annotations.md	Documents the new Service annotation and behavior.
e2e/test/lb-with-ipv6-backends/create-pods-services.yaml	Adds a dual-stack Service + backend deployment for e2e coverage.
e2e/test/lb-with-ipv6-backends/chainsaw-test.yaml	Adds an e2e Chainsaw scenario validating IPv6 backend node addresses and reachability.
devbox.json	Pins clusterctl to a specific version for devbox shells.
devbox.lock	Updates locked devbox package metadata for the new clusterctl pin.
Makefile	Pins/installs clusterctl, updates CAP* versions, and adjusts e2e cluster generation for dual-stack.
.gitignore	Ignores locally generated cluster manifests/kubeconfigs and related artifacts.