MachineService API - Talos Linux

Overview

The MachineService provides the primary API for managing individual Talos nodes. It includes methods for configuration, lifecycle management, monitoring, and file operations.

service MachineService {
  rpc ApplyConfiguration(ApplyConfigurationRequest) returns (ApplyConfigurationResponse);
  rpc Bootstrap(BootstrapRequest) returns (BootstrapResponse);
  rpc Containers(ContainersRequest) returns (ContainersResponse);
  rpc Copy(CopyRequest) returns (stream common.Data);
  rpc Reboot(RebootRequest) returns (RebootResponse);
  rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
  rpc Upgrade(UpgradeRequest) returns (UpgradeResponse);
  // ... and many more
}

Configuration Management

ApplyConfiguration

Applies a new machine configuration to the node.

data

bytes

required

Complete machine configuration as YAML bytes

mode

Mode

default:"AUTO"

Application mode:

REBOOT: Apply config and reboot immediately
AUTO: Automatically determine if reboot is needed
NO_REBOOT: Apply without rebooting (may require manual reboot)
STAGED: Stage configuration for next reboot
TRY: Try configuration with automatic rollback

dry_run

bool

default:"false"

Validate configuration without applying

try_mode_timeout

Duration

Timeout for TRY mode before automatic rollback (default: 60s)

Response:

metadata

Metadata

Standard response metadata with hostname

warnings

string[]

Configuration validation warnings

mode

Mode

Actual mode used for applying configuration

mode_details

string

Human-readable explanation of the mode selection

Example:

import (
    "github.com/siderolabs/talos/pkg/machinery/api/machine"
)

configData, _ := os.ReadFile("machine-config.yaml")

resp, err := client.ApplyConfiguration(ctx, &machine.ApplyConfigurationRequest{
    Data: configData,
    Mode: machine.ApplyConfigurationRequest_AUTO,
})

for _, msg := range resp.Messages {
    fmt.Printf("Applied on %s with mode %s\n", msg.Metadata.Hostname, msg.Mode)
    for _, warning := range msg.Warnings {
        fmt.Printf("Warning: %s\n", warning)
    }
}

System Lifecycle

Reboot

Reboots the node.

mode

RebootMode

default:"DEFAULT"

Reboot mode:

DEFAULT: Graceful reboot
POWERCYCLE: Force power cycle
FORCE: Skip graceful shutdown

Response:

metadata

Metadata

Standard response metadata

actor_id

string

ID of the request initiator

Example:

resp, err := client.Reboot(ctx, &machine.RebootRequest{
    Mode: machine.RebootRequest_DEFAULT,
})

Shutdown

Shuts down the node.

force

bool

default:"false"

Skip cordoning and draining before shutdown

Response:

metadata

Metadata

Standard response metadata

actor_id

string

ID of the request initiator

Example:

talosctl shutdown -n 10.0.0.1

Upgrade

Upgrades Talos to a new version.

image

string

required

Talos installer image (e.g., ghcr.io/siderolabs/installer:v1.7.0)

preserve

bool

default:"false"

Preserve ephemeral data (not recommended)

stage

bool

default:"false"

Stage upgrade for next reboot

force

bool

default:"false"

Force upgrade even if version check fails

reboot_mode

RebootMode

default:"DEFAULT"

Reboot mode after upgrade

Response:

metadata

Metadata

Standard response metadata

ack

string

Acknowledgment message

actor_id

string

ID of the request initiator

Example:

resp, err := client.Upgrade(ctx, &machine.UpgradeRequest{
    Image: "ghcr.io/siderolabs/installer:v1.7.0",
    Stage: false,
    Force: false,
})

Reset

Resets the node to a clean state.

graceful

bool

default:"false"

Leave etcd gracefully and run pre-reset checks

reboot

bool

default:"true"

Reboot after reset (false = halt)

system_partitions_to_wipe

ResetPartitionSpec[]

Specific system partitions to wipe. Empty = wipe all

user_disks_to_wipe

string[]

Block devices to wipe (e.g., /dev/sdb)

mode

WipeMode

default:"ALL"

Wipe mode:

ALL: Wipe all disks
SYSTEM_DISK: Only system disk
USER_DISKS: Only user disks

Example:

# Reset with etcd leave
talosctl reset --graceful -n 10.0.0.1

# Reset and wipe specific disk
talosctl reset --user-disks-to-wipe /dev/sdb -n 10.0.0.1

Monitoring & Stats

Version

Returns Talos version information. Request: Empty Response:

metadata

Metadata

Standard response metadata

version

VersionInfo

