Talosctl
@dataverket/talosctlv2026.10.27.1
01README
Talos Linux machines for swamp, through talosctl, with or without Omni.
One model type, @dataverket/talosctl/node, targets one or many nodes: version, services, etcd members and status, service logs, top processes, the cluster kubeconfig, apply and patch machine config, bootstrap, reboot, shutdown, reset (whole system disk or only named partitions such as EPHEMERAL), upgrade, and the cluster health check. Every method but health takes nodes, a subset of the definition's targets, so a fleet definition can reboot one machine; etcd and health go only to control planes. volumes reads every node's disks, partitions by label, unallocated space on the system disk and how full EPHEMERAL is, in one execution, so a plan for user volumes starts from measured numbers.
Forked from @magistr/talos-node (MIT) and typed. For an Omni-managed fleet, @dataverket/omni supplies the node addresses and a minted talosconfig as data; this model takes the config as content (talosconfigContent) and speaks to the machines through Omni's proxy, so a lab cluster on plain talosctl and a managed one share one code path. A definition names its own context (talosContext) and its own Omni key, either as a file read at call time (serviceAccountKeyFile) or as a vaulted value (serviceAccountKey), so nothing depends on which context was selected last.
02Behaviors
@dataverket/talosctl/nodev2026.09.30.1node.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| endpoint? | string | Talos API endpoint (--endpoints); also the default node. Leave unset with an Omni talosconfig |
| nodes? | array | Node addresses the methods target (--nodes); defaults to [endpoint] |
| talosconfig? | string | Path to a talosconfig; defaults to talosctl's own lookup |
| talosContext? | string | Context in the talosconfig to use (--context), e.g. the cluster's name; without it talosctl uses the config's current context, which is whatever was selected last |
| talosconfigContent? | string | A talosconfig\ |
| insecure? | boolean | Use --insecure (maintenance mode, no client certificate) |
| talosctlPath? | string | Path to the talosctl binary; override when it is not on PATH |
| serviceAccountKeyFile? | string | Path to a file holding the Omni service-account key, read at call time, e.g. ~/.talos/omni/<name>.key, for a key an operator's session writes and rotates; the path is not a secret, so the definition carries no value |
| serviceAccountKey? | string | Omni service-account key for an Omni-issued talosconfig (OMNI_SERVICE_ACCOUNT_KEY) as a value, for a key the process owns; supply via a vault expression. Mutually exclusive with serviceAccountKeyFile |
| retryDelayMs? | number | Pause between retries of transient API errors |
fn version()
Read the Talos version of every targeted node
fn services()
List every service on every targeted node
fn etcdMembers()
List the etcd cluster members, as one control plane among the targets sees them; the first that answers is asked
fn etcdStatus()
The etcd status of every control plane among the targets: member, leader, raft index and term, database size, errors. One etcdStatus per control plane; one that does not answer, and any target that cannot say what kind of machine it is, is recorded as unreachable, so a stale healthy record never outlives a node that went down. Read-only.
fn serviceLogs(service: string, tail?: number, match?: string, sinceSeconds?: number, keep?: number)
The last lines of one service's log on every targeted node, with how many fall inside a time window and match a pattern. One serviceLog per node; a node where the service does not exist is skipped. Read-only.
| Argument | Type | Description |
|---|---|---|
| service | string | Talos service or container log, e.g. etcd, kubelet, apid |
| tail? | number | How many of the newest lines to read |
| match? | string | Regular expression; only matching lines are counted as matched and kept |
| sinceSeconds? | number | Count only lines whose own timestamp is this recent; lines without one are counted |
| keep? | number | How many of the newest matching lines to store |
fn processes(sort?: enum, top?: number)
The top processes of every targeted node by CPU time or resident memory. One processes record per node, holding each process's executable but never its arguments. Read-only.
| Argument | Type | Description |
|---|---|---|
| sort? | enum | |
| top? | number |
fn kubeconfig()
Retrieve the cluster kubeconfig
fn volumes()
For every targeted node: disks, partitions (STATE, EPHEMERAL, u-<name>, ...), unallocated bytes on the system disk, and /var usage. One volumeLayout per node, one execution. Read-only.
fn applyConfig(configFile: string, mode?: enum, insecure?: boolean)
Apply a machine config (insecure=true for maintenance mode)
| Argument | Type | Description |
|---|---|---|
| configFile | string | Path to the machine config YAML file |
| mode? | enum | |
| insecure? | boolean | Override the global insecure flag (maintenance mode) |
fn bootstrap()
Bootstrap etcd (run once, against the first control plane)
fn reboot(mode?: enum)
Reboot the targeted nodes; give nodes to reboot fewer than all of them, e.g. one control plane at a time
| Argument | Type | Description |
|---|---|---|
| mode? | enum |
fn shutdown(force?: boolean)
Shut down the targeted nodes
| Argument | Type | Description |
|---|---|---|
| force? | boolean |
fn reset(graceful?: boolean, reboot?: boolean, systemLabelsToWipe?: array)
Reset the targeted nodes: wipe the system disk, or only the named partitions
| Argument | Type | Description |
|---|---|---|
| graceful? | boolean | Cordon, drain and leave etcd first |
| reboot? | boolean | Reboot after the reset instead of shutting down |
| systemLabelsToWipe? | array | Wipe only these system partitions (e.g. [EPHEMERAL]); keeps STATE and the config |
fn upgrade(image: string, preserve?: boolean)
Upgrade Talos on the targeted nodes
| Argument | Type | Description |
|---|---|---|
| image | string | Installer image, e.g. ghcr.io/siderolabs/installer:v1.14.1 |
| preserve? | boolean | Preserve ephemeral data |
fn patchConfig(patchFile: string, mode?: enum)
Patch the machine config with a YAML patch file
| Argument | Type | Description |
|---|---|---|
| patchFile | string | Path to the YAML patch file |
| mode? | enum |
fn health(node?: string, waitTimeout?: string)
Run the cluster health check from one control plane: the given node, or the first control plane among the targets. Through Omni's proxy the etcd check needs more than a Reader identity; Omni reports cluster health itself
| Argument | Type | Description |
|---|---|---|
| node? | string | The control plane to run the check from; must be one of the targets |
| waitTimeout? | string | How long to wait for the check to pass, e.g. 30s, 2m |
Resources
version(infinite)— Talos version of one node
service(infinite)— State and health of one Talos service on one node
etcdMember(infinite)— One etcd cluster member
kubeconfig(infinite)— The cluster's admin kubeconfig
volumeLayout(30d)— Disks, partitions by label, unallocated space and EPHEMERAL usage of one node
result(infinite)— Outcome of a lifecycle or config operation
etcdStatus(30d)— One control plane's etcd member: leader, raft indexes, database size, errors
serviceLog(7d)— The recent lines of one service on one node, with counts in a time window
processes(7d)— The top processes of one node by CPU time or memory
03Previous Versions
2026.09.30.1
Modified 1 behaviors
2026.09.29.3
2026.09.29.2
2026.09.29.1
2026.09.19.2
2026.09.19.1
04Stats
A
100 / 100
Downloads
36
Archive size
46.3 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
05Platforms
06Labels