[feat] Add support for new network interfaces

[AshleyDumaine]

NOTES:

• Depends on a new version of linodego that includes the changes in Project: Linode Interfaces linodego#735
• Docs and e2e tests are purposely excluded for now as this is a beta opt-in only feature. They will be included once the feature becomes GA.

---

What this PR does / why we need it: Linode Interfaces is in beta. This adds support so customers opted into the beta can make use of the feature in CAPL.

This adds 2 new fields to the LinodeMachine/LinodeMachineTemplate CRD:

• interfaceGeneration which defaults to legacy_config if omitted (to not break existing users), unless linodeInterfaces is defined, in which case it will default to linode (new interfaces). This field allows the user to omit both interfaces and linodeInterfaces while allowing the LM controller to know which generation to use for the LM's auto-provisioned interfaces.
• linodeInterfaces (various webhook validation rules have been added since this does not play well with certain settings like network helper, legacy interfaces, and private IPs)

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: If you want to test this locally you need to opt in to the Linode Interfaces beta.

TODOs:

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

---

Testing

PREREQUISITE: Opt in to the new network interfaces beta: https://cloud.linode.com/betas. Make sure once you do that you can list the "Linode Interfaces" capability via the linode-CLI:

linode-cli regions ls | grep "Linode Interfaces" | wc -l
31

You'll also want to disable the default network helper in your account settings.

1. make local-release
2. make local-deploy
3. clusterctl generate cluster test-cluster --kubernetes-version v1.31.8 --infrastructure local-linode:v0.0.0 > test-cluster.yaml
4. Replace the following for the LinodeMachineTemplate for test-cluster-md-0:

      interfaces:
        - purpose: public

with

      linodeInterfaces:
      - public:
          ipv4:
            addresses:
            - address: auto

