feat: implement KubeSpan multi-document configuration #12504

pranav767 · 2025-12-28T00:00:53Z

Resolves #12437

Pull Request

What? (description)

Add KubeSpanConfigV1Alpha1 document type with registry support
Implement container aggregation with wrapper pattern
Deprecate .machine.network.kubespan v1alpha1 path

Why? (reasoning)

Making/applying config for kubespan easier,
instead of the current scenario which requires:

machine:
    network:
        nameservers:
            - 9.8.7.6
            - 8.7.6.5
        searchDomains:
            - example.org
            - example.com

        # # Configures KubeSpan feature.
        # kubespan:
        #     enabled: true # Enable the KubeSpan feature.

We can have independent config for Kubespan like:

apiVersion: v1alpha1
kind: KubeSpanConfig
enabled: true
advertiseKubernetesNetworks: false
allowDownPeerBypass: false
mtu: 1420

Few more Points for my own sanity:

The issue talks about deprecate and hide fully .machine.network. , but this still supports the previous config way, this just extends and gives priority to the multi-document config way for Kubespan.
Created pkg/machinery/config/types/network/kubespan.go which reads yaml and creates KubeSpanConfigV1Alpha1 (struct) with all values and implements all interfaces.
Updated container logic in pkg/machinery/config/container/container.go to use a wrapper-in-wrapper pattern instead of just returning container.v1alpha1Config.Machine() helps to intercept controller call on container.Machine().Network().KubeSpan() and use the desired (new multi-doc config) from container.documents
make generate Created json and copy stuff.
There is one confusing bit which I feel should be changed, from docs we have params as

enabled
advertiseKubernetesNetworks
allowDownPeerBypass
harvestExtraEndpoints
mtu
filters

and following above pattern we have such structs, but https://github.com/siderolabs/talos/blob/main/api/resource/definitions/kubespan/kubespan.proto has

// ConfigSpec describes KubeSpan configuration..
message ConfigSpec {
  bool enabled = 1;
  string cluster_id = 2;
  string shared_secret = 3;
  **bool force_routing = 4;**
  bool advertise_kubernetes_networks = 5;
  uint32 mtu = 6;
  repeated string endpoint_filters = 7;
  bool harvest_extra_endpoints = 8;
  repeated common.NetIPPort extra_endpoints = 9;
}

also the config for kubespan controller has
https://github.com/siderolabs/talos/blob/main/internal/app/machined/pkg/controllers/kubespan/config.go#L49
res.TypedSpec().ForceRouting = c.Machine().Network().KubeSpan().ForceRouting() forceRouting instead of allowDownPeerBypass,
which leads to https://github.com/siderolabs/talos/compare/main...pranav767:talos:feat/kubespan-multi-document-config?expand=1#diff-2f6f6aab6dbbcc38f191c5f752866e9d8d3dc787f0044c4eb9d7107ea7a1719dR170
Just feels a bit of inconsistency with the use of one parameter with 2 different names.

Acceptance

Please use the following checklist:

you linked an issue (if applicable)
you included tests (if applicable)
you ran conformance (make conformance)
you formatted your code (make fmt)
you linted your code (make lint)
you generated documentation (make docs)
you ran unit-tests (make unit-tests)

See make help for a description of the available targets.

smira · 2025-12-29T10:42:21Z

pkg/machinery/config/container/container.go

 }

