Machines

Machine management is the bridge between user-owned hardware and Satusky deployments. It is broader than renting capacity: the target system lets users discover, claim, group, observe, operate, and eventually decommission machines through one coherent control plane.

Current source-of-truth model

Concern	Best source of truth
machine discovery and management reachability	SideroLink
OS-level lifecycle and pre-Kubernetes state	Talos API
schedulability, capacity, allocatable resources	Kubernetes Node API
placement metadata	Kubernetes node labels
ownership, billing history, audit trail	backend database
live host/workload telemetry	Kubernetes metrics, Prometheus, and Talos where needed

SideroLink and Talos

SideroLink gives Talos machines a stable management address over a WireGuard overlay, including when machines sit behind NAT or firewalls. That makes discovery and lifecycle operations possible before ordinary app networking is useful.

Talos machine
  └── SideroLink identity / overlay address
        └── Satusky control plane

Current CLI workflow

List owned inventory and inspect one machine by its machine ID or name:

1ctl machine list
1ctl machine get worker-example
1ctl machine inspect worker-example

machine inspect combines stored inventory, hardware, labels, and Talos/Kubernetes status where available. A statically connected worker can be healthy even when the command warns that it is not present in SideroLink discovery; the remaining sections still describe the available sources.

Fetch bounded diagnostics:

1ctl machine logs worker-example --source kubernetes --tail 100 --since 10m
1ctl machine events worker-example --tail 50

An empty result means no matching logs or events were returned. It is not, by itself, evidence that the machine is unhealthy.

Rentable capacity and accounting history are separate views:

1ctl machine available --region MY --zone my-kul-1b --min-cpu 2 --min-memory 4
1ctl machine usage list

Control-plane model

1ctl machine = fleet ownership and operations
1ctl deploy  = workload placement intent
Kubernetes  = scheduling substrate

Inventory creation, updates, and deletion change control-plane records. Do not use them as substitutes for Kubernetes drain, Talos reconfiguration, or physical machine lifecycle procedures.

Labels and selectors

This is the strategic center of machine-aware deployment.

machines declare what they are
workloads declare what they need

Use the immutable machine ID for label changes:

MACHINE_ID=89905f5f769867452a7bd6c7505ab34d
1ctl machine labels list "$MACHINE_ID"
1ctl machine labels set "$MACHINE_ID" pool=production architecture=arm64
1ctl machine labels unset "$MACHINE_ID" pool
1ctl machine labels keys

User keys are stored in the Satusky label namespace. Label removal aliases are delete and rm; the singular machine label alias is also accepted.

Most machine read commands support table and JSON output. machine labels list and machine labels keys currently render human-readable output even when --output json is supplied, so do not parse those commands as JSON.

Safe scripting

Supply every documented positional argument explicitly. Some machine subcommands currently print help and exit successfully when a required positional argument is omitted. Validate identifiers in the script rather than treating that help exit as an operation success.

Current gaps and target direction

Gap	Target
Discovery and claim are not part of the current CLI contract.	First-class tenant onboarding for new hardware.
Logs and events are point-in-time queries, not streaming telemetry.	Unified live and historical fleet diagnostics.
Placement language is narrower than the intended model.	General selectors become the foundation.
SideroLink/Talos details risk leaking too far upward.	Keep them diagnosable but beneath a clean machine UX.