[feat] Add Support for VPC only backends

[komer3]

Summary

Feature-flagged support for VPC-scoped NodeBalancer backends. When enabled, control plane backends use VPC internal IPs and the NodeBalancer is created inside the target VPC. External traffic continues to egress via VPC NAT with a public IP.

Key changes

• API: Add spec.network.enableVPCBackends (default false, immutable). When true and either spec.VPCRef or spec.VPCID is set, create the NodeBalancer in the VPC and prefer VPC backend IPs. Optional spec.network.nodeBalancerBackendIPv4Range is honored if provided.
• Services:
  • New helpers: ShouldUseVPC(scope) and DetermineAPIServerLBPort(scope).
  • NodeBalancer creation uses VPC SubnetID and optional IPv4Range; backend registration prefers VPC internal IPs, falls back to Linode private IPs when the flag is disabled.
• Controller: getIPPortCombo now prefers VPC IPs when enabled; factored helpers to select IPs and compose port pairs; DNS endpoint now reuses DetermineAPIServerLBPort.
• CRDs & Docs: CRDs extended with enableVPCBackends (default false, immutable); docs updated accordingly.

Decisions

• Backwards-compatible: default behavior unchanged unless enableVPCBackends is explicitly set to true.
• Template updates (including CCM changes) are intentionally excluded from this PR and will be proposed in a separate templates-only PR. Here is the draft PR: [feat] Templating changes to enable VPC only backend by default #825

What this PR does / why we need it:

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #

Special notes for your reviewer:

TODOs:

• squashed commits
• includes documentation
• adds unit tests
• adds or updates e2e tests

[rahulait]

I didn't realize we had added NB-VPC support in CAPL but with fixed /30 ranges and just needed to make it enabled by default.

Do we need changes in machinecontroller to consume the new changes in machineTemplate? Not sure how they are being used based on the current state of the PR.

[komer3]

I didn't realize we had added NB-VPC support in CAPL but with fixed /30 ranges and just needed to make it enabled by default.

Do we need changes in machinecontroller to consume the new changes in machineTemplate? Not sure how they are being used based on the current state of the PR.

Yup. We added these changes few months back I think.

As for machinecontroller, we don't need to update anything. Just setting privateIP to false and removing public interface does the job!

Here is a sample linode deployed with those settings:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.22%. Comparing base (6e6db1b) to head (8fb3e11).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #803      +/-   ##
==========================================
+ Coverage   63.20%   63.22%   +0.01%     
==========================================
  Files          71       71              
  Lines        7359     7363       +4     
==========================================
+ Hits         4651     4655       +4     
  Misses       2435     2435              
  Partials      273      273              

☔ 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

This PR introduces VPC-only backend support for the Cluster API Provider Linode (CAPL), removing the requirement for public/private IPs on nodes. The changes enable cluster communication exclusively through VPC networks while supporting external traffic through VPC NAT with public IPs.

Key changes include:

• Addition of EnableVPCBackends field to toggle VPC-scoped NodeBalancer creation and VPC backend IP usage
• Refactoring of IP selection logic to prioritize VPC IPs over traditional private IPs when VPC backends are enabled
• Simplification of NodeBalancer VPC creation conditions to check VPC references before IPv4 range requirements

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
api/v1alpha2/linodecluster_types.go	Adds EnableVPCBackends field to NetworkSpec with immutable validation
cloud/services/loadbalancers.go	Introduces helper functions and simplifies VPC NodeBalancer creation logic
internal/controller/linodecluster_controller_helpers.go	Refactors IP selection logic to prioritize VPC IPs when enabled
config/crd/bases/*.yaml	Updates CRDs with new EnableVPCBackends field and validation rules
cloud/services/loadbalancers_test.go	Updates test cases to include new EnableVPCBackends field
internal/controller/linodecluster_controller_test.go	Adds SubnetID to test data and mock call expectations
internal/controller/linodecluster_controller_helpers_test.go	Updates test cases with EnableVPCBackends field
docs/src/reference/out.md	Documents the new EnableVPCBackends field
hack/generate-flavors.sh	Updates flavor generation log message

Comments suppressed due to low confidence (1)

internal/controller/linodecluster_controller_helpers.go:139

• [nitpick] The variable name results could be more descriptive, such as ipPortCombos or portCombinations to better reflect its purpose.

	results = append(results, fmt.Sprintf("%s:%d", ip, apiServerLBPort))

[AshleyDumaine]

LGTM