+// machineConfigWrapper wraps MachineConfig to override Network().KubeSpan() with multi-doc aggregation.
+type machineConfigWrapper struct {


this approach doesn't scale well.

we have this pattern:

talos/pkg/machinery/config/container/container.go

Lines 326 to 341 in 1549521

// NetworkTimeSyncConfig implements config.Config interface.

func (container *Container) NetworkTimeSyncConfig() config.NetworkTimeSyncConfig {

// first check if we have a dedicated document

matching := findMatchingDocs[config.NetworkTimeSyncConfig](container.documents)

if len(matching) > 0 {

return matching[0]

}

// fallback to v1alpha1

if container.v1alpha1Config != nil {

return container.v1alpha1Config.NetworkTimeSyncConfig()

}

return nil

}

Removed the wrapper in wrapper pattern, and followed existing one. 👍

smira · 2025-12-29T10:43:35Z

pkg/machinery/config/types/network/kubespan.go

+// KubeSpanFiltersConfig configures KubeSpan endpoint filters.
+type KubeSpanFiltersConfig struct {
+	//   description: |
+	//     Filter node addresses which will be advertised as KubeSpan endpoints for peer-to-peer Wireguard connections.


this needs more configuration/examples

Updated 👍

smira · 2025-12-29T10:44:13Z

pkg/machinery/config/types/network/kubespan.go

+		return *s.ConfigMTU
+	}
+
+	return 1420


I think we had a constant for it.

yes, found it KubeSpanLinkMTU

smira · 2025-12-29T10:44:33Z

pkg/machinery/config/types/network/kubespan.go

+
+// Endpoints implements config.KubeSpanFilters interface.
+func (f *KubeSpanFiltersConfig) Endpoints() []string {
+	if f == nil {


this can be removed (nil slice is an empty slice).

removed 👍

smira · 2025-12-29T10:45:18Z

pkg/machinery/config/types/v1alpha1/v1alpha1_types.go

 }

 // NetworkConfig represents the machine's networking config values.
 type NetworkConfig struct {


we can now deprecate the whole .machine.network tree, so that it disappears from the docs (it's now empty as everything inside it is deprecated).

Updated with docgen: nodoc

smira

talosctl cluster create has --with-kubepsan option which should use new multi-doc for Talos >= 1.13 (need new config version contract flag)
KubeSpanConfigController should have a new testcase for enabling KubeSpan via new multi-doc

Migrate KubeSpan configuration to support multi-document format. Add version-aware support for talosctl cluster create and gen config. Uses multi-doc format for Talos 1.13+, legacy format for 1.12 and earlier. Signed-off-by: Pranav Patil <[email protected]>

pranav767 · 2025-12-29T20:16:27Z

@smira

There were two talosctl commands (talosctl cluster create and talosctl gen config) using --with-kubespan. Both have been updated to use the new multi-document configuration format for Talos ≥ 1.13.
KubeSpanConfigController now includes a new test case for the multi-config–style KubeSpan.

pranav767 · 2025-12-29T20:33:31Z

cmd/talosctl/cmd/mgmt/cluster/create/clusterops/configmaker/internal/makers/common.go

-		genOptions = slices.Concat(genOptions,
-			[]generate.Option{generate.WithNetworkOptions(
-				v1alpha1.WithKubeSpan(),
-			)},


I'm aware that we're migrating .machine.network to multi-document format, but I've kept legacy v1alpha1 config generation for Talos < 1.13 as previous versions can't parse new KubeSpanConfigV1Alpha1

github-project-automation bot added this to Planning Dec 28, 2025

github-project-automation bot moved this to To Do in Planning Dec 28, 2025

talos-bot moved this from To Do to In Review in Planning Dec 28, 2025

smira reviewed Dec 29, 2025

View reviewed changes

pranav767 force-pushed the feat/kubespan-multi-document-config branch from 045777a to bc95639 Compare December 29, 2025 20:11

pranav767 commented Dec 29, 2025

View reviewed changes

	// NetworkTimeSyncConfig implements config.Config interface.
	func (container *Container) NetworkTimeSyncConfig() config.NetworkTimeSyncConfig {
	// first check if we have a dedicated document
	matching := findMatchingDocs[config.NetworkTimeSyncConfig](container.documents)
	if len(matching) > 0 {
	return matching[0]
	}

	// fallback to v1alpha1
	if container.v1alpha1Config != nil {
	return container.v1alpha1Config.NetworkTimeSyncConfig()
	}

	return nil
	}

Uh oh!

feat: implement KubeSpan multi-document configuration #12504

Are you sure you want to change the base?

feat: implement KubeSpan multi-document configuration #12504

Conversation

pranav767 commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

What? (description)

Why? (reasoning)

Acceptance

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smira left a comment

Choose a reason for hiding this comment

Uh oh!

pranav767 commented Dec 29, 2025

Uh oh!

pranav767 Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pranav767 commented Dec 28, 2025 •

edited

Loading

pranav767 Dec 29, 2025 •

edited

Loading