docs: add information on how config patches work#602
Conversation
|
|
||
| - **Cluster** — applies to every machine in the cluster. Use for settings that should be uniform everywhere: registry mirrors, cluster DNS, KubeSpan. | ||
| - **Machine Set** — applies to every machine in a specific machine set, such as all control-plane nodes or all GPU workers. Use for role-specific configuration. | ||
| - **Machine** — applies to one specific machine. Use for per-machine settings like a static IP or a unique hostname. |
There was a problem hiding this comment.
There are more scopes for the node level:
ClusterMachine and Machine.
ClusterMachineconfig patch is deleted when you delete the cluster.Machineconfig patch stays until you remove the machine from Omni completely. But it's not applied in maintenance mode.
There was a problem hiding this comment.
The priority of the patches is the following (from low to high):
Machine -> Cluster -> MachineSet -> ClusterMachine.
Inside the group the order is alphabetical. That's why we weight the patches by padded ints (000, 001, 400).
There was a problem hiding this comment.
@Unix4ever - let me make sure I'm understanding the model right.
Priority low→high: Machine → Cluster → MachineSet → ClusterMachine, alphabetical by padded-int ID prefix within each group. So a standalone Machine patch is the lowest (below cluster), while a ClusterMachine patch is the highest. Is that correct?
Follow-up question: when someone picks a specific machine from the Patch Target dropdown on a cluster and creates a patch there, is that a ClusterMachine patch (highest)? And is a Machine patch only what you get when you author against an unallocated machine that isn't in a cluster yet?
@Iheanacho-ai - If the above mapping holds, the everyday user-facing rule can stay close to "the more specific scope wins" (cluster → machine-set → the machine, in a cluster), with standalone Machine patches documented as a separate, lowest-priority baseline that a cluster overrides. If instead users routinely encounter both Machine and ClusterMachine as distinct choices for the same node, we need to teach the full four-scope ordering explicitly
| |---|---|---| | ||
| | Patch applied, value missing from merged config | Field is reserved by Omni, or patch is not scoped to this machine | [Talos Config Overrides](/omni/cluster-management/talos-config-overrides); check patch scope | | ||
| | Patch applied, value in merged config, machine ignores it | Field is silently dropped by Talos (e.g. `audit-log-*` under `apiServer.extraArgs`), or a Talos default is overriding it | Check Talos docs for whether the specific key is supported | | ||
| | Configuration broke after a Talos upgrade, no error surfaced | Field moved to a new document type; old syntax silently no-ops | Talos release notes for the version you upgraded to | |
| | Patch applied, value missing from merged config | Field is reserved by Omni, or patch is not scoped to this machine | [Talos Config Overrides](/omni/cluster-management/talos-config-overrides); check patch scope | | ||
| | Patch applied, value in merged config, machine ignores it | Field is silently dropped by Talos (e.g. `audit-log-*` under `apiServer.extraArgs`), or a Talos default is overriding it | Check Talos docs for whether the specific key is supported | | ||
| | Configuration broke after a Talos upgrade, no error surfaced | Field moved to a new document type; old syntax silently no-ops | Talos release notes for the version you upgraded to | | ||
| | Machine has a value you never set | Platform or cloud-init injection, or a Talos default (e.g. DHCP-assigned hostname) | Not visible in any patch list, exists outside Omni's authoring surface | |
There was a problem hiding this comment.
Cloud init injection will be gone as soon as you allocate the machine into a cluster.
Talos doesn't merge the configs from these sources: it's either full Talos config injected by apply-config call or it's the config loaded from talos.config kernel arg or cloud-init user-data.
| | Set cluster DNS | Configuration Patches or Cluster Templates | | | ||
| | Add a registry mirror | Configuration Patches or Cluster Templates | | | ||
| | Configure KubeSpan | Configuration Patches or Cluster Templates | | | ||
| | Sync a Kubernetes manifest | Configuration Patches or Cluster Templates | See [Sync Kubernetes Manifests](../cluster-management/sync-kubernetes-manifests). | |
There was a problem hiding this comment.
Oh, btw KubernetesManifestGroup is used for that. You don't use Configuration Patches for that. CLI way is Cluster Templates, that's correct.
It's not possible to set manifests in the UI now. I doubt we should have it there.
You can view them only
| |---|---|---| | ||
| | Set kubelet flags per role | Configuration Patches or Cluster Templates | One patch per machine set. | | ||
| | Set sysctls or kernel modules per role | Configuration Patches or Cluster Templates | Use cluster scope if uniform across all roles; machine set scope if role-specific. | | ||
| | Add a system extension to a specific role | `MachineExtensions` resource | Not a patch. Changing extensions re-images the machine. | |
There was a problem hiding this comment.
Wrong resource again and can be set on all levels: cluster, machine set, machine.
|
We need to add a note about |
Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Iheanacho-ai
force-pushed
the
config-omni
branch
from
784c3bf to
8ef3d87
Compare
6 participants
fixes #584