(If you want to do this for the control-plane LMT, you will need the changes in #825 so the default cluster NB doesn't need private IPs which are not supported by the new interfaces. With this you only need to add interfaceGeneration: linode into the LMT spec for both the control plane and workers and can exclude defining interfaces / linodeInterfaces )
5. kubectl apply -f test-cluster.yaml
6. Verify the cluster eventually provisions successfully:

$ k get lm -A
NAMESPACE   NAME                               CLUSTER        STATE     READY   PROVIDERID          MACHINE
default     test-cluster-control-plane-zrbxg   test-cluster   running   true    linode://81841168   test-cluster-control-plane-zrbxg
default     test-cluster-md-0-tvn9g-qwvrv      test-cluster   running   true    linode://81841687   test-cluster-md-0-tvn9g-qwvrv
$ k get lm -A -o json | jq -r '.items[].spec'
{
  "firewallRef": {
    "apiVersion": "infrastructure.cluster.x-k8s.io/v1alpha2",
    "kind": "LinodeFirewall",
    "name": "test-cluster"
  },
  "image": "linode/ubuntu22.04",
  "interfaceGeneration": "linode",
  "privateIP": false,
  "providerID": "linode://81841168",
  "region": "us-sea",
  "type": "g6-standard-2",
  "vpcRef": {
    "apiVersion": "infrastructure.cluster.x-k8s.io/v1alpha2",
    "kind": "LinodeVPC",
    "name": "test-cluster"
  }
}
{
  "firewallRef": {
    "apiVersion": "infrastructure.cluster.x-k8s.io/v1alpha2",
    "kind": "LinodeFirewall",
    "name": "test-cluster"
  },
  "image": "linode/ubuntu22.04",
  "interfaceGeneration": "linode",
  "privateIP": false,
  "providerID": "linode://81841687",
  "region": "us-sea",
  "type": "g6-standard-2",
  "vpcRef": {
    "apiVersion": "infrastructure.cluster.x-k8s.io/v1alpha2",
    "kind": "LinodeVPC",
    "name": "test-cluster"
  }
}
$ clusterctl describe cluster test-cluster
NAME                                                             READY  SEVERITY  REASON             SINCE  MESSAGE
Cluster/test-cluster                                             True                                5m17s
├─ClusterInfrastructure - LinodeCluster/test-cluster             True             LoadBalancerReady  9m59s
├─ControlPlane - KubeadmControlPlane/test-cluster-control-plane  True                                5m17s
│ └─Machine/test-cluster-control-plane-zrbxg                     True                                8m24s
└─Workers
  └─MachineDeployment/test-cluster-md-0                          True                                97s
    └─Machine/test-cluster-md-0-tvn9g-qwvrv                      True                                3m43s

[codecov]

Codecov Report

❌ Patch coverage is 67.17850% with 171 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.46%. Comparing base (dbfb8e6) to head (265d4f0).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...nal/controller/linodemachine_controller_helpers.go	65.30%	134 Missing and 19 partials ⚠️
internal/controller/linodemachine_controller.go	60.86%	15 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #821      +/-   ##
==========================================
+ Coverage   63.44%   63.46%   +0.01%     
==========================================
  Files          71       71              
  Lines        7414     7833     +419     
==========================================
+ Hits         4704     4971     +267     
- Misses       2435     2570     +135     
- Partials      275      292      +17     

☔ 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.

[komer3]

nit: could we use replace for getting the specific linodego dep instead of doing it here? I feel like that makes it easier to understand we are using specific version for a reason. Thoughts?

[AshleyDumaine]

just noticed we're doing that on the CCM but there's no comment explaining why the replace is needed. I'm fine with doing that

[Copilot]

Pull Request Overview

This PR adds support for Linode's new network interfaces feature (currently in beta), introducing a new network interface configuration approach while maintaining compatibility with existing legacy interfaces. The key changes include adding a new linodeInterfaces field and interfaceGeneration parameter to control which interface generation is used.

Key changes:

• Adds linodeInterfaces field to LinodeMachine/LinodeMachineTemplate CRDs for the new network interface generation
• Introduces interfaceGeneration field to control which interface type to use (defaults to "legacy_config")
• Updates controller logic to handle both legacy and new interface configurations with proper validation

Reviewed Changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
api/v1alpha2/linodemachine_types.go	Adds new LinodeInterface types and interfaceGeneration field to support beta network interfaces
internal/controller/linodemachine_controller_helpers.go	Implements dual interface support logic with generation-aware configuration
internal/controller/linodemachine_controller.go	Updates reconciliation logic to handle new interface generation and firewall management
internal/webhook/v1alpha2/linodemachine_webhook.go	Adds validation rules preventing incompatible combinations of new interfaces with legacy features
config/crd/bases/*.yaml	Updates CRD definitions to include new interface fields and validation
templates/infra/linodeMachineTemplate.yaml	Adds commented examples and warnings about new interface usage
clients/clients.go	Adds LinodeInterfacesClient interface for new API methods
mock/client.go	Adds mock implementations for new interface-related API calls

Comments suppressed due to low confidence (2)

internal/controller/linodemachine_controller_helpers.go:768

• Missing assignment for the Address field. The code sets NAT1To1Address to "auto" but doesn't set Address, which is required according to the struct definition.

	}

internal/controller/linodemachine_controller_helpers.go:277

• The buildInstanceAddrs function has been modified to call handleVlanIps, but this introduces code duplication. The VLAN IP handling logic appears twice - once in the new handleVlanIps function and once inline in the existing code. Consider consolidating this logic.

	}

[komer3]

The PR looks good to me! Once linode interfaces become GA (out of beta), we should create a flavor for it and add e2e tests.

[marcoderama]

I'm struggling to parse that. Should that be "...for the cluster's nodes IF interface / linodeInterface are not specified for a LinodeMachine"? If not, I'm not sure what it means. But then again, I don't really know what I'm talking about in this domain...

Feel free to resolve this comment into oblivion.