Skip to main content
Talos node state is fully defined by machine configuration. Initial configuration is delivered to the node at bootstrap time, but configuration can be updated while the node is running. There are three talosctl commands which facilitate machine configuration updates:
  • talosctl apply-config to apply configuration from the file
  • talosctl edit machineconfig to launch an editor with existing node configuration, make changes and apply configuration back
  • talosctl patch machineconfig to apply automated machine configuration via JSON patch
In Talos, machine configuration is always applied to the running node without a reboot. Each of these commands can operate in one of the following modes:
  • apply change immediately (default, --mode=auto or --mode=no-reboot): the new configuration is applied to the running node
  • apply change on next reboot (--mode=staged): change is staged to be applied after a reboot, but node is not rebooted
  • apply change with automatic revert (--mode=try): change is applied immediately (if not possible, returns an error), and reverts it automatically in 1 minute if no configuration update is applied
Note: applying change on next reboot (--mode=staged) doesn’t modify current node configuration, so next call to talosctl edit machineconfig --mode=staged will not see changes
The --mode=reboot option was removed in Talos 1.14, and --mode=interactive was removed in an earlier release. When a change does need a reboot (see below), reboot the node explicitly with talosctl reboot after applying the configuration. This keeps the reboot under your control, so it can be sequenced with cordoning and draining the node. Additionally, there is also talosctl get machineconfig v1alpha1 -o jsonpath='{.spec}', which retrieves the current node configuration API resource and return just the machine configuration in the .spec field. It can be used to modify the configuration locally before being applied to the node.

​
Changes which might need a reboot

Talos applies the new configuration to the running node, but a few settings are not fully picked up by a node which is already running, and need a reboot to take effect:
  • .cluster.etcd: the etcd service reads its settings — image, extra arguments, advertised and listen addresses — when it starts. Talos does not restart etcd on a configuration change, since restarting a control plane member is disruptive and is not something Talos does implicitly. Reboot the node to pick up the new settings:
  • Environment variables (EnvironmentConfig or .machine.env): Talos picks up the new values on the fly, but a service which is already running keeps the environment it was started with, so a variable consumed by a service only takes effect once that service restarts. Removing a variable from the configuration does not unset it on a running node either.
  • Kernel modules (KernelModuleConfig or .machine.kernel.modules): Talos loads modules which were added to the configuration, but it never unloads modules, and module parameters are only applied when the module is loaded for the first time. Removing a module, or changing the parameters of a module which is already loaded, has no effect until a reboot.
  • Volume encryption keys: the encryption section of a volume document is applied when the volume is unlocked, so rotating a key takes a reboot for the volume to be re-encrypted with the new key.
This list is not exhaustive: in general, a setting consumed by a long-running service only takes effect when that service restarts. Install configuration is a separate case: UnattendedInstallConfig and the deprecated .machine.install are only used during an install or an upgrade, so changing them has no effect on a node which is already installed — not even after a reboot.

​
talosctl apply-config

This command is traditionally used to submit initial machine configuration generated by talosctl gen config to the node. It can also be used to apply configuration to running nodes. The initial YAML for this is typically obtained using talosctl get machineconfig v1alpha1 -o jsonpath='{.spec}' > machineconfig.yaml. Example:
Command apply-config can also be invoked as apply machineconfig:
Staging the machine configuration to be applied on the next reboot:
Note: when a Talos node is running in the maintenance mode it’s necessary to provide --insecure (-i) flag to connect to the API and apply the config.

​
talosctl edit machineconfig

Command talosctl edit loads current machine configuration from the node and launches configured editor to modify the config. If config hasn’t been changed in the editor (or if updated config is empty), update is not applied.
Note: Talos uses environment variables TALOS_EDITOR, EDITOR to pick up the editor preference. If environment variables are missing, vi editor is used by default.
Example:
Configuration can be edited for multiple nodes if multiple IP addresses are specified:
Staging the machine configuration change to be applied on the next reboot:

​
talosctl patch machineconfig

Command talosctl patch works similar to talosctl edit command - it loads current machine configuration, but instead of launching configured editor it applies a set of patches to the configuration and writes the result back to the node. Example, updating kubelet version by patching the KubeletConfig document: Updating kube-apiserver version via the KubeAPIServerConfig document, reverting the change automatically if it is not confirmed within a minute: A patch might be applied to multiple nodes when multiple IPs are specified:
Patches can also be sourced from files using file (or @file) syntax, which is usually more readable for document patches:

​
Recover from node boot failures

If a Talos node fails to boot because of wrong configuration (for example, control plane endpoint is incorrect), configuration can be updated to fix the issue.