tag: Version tag (e.g., v1.7.0)
sha: Git commit SHA
built: Build timestamp
go_version: Go compiler version
os: Operating system
arch: Architecture

platform

PlatformInfo

name: Platform name (e.g., aws, metal)
mode: Platform mode (e.g., cloud, container)

features

FeaturesInfo

rbac: Whether RBAC is enabled

Example:

resp, err := client.Version(ctx)
for _, msg := range resp.Messages {
    fmt.Printf("%s: Talos %s (%s)\n", 
        msg.Metadata.Hostname,
        msg.Version.Tag,
        msg.Platform.Name,
    )
}

Memory

Returns memory statistics. Request: Empty Response:

meminfo

MemInfo

Detailed memory statistics including:

memtotal: Total memory in bytes
memfree: Free memory
memavailable: Available memory
buffers: Buffer cache
cached: Page cache
swaptotal: Total swap
swapfree: Free swap
And 40+ more fields

Example:

talosctl memory -n 10.0.0.1

Processes

Lists running processes. Request: Empty Response:

processes

ProcessInfo[]

Array of processes with:

pid: Process ID
ppid: Parent process ID
state: Process state (R, S, D, Z, T)
threads: Number of threads
cpu_time: CPU time in seconds
virtual_memory: Virtual memory size
resident_memory: Resident memory size
command: Command name
executable: Executable path
args: Command arguments

Example:

resp, err := client.Processes(ctx)
for _, msg := range resp.Messages {
    for _, proc := range msg.Processes {
        fmt.Printf("PID %d: %s\n", proc.Pid, proc.Command)
    }
}

SystemStat

Returns system statistics (CPU, IRQ, context switches). Request: Empty Response:

boot_time

uint64

System boot time (Unix timestamp)

cpu_total

CPUStat

Aggregated CPU statistics

cpu

CPUStat[]

Per-CPU statistics with:

user: User mode time
system: Kernel mode time
idle: Idle time
iowait: IO wait time
irq: IRQ time

context_switches

uint64

Total context switches

process_created

uint64

Total processes created

process_running

uint64

Currently running processes

LoadAvg

Returns system load averages. Response:

load1

double

1-minute load average

load5

double

5-minute load average

load15

double

15-minute load average

NetworkDeviceStats

Returns network interface statistics. Response:

total

NetDev

Aggregated statistics across all interfaces

devices

NetDev[]

Per-interface statistics with:

name: Interface name
rx_bytes: Received bytes
rx_packets: Received packets
rx_errors: Receive errors
tx_bytes: Transmitted bytes
tx_packets: Transmitted packets
tx_errors: Transmit errors

DiskStats

Returns disk I/O statistics. Response:

total

DiskStat

Aggregated disk statistics

devices

DiskStat[]

Per-disk statistics with:

name: Device name
read_completed: Completed reads
read_sectors: Sectors read
read_time_ms: Time spent reading
write_completed: Completed writes
write_sectors: Sectors written
write_time_ms: Time spent writing
io_in_progress: I/Os in progress

Container Management

Containers

Lists containers running on the node.

namespace

string

default:"k8s.io"

Containerd namespace

driver

ContainerDriver

default:"CONTAINERD"

Container runtime driver: CONTAINERD or CRI

Response:

containers

ContainerInfo[]

Array of containers with:

namespace: Container namespace
id: Container ID
image: Container image
pid: Process ID
status: Container status
pod_id: Kubernetes pod ID (if applicable)
name: Container name

Example:

# List Kubernetes containers
talosctl containers -n 10.0.0.1

# List system containers
talosctl containers -k -n 10.0.0.1

Stats

Returns container resource usage statistics.

namespace

string

default:"k8s.io"

Containerd namespace

driver

ContainerDriver

default:"CONTAINERD"

Container runtime driver

Response:

stats

Stat[]

Resource usage per container:

namespace: Container namespace
id: Container ID
memory_usage: Memory usage in bytes
cpu_usage: CPU usage in nanoseconds
pod_id: Pod ID
name: Container name

Restart

Restarts a container.

namespace

string

required

Container namespace

string

required

Container ID

driver

ContainerDriver

default:"CONTAINERD"

Container runtime driver

Example:

talosctl restart kubelet -n 10.0.0.1

Logs & Events

Logs

Streams container logs.

namespace

string

required

Container namespace

string

required

Container ID

driver

ContainerDriver

default:"CONTAINERD"

Container runtime driver

bool

default:"false"

Follow log output (stream new logs)

tail_lines

int32

default:"-1"

Number of lines from the end to show (-1 = all)

Response: Stream of common.Data messages containing log data Example:

