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 cluster 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 cluster 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 cluster 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

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