Talos Native Patches Migration

KSail is shifting to a patch-first model for Talos clusters. Several ksail.yaml fields that previously generated Talos machine config patches at runtime are now deprecated. Users should manage these patches directly in their talos/ patch directories.

This gives you:

Full control over Talos machine configuration
Transparency — you see exactly what patches are applied
Access to all Talos config options, not just what KSail exposes
Better compatibility with Talos documentation and community resources

Deprecated Fields

Deprecated Field	Replacement	Generated By Init
`spec.cluster.cdi`	`talos/cluster/disable-cdi.yaml`	✅
`spec.cluster.oidc.*`	`talos/cluster/oidc.yaml`	✅
`spec.provider.hetzner.ingressFirewall`	`talos/cluster/` + role-specific patches	✅
`spec.cluster.talos.imageVerification`	`talos/cluster/image-verification.yaml`	✅

Not deprecated (these are KSail orchestration concerns, not patch wrappers):

spec.cluster.talos.version — pins Talos OS version
spec.cluster.talos.extensions — Image Factory integration
spec.cluster.talos.extraPortMappings — Docker provider concern
spec.cluster.cni — Helm install/uninstall (Kubernetes-level)
spec.cluster.metricsServer — Helm install/uninstall (Kubernetes-level)

Migration Steps

CDI

Remove spec.cluster.cdi from ksail.yaml. If you need CDI disabled, ensure talos/cluster/disable-cdi.yaml exists (created by ksail project init):

machine:
  features:
    enableCDI: false

To enable CDI (Talos 1.13+ default), simply delete this patch file.

OIDC

Remove spec.cluster.oidc.* from ksail.yaml. Manage OIDC configuration directly in talos/cluster/oidc.yaml (created by ksail project init --oidc-issuer-url=...).

See Talos OIDC docs for the full patch format.

Ingress Firewall

Remove spec.provider.hetzner.ingressFirewall from ksail.yaml. The firewall patches are scaffolded by ksail project init in:

talos/cluster/ingress-firewall-default-action.yaml
talos/control-planes/ingress-firewall-rules.yaml
talos/workers/ingress-firewall-rules.yaml

To disable the firewall, delete these patch files.

See Talos Ingress Firewall docs.

Image Verification

Remove spec.cluster.talos.imageVerification from ksail.yaml. Add an ImageVerificationConfig document directly to talos/cluster/image-verification.yaml.

See Talos Image Verification docs.

Patch Directory Structure

talos/
├── cluster/              # Applied to ALL nodes
│   ├── allow-scheduling-on-control-planes.yaml
│   ├── disable-cdi.yaml
│   ├── disable-default-cni.yaml
│   ├── oidc.yaml
│   ├── ingress-firewall-default-action.yaml
│   └── image-verification.yaml
├── control-planes/       # Applied to control-plane nodes only
│   └── ingress-firewall-rules.yaml
└── workers/              # Applied to worker nodes only
    └── ingress-firewall-rules.yaml

How KSail Handles Patches

When you run ksail cluster update, KSail:

Loads all patches from the talos/ directory
Compares the resulting config against the running cluster
Classifies changes by impact:
- In-place — applied without reboot (registries, kubelet args, API server config)
- Reboot-required — applied with rolling reboot (CNI changes, machine features)
- Wipe-required — requires partition wipe (disk encryption migration)
Applies changes using the appropriate Talos SDK mode

Talos 1.14 Kubernetes Patch Migration

When generating a Talos 1.14 or newer configuration, KSail converts supported legacy cluster.apiServer settings into native Kubernetes configuration documents. Patches for older Talos version contracts keep their original content.

Files are applied in filename order within each directory. Shared cluster/ patches are applied before control-planes/ and workers/ patches, including shared patches supplied at runtime. Documents separated by --- are applied in their original order as separate patches, so repeated API-server settings follow Talos’s native merge rules.

Legacy OIDC flags may be split across files or documents in the same scope. KSail resolves the complete issuer, client, claim mappings, and CA before emitting structured authentication. Role patches override shared settings without changing the other role. A shared OIDC configuration must be complete on its own; put settings intended only for control planes together in control-planes/.

Some layouts require an explicit conversion:

RFC 6902 YAML or JSON lists: Talos cannot apply these to its multi-document configuration. Convert them to strategic-merge Talos configuration documents. KSail reports the source file during migration, including for operations on unrelated fields.
YAML aliases in multi-document files: expand aliases to explicit values before migration so each resulting patch is self-contained.
Mixed authentication formats: consolidate legacy OIDC flags and an explicit KubeAuthenticationConfig into one structured configuration.
OIDC CA appends or deletions: provide the complete CA as literal file content using create or overwrite. KSail cannot resolve a CA from existing machine state. An empty final CA does not fall back to earlier content.
Deletion selectors overlapping OIDC: consolidate the remaining authentication settings before migration. Multi-key list deletions in a legacy document being converted must be moved to a separate strategic-merge patch to preserve their selector. When OIDC references a CA file, a deletion selected only by another file’s path is preserved. Deletions of the CA, the whole file list, or the machine remain unsupported, as do selectors without a path or with additional selector fields.

Backward Compatibility

Deprecated fields continue to work. When a deprecated field is set:

KSail emits a deprecation warning during config loading
If the corresponding patch file exists on disk, the patch file takes precedence
If no patch file exists, KSail injects the patch at runtime (current behavior)

There is no urgency to migrate — fields will be supported until a future major version.

Talos Disk Encryption Migration — rolling encryption migration guide
Talos Machine Configuration — upstream Talos config reference