stream, err := client.Logs(ctx, &machine.LogsRequest{
    Namespace: "system",
    Id:        "kubelet",
    Follow:    true,
    TailLines: 100,
})

for {
    data, err := stream.Recv()
    if err == io.EOF {
        break
    }
    fmt.Print(string(data.Bytes))
}

Events

Streams system events.

tail_events

int32

default:"0"

Number of past events to return

tail_id

string

Start streaming from this event ID

tail_seconds

int32

Return events from the last N seconds

with_actor_id

string

Filter events by actor ID

Response: Stream of Event messages

data

Any

Event data (one of: SequenceEvent, PhaseEvent, TaskEvent, ServiceStateEvent, etc.)

string

Event ID

actor_id

string

Actor that triggered the event

Example:

# Stream all events
talosctl events -n 10.0.0.1

# Show last 10 events
talosctl events --tail 10 -n 10.0.0.1

Dmesg

Streams kernel messages.

bool

default:"false"

Follow kernel messages

tail

bool

default:"false"

Show only recent messages

Response: Stream of common.Data messages Example:

talosctl dmesg -f -n 10.0.0.1

File Operations

List

Lists files in a directory.

root

string

default:"/"

Root directory to list

recurse

bool

default:"false"

Recursively list subdirectories

recursion_depth

int32

default:"0"

Maximum recursion depth (0 = unlimited)

types

Type[]

Filter by file types: REGULAR, DIRECTORY, SYMLINK

Response: Stream of FileInfo messages

name

string

Full file path

size

int64

File size in bytes

mode

uint32

Unix file mode/permissions

modified

int64

Last modification time (Unix timestamp)

is_dir

bool

Whether this is a directory

link

string

Symlink target (if applicable)

Example:

talosctl ls /etc -n 10.0.0.1
talosctl ls -r /var/log -n 10.0.0.1

Read

Reads a file from the node.

path

string

required

File path to read

Response: Stream of common.Data messages containing file contents Example:

talosctl read /etc/os-release -n 10.0.0.1

Copy

Copies files from the node as a tar.gz archive.

root_path

string

required

File or directory path to copy

Response: Stream of common.Data messages containing tar.gz data Example:

talosctl copy /var/log -n 10.0.0.1

Service Management

ServiceList

Lists system services. Request: Empty Response:

services

ServiceInfo[]

Array of services with:

id: Service ID
state: Current state (Running, Stopped, etc.)
events: Service event history
health: Service health status

Example:

talosctl services -n 10.0.0.1

ServiceStart

Starts a system service.

string

required

Service ID

Example:

talosctl service start kubelet -n 10.0.0.1

ServiceStop

Stops a system service.

string

required

Service ID

Example:

talosctl service stop kubelet -n 10.0.0.1

ServiceRestart

Restarts a system service.

string

required

Service ID

Example:

talosctl service restart kubelet -n 10.0.0.1

etcd Management

Bootstrap

Bootstraps etcd on a control plane node.

recover_etcd

bool

default:"false"

Recover etcd from uploaded snapshot

recover_skip_hash_check

bool

default:"false"

Skip hash check when recovering from snapshot

Example:

talosctl bootstrap -n 10.0.0.1

EtcdMemberList

Lists etcd cluster members.

query_local

bool

default:"false"

Query only local etcd member

Response:

members

EtcdMember[]

Array of etcd members:

id: Member ID
hostname: Member hostname
peer_urls: Peer URLs
client_urls: Client URLs
is_learner: Whether this is a learner node

Example:

talosctl etcd members -n 10.0.0.1

EtcdRemoveMemberByID

Removes an etcd member by ID.

member_id

uint64

required

Member ID to remove

Example:

talosctl etcd remove-member 12345678 -n 10.0.0.1

EtcdLeaveCluster

Makes the node leave the etcd cluster gracefully. Request: Empty Example:

talosctl etcd leave -n 10.0.0.1

EtcdSnapshot

Creates an etcd snapshot. Request: Empty Response: Stream of common.Data containing snapshot data Example:

talosctl etcd snapshot etcd.snapshot -n 10.0.0.1

EtcdRecover

Uploads an etcd snapshot for recovery. Request: Stream of common.Data containing snapshot Example:

# Upload snapshot, then bootstrap with recovery
talosctl etcd recover etcd.snapshot -n 10.0.0.1
talosctl bootstrap --recover-etcd -n 10.0.0.1

EtcdStatus

Returns etcd member status. Request: Empty Response:

member_status

EtcdMemberStatus

