mirror of
https://github.com/siderolabs/talos.git
synced 2025-12-07 02:21:14 +01:00
fdbd380f60
See https://kubernetes.io/blog/2022/11/28/registry-k8s-io-faster-cheaper-ga/ Signed-off-by: Andrey Smirnov <andrey.smirnov@talos-systems.com>
160 lines
6.3 KiB
Markdown
160 lines
6.3 KiB
Markdown
---
|
|
title: "Editing Machine Configuration"
|
|
description: "How to edit and patch Talos machine configuration, with reboot, immediately, or stage update on reboot."
|
|
aliases:
|
|
- ../../guides/editing-machine-configuration
|
|
---
|
|
|
|
Talos node state is fully defined by [machine configuration]({{< relref "../../reference/configuration" >}}).
|
|
Initial configuration is delivered to the node at bootstrap time, but configuration can be updated while the node is running.
|
|
|
|
> Note: Be sure that config is persisted so that configuration updates are not overwritten on reboots.
|
|
> Configuration persistence was enabled by default since Talos 0.5 (`persist: true` in machine configuration).
|
|
|
|
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
|
|
|
|
Each of these commands can operate in one of four modes:
|
|
|
|
* apply change in automatic mode(default): reboot if the change can't be applied without a reboot, otherwise apply the change immediately
|
|
* apply change with a reboot (`--mode=reboot`): update configuration, reboot Talos node to apply configuration change
|
|
* apply change immediately (`--mode=no-reboot` flag): change is applied immediately without a reboot, fails if the change contains any fields that can not be updated without a reboot
|
|
* apply change on next reboot (`--mode=staged`): change is staged to be applied after a reboot, but node is not rebooted
|
|
* apply change in the interactive mode (`--mode=interactive`; only for `talosctl apply-config`): launches TUI based interactive installer
|
|
|
|
> 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
|
|
|
|
Additionally, there is also `talosctl get machineconfig`, which retrieves the current node configuration API resource and contains the machine configuration in the `.spec` field.
|
|
It can be used to modify the configuration locally before being applied to the node.
|
|
|
|
The list of config changes allowed to be applied immediately in Talos {{< release >}}:
|
|
|
|
* `.debug`
|
|
* `.cluster`
|
|
* `.machine.time`
|
|
* `.machine.certCANs`
|
|
* `.machine.install` (configuration is only applied during install/upgrade)
|
|
* `.machine.network`
|
|
* `.machine.nodeLabels`
|
|
* `.machine.sysfs`
|
|
* `.machine.sysctls`
|
|
* `.machine.logging`
|
|
* `.machine.controlplane`
|
|
* `.machine.kubelet`
|
|
* `.machine.pods`
|
|
* `.machine.kernel`
|
|
* `.machine.registries` (CRI containerd plugin will not pick up the registry authentication settings without a reboot)
|
|
* `.machine.features.kubernetesTalosAPIAccess`
|
|
|
|
### `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 -o yaml | yq eval .spec >machs.yaml`.
|
|
(We must use [`yq`](https://github.com/mikefarah/yq) because for historical reasons, `get` returns the configuration as a full resource, while `apply-config` only accepts the raw machine config directly.)
|
|
|
|
Example:
|
|
|
|
```bash
|
|
talosctl -n <IP> apply-config -f config.yaml
|
|
```
|
|
|
|
Command `apply-config` can also be invoked as `apply machineconfig`:
|
|
|
|
```bash
|
|
talosctl -n <IP> apply machineconfig -f config.yaml
|
|
```
|
|
|
|
Applying machine configuration immediately (without a reboot):
|
|
|
|
```bash
|
|
talosctl -n IP apply machineconfig -f config.yaml --mode=no-reboot
|
|
```
|
|
|
|
Starting the interactive installer:
|
|
|
|
```bash
|
|
talosctl -n IP apply machineconfig --mode=interactive
|
|
```
|
|
|
|
> 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.
|
|
|
|
### `taloctl 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:
|
|
|
|
```bash
|
|
talosctl -n <IP> edit machineconfig
|
|
```
|
|
|
|
Configuration can be edited for multiple nodes if multiple IP addresses are specified:
|
|
|
|
```bash
|
|
talosctl -n <IP1>,<IP2>,... edit machineconfig
|
|
```
|
|
|
|
Applying machine configuration change immediately (without a reboot):
|
|
|
|
```bash
|
|
talosctl -n <IP> edit machineconfig --mode=no-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 [JSON patches](http://jsonpatch.com/) to the configuration and writes the result back to the node.
|
|
|
|
Example, updating kubelet version (in auto mode):
|
|
|
|
```bash
|
|
$ talosctl -n <IP> patch machineconfig -p '[{"op": "replace", "path": "/machine/kubelet/image", "value": "ghcr.io/siderolabs/kubelet:v{{< k8s_release >}}"}]'
|
|
patched mc at the node <IP>
|
|
```
|
|
|
|
Updating kube-apiserver version in immediate mode (without a reboot):
|
|
|
|
```bash
|
|
$ talosctl -n <IP> patch machineconfig --mode=no-reboot -p '[{"op": "replace", "path": "/cluster/apiServer/image", "value": "registry.k8s.io/kube-apiserver:v{{< k8s_release >}}"}]'
|
|
patched mc at the node <IP>
|
|
```
|
|
|
|
A patch might be applied to multiple nodes when multiple IPs are specified:
|
|
|
|
```bash
|
|
talosctl -n <IP1>,<IP2>,... patch machineconfig -p '[{...}]'
|
|
```
|
|
|
|
Patches can also be sourced from files using `@file` syntax:
|
|
|
|
```bash
|
|
talosctl -n <IP> patch machineconfig -p @kubelet-patch.json -p @manifest-patch.json
|
|
```
|
|
|
|
It might be easier to store patches in YAML format vs. the default JSON format.
|
|
Talos can detect file format automatically:
|
|
|
|
```yaml
|
|
# kubelet-patch.yaml
|
|
- op: replace
|
|
path: /machine/kubelet/image
|
|
value: ghcr.io/siderolabs/kubelet:v{{< k8s_release >}}
|
|
```
|
|
|
|
```bash
|
|
talosctl -n <IP> patch machineconfig -p @kubelet-patch.yaml
|
|
```
|
|
|
|
### Recovering 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.
|