member_id: Member ID
protocol_version: Protocol version
db_size: Database size in bytes
db_size_in_use: Database size in use
leader: Leader member ID
raft_index: Raft index
raft_term: Raft term
raft_applied_index: Applied index
is_learner: Learner status
errors: Any errors

Example:

talosctl etcd status -n 10.0.0.1

EtcdAlarmList

Lists etcd alarms. Response:

member_alarms

EtcdMemberAlarm[]

Array of alarms:

member_id: Member ID
alarm: Alarm type (NONE, NOSPACE, CORRUPT)

EtcdAlarmDisarm

Disarms etcd alarms. Request: Empty Example:

talosctl etcd alarm disarm -n 10.0.0.1

EtcdDefragment

Defragments etcd database. Request: Empty

Defragmentation is resource-intensive. Run on one node at a time.

Example:

talosctl etcd defrag -n 10.0.0.1

Advanced Operations

GenerateClientConfiguration

Generates a new client certificate and talosconfig.

roles

string[]

required

Roles to assign to the certificate (e.g., ["os:admin"])

crt_ttl

Duration

default:"8760h"

Certificate TTL (default: 1 year)

Response:

bytes

PEM-encoded CA certificate

crt

bytes

PEM-encoded client certificate

key

bytes

PEM-encoded client private key

talosconfig

bytes

Complete talosconfig file content

Example:

talosctl config new admin.yaml --roles os:admin -n 10.0.0.1

PacketCapture

Captures network packets.

interface

string

required

Network interface name

promiscuous

bool

default:"false"

Enable promiscuous mode

snap_len

uint32

default:"65536"

Snapshot length in bytes

bpf_filter

BPFInstruction[]

BPF filter instructions

Response: Stream of pcap data Example:

talosctl pcap -i eth0 -n 10.0.0.1 > capture.pcap

Netstat

Provides network connection information.

filter

Filter

default:"ALL"

Connection filter: ALL, CONNECTED, LISTENING

feature

Feature

pid: Include process IDs

l4proto

L4proto

Protocol filters: tcp, tcp6, udp, udp6, etc.

Response:

connectrecord

ConnectRecord[]

Network connections with:

l4proto: Protocol (tcp, udp, etc.)
localip: Local IP address
localport: Local port
remoteip: Remote IP address
remoteport: Remote port
state: Connection state
process: Process information (if requested)

Example:

talosctl netstat -n 10.0.0.1

Hostname

Returns the node hostname. Request: Empty Response:

hostname

string

Node hostname

Example:

talosctl hostname -n 10.0.0.1

Kubeconfig

Returns the Kubernetes admin kubeconfig. Request: Empty Response: Stream of kubeconfig file data Example:

talosctl kubeconfig -n 10.0.0.1

CLI Reference

gRPC API

Configuration API

​Overview

​Configuration Management

​ApplyConfiguration

​System Lifecycle

​Reboot

​Shutdown

​Upgrade

​Reset

​Monitoring & Stats

​Version

​Memory

​Processes

​SystemStat

​LoadAvg

​NetworkDeviceStats

​DiskStats

​Container Management

​Containers

​Stats

​Restart

​Logs & Events

​Logs

​Events

​Dmesg

​File Operations

​List

​Read

​Copy

​Service Management

​ServiceList

​ServiceStart

​ServiceStop

​ServiceRestart

​etcd Management

​Bootstrap

​EtcdMemberList

​EtcdRemoveMemberByID

​EtcdLeaveCluster

​EtcdSnapshot

​EtcdRecover

​EtcdStatus

​EtcdAlarmList

​EtcdAlarmDisarm

​EtcdDefragment

​Advanced Operations

​GenerateClientConfiguration

​PacketCapture

​Netstat

​Hostname

​Kubeconfig

​See Also

Build docs developers (and LLMs) love

Overview

Configuration Management

ApplyConfiguration

System Lifecycle

Reboot

Shutdown

Upgrade

Reset

Monitoring & Stats

Version

Memory

Processes

SystemStat

LoadAvg

NetworkDeviceStats

DiskStats

Container Management

Containers

Stats

Restart

Logs & Events

Logs

Events

Dmesg

File Operations

List

Read

Copy

Service Management

ServiceList

ServiceStart

ServiceStop

ServiceRestart

etcd Management

Bootstrap

EtcdMemberList

EtcdRemoveMemberByID

EtcdLeaveCluster

EtcdSnapshot

EtcdRecover

EtcdStatus

EtcdAlarmList

EtcdAlarmDisarm

EtcdDefragment

Advanced Operations

GenerateClientConfiguration

PacketCapture

Netstat

Hostname

Kubeconfig

See Also