Talos: Where COSI Was Born

This chapter is the origin story: Talos Linux is what COSI was built for. The entire operating system — networking, configuration, services, upgrades, hardware discovery — is modeled as a graph of controllers reconciling typed resources against a central state broker. COSI was extracted from Talos to be reusable. Reading Talos is reading the library at full depth, in full production, on real machines.

#What Talos is

Talos Linux is an immutable, API-only operating system purpose-built for running Kubernetes. It has no SSH, no shell, no package manager, no user accounts. Every configuration change is a structured API call. Every observable fact about the machine — its IP addresses, its hostname, the status of its services — is a structured API response. The system is designed around one guarantee: if you know the desired state, the machine will converge to it, deterministically, from any starting point.

#The origin: COSI as extracted infrastructure

COSI was not designed in the abstract and then applied to Talos — it emerged from Talos. Sidero Labs built the resource/controller engine inside the Talos monorepo, discovered it was the load-bearing architecture for the entire OS, and then extracted it into github.com/cosi-project/runtime so other systems could use the same substrate. The current cosi-project/runtime library is a direct descendant of code that has been running on bare metal in production since Talos v0.x.

#The topology: machined and its runtimes

On each Talos node, the main system daemon is machined — effectively the init daemon and PID 1. It owns the COSI runtime and registers every controller. The COSI state.State is the machine's memory — everything transient and derived is held entirely in-memory; only the MachineConfig is persisted to disk and is re-loaded as a resource on each boot. All other resources are reconstructed from scratch by their controllers.

#The bootstrap sequence: resources coming to life

COSI state is entirely in-memory. On every boot, it starts empty and reconstructs from scratch. The order in which resources appear is exactly the dependency graph the runtime has computed. The sequence below shows how a Talos control-plane node goes from power-on to a running Kubernetes cluster — every step is a controller waking up because its inputs appeared:

1. machined starts (PID 1 equivalent). COSI runtime initializes. All namespaces exist but contain zero resources. Controllers are registered but blocked on r.EventCh().
2. ConfigAcquireController reads persistent config from disk and creates the config.MachineConfig resource (ID: v1alpha1). This is the trigger event for everything else.
3. ~12 config controllers wake simultaneously. MachineTypeController, TimeServerConfigController, NetworkConfigController, and others all watched MachineConfig. They fan out, writing their typed sub-resources into network, k8s, etcd, etc.
4. Network controllers cascade. LinkConfigController writes LinkSpec resources → LinkSpecController applies them to the kernel → LinkStatusController reflects actual state back as LinkStatus. Same for addresses and routes. NodeAddressController aggregates AddressStatus → writes NodeAddress.
5. etcd and Kubernetes controllers unblock. They were waiting for NodeAddress (needed to compute peer/advertise addresses). Now etcd.SpecController writes etcd.Spec → etcd service starts → becomes healthy.
6. KubeletStaticPodController writes k8s.StaticPod resources for kube-apiserver, kube-controller-manager, kube-scheduler. A local HTTP server (part of machined) serves these manifests to kubelet. Kubernetes control plane comes up.
7. Cluster controllers join. cluster.Member and cluster.Affiliate resources appear as the node joins the etcd cluster and the Kubernetes API becomes available.

The key property: no step happens before its dependencies are satisfied, and no step polls — everything is triggered by the appearance of the resources it was waiting for. If you change the machine config mid-run, only the controllers whose inputs changed wake up; everything else stays quiet. The dependency graph, not a startup script, is the operating system's boot logic.

#The resource catalog: namespaces and types

Talos organizes every resource into a namespace. The namespace is the first axis of isolation — controllers in the network namespace only declare outputs there; no other controller can write network addresses. Here is the full catalog as of Talos v1.x:

Every type name resolves through resource.ResourceType. For example, network.AddressSpecType = "AddressSpecs.net.talos.dev". The .net.talos.dev group suffix is how Talos scopes its types — a convention you'd replicate in your own application with your own domain suffix.

#The config plane

A Talos machine is configured by writing a MachineConfig resource (a YAML document) over the machine API. Internally, machined creates a config.MachineConfig resource in the config namespace with the stable ID "v1alpha1". From that single resource, approximately 12 config controllers fan out into typed sub-resources that downstream controllers can consume without parsing YAML:

This is the key architectural insight of Talos: structured config input is translated to typed resources at the edge, and the rest of the system never sees raw config again. The network controller doesn't know what YAML looks like. It watches network.LinkSpec resources. If the config plane correctly populated them, the network plane is correct.

// etcd.ConfigController uses the transform.Controller generic — no explicit Run() loop.
// The runtime wakes it when MachineConfig changes; TransformFunc does the work.
func NewConfigController() *transform.Controller[*config.MachineConfig, *etcd.Config] {
    return transform.NewController(
        transform.Settings[*config.MachineConfig, *etcd.Config]{
            Name: "etcd.ConfigController",
            MapMetadataFunc: func(cfg *config.MachineConfig) *etcd.Config {
                return etcd.NewConfig(etcd.NamespaceName, etcd.ConfigID)
            },
            TransformFunc: func(ctx context.Context, r controller.Runtime, logger *zap.Logger,
                cfg *config.MachineConfig, out *etcd.Config) error {
                spec := out.TypedSpec()
                spec.AdvertiseSubnets = cfg.Config().Cluster().Etcd().Subnet()
                spec.ExtraArgs = cfg.Config().Cluster().Etcd().ExtraArgs()
                // ... etc.
                return nil
            },
        },
    )
}

// When you need full control (multiple inputs, complex logic), plain Controller still applies.
// MachineTypeController shows the hand-rolled pattern.
func (ctrl *MachineTypeController) Inputs() []controller.Input {
    return []controller.Input{{
        Namespace: config.NamespaceName,
        Type:      config.MachineConfigType,
        ID:        optional.Some(config.ActiveID),
        Kind:      controller.InputWeak,
    }}
}

func (ctrl *MachineTypeController) Outputs() []controller.Output {
    return []controller.Output{{Type: config.MachineTypeType, Kind: controller.OutputExclusive}}
}

func (ctrl *MachineTypeController) Run(ctx context.Context, r controller.Runtime, _ *zap.Logger) error {
    for {
        select {
        case <-ctx.Done(): return nil
        case <-r.EventCh():
        }
        cfg, err := safe.ReaderGetByID[*config.MachineConfig](ctx, r, config.ActiveID)
        // … write config.MachineType based on cfg.Config().Machine().Type()
    }
}

#The network plane: spec/status at scale

The network plane is where COSI earns its keep most visibly in Talos — and it's the most developed network management stack you'll find built on this model. Every network concept has a strict Spec/Status split:

The Status controllers are wrappers around the Linux kernel's netlink API. They do one job: translate kernel state into COSI resources. They never read Spec resources. They are the ingest edge of the system — real-world facts flowing in. The applier controllers (e.g., AddressConfigController) do the other half: they read Spec, compare to Status, and call netlink to reconcile the difference. The two halves never directly coordinate — they talk only through shared resources.

#Multi-source merge: the network controller graph

The most sophisticated pattern in Talos's network plane is multi-source spec merging. A machine's IP address can come from three sources: the MachineConfig, a DHCP response, or the kernel cmdline. Each source is a separate controller that writes AddressSpec resources with a layer weight in the resource ID. A merge controller collects all the sources and produces the final desired spec.

This is the shared output pattern from chapter 03 at full scale. Multiple controllers contribute to the same resource type without conflict, because each one owns distinct resource IDs (keyed by source and interface). The merge controller is the only one that reads across all of them.

#The runtime plane: services as resources

Every system service in Talos — kubelet, etcd, apid, cri, extension services — is managed by a COSI controller. The pattern is identical to the network plane:

1. A config controller reads the relevant MachineConfig section and writes a typed config resource (e.g., k8s.KubeletConfig, k8s.EtcdConfig).
2. A service controller reads that config resource and manages the actual system service via go-runner (Talos's process runner). It starts, restarts, and stops the service based on resource phase changes.
3. A status controller reflects the service's actual health back as a runtime.ServiceStatus or similar resource.

For example, the kubelet lifecycle: MachineConfig → k8s.KubeletConfig (config plane) → KubeletController starts the kubelet process → ServiceStatusController writes runtime.ServiceStatus{Running: true}. If the machine config changes (say, the kubelet extra args), the config plane updates k8s.KubeletConfig, which wakes the KubeletController, which restarts kubelet with the new args. The controller never parses YAML — it reads a typed Go struct.

func (ctrl *KubeletController) Inputs() []controller.Input {
    return []controller.Input{
        {Namespace: k8s.NamespaceName, Type: k8s.KubeletConfigType, Kind: controller.InputWeak},
        {Namespace: secrets.NamespaceName, Type: secrets.KubernetesType, Kind: controller.InputWeak},
        // also watches network.NodeAddress so it can update --node-ip on address change
        {Namespace: network.NamespaceName, Type: network.NodeAddressType, Kind: controller.InputWeak},
    }
}

func (ctrl *KubeletController) Run(ctx context.Context, r controller.Runtime, logger *zap.Logger) error {
    for {
        select {
        case <-ctx.Done(): return nil
        case <-r.EventCh():
        }
        kubeletCfg, _ := safe.ReaderGetByID[*k8s.KubeletConfig](ctx, r, k8s.KubeletID)
        nodeAddresses, _ := safe.ReaderListAll[*network.NodeAddress](ctx, r)
        // build the args list, reconcile against the running process
        ctrl.runner.Reconcile(ctx, buildArgs(kubeletCfg, nodeAddresses))
    }
}

Notice that KubeletController also watches network.NodeAddress — so when the machine's IP changes (say, a DHCP renewal), the kubelet is automatically restarted with the updated --node-ip flag. The network plane and the service plane are decoupled; they communicate through state. This is exactly the "no controller calls another controller" design principle from chapter 00, at OS scale.

#The Talos API: COSI state over gRPC

From the outside, the Talos API looks like a conventional gRPC service. Under the hood, apid is a thin auth layer on top of the COSI gRPC transport from chapter 05. When you run talosctl get addresses, here's what actually happens:

The COSI gRPC server in apid wraps the state.State with an access-control layer (AdminRole can read all namespaces; OS-role can only read public resources), then connects it directly to the gRPC State service defined in chapter 05. There is no translation layer, no separate API model — the external API is the resource model. This is what the README means by "the interface runs from local to gRPC without changing your controllers."

// apid registers the COSI gRPC State service using the same state.State
// that the controller runtime uses. External clients get a live, watched
// view of everything inside machined — with RBAC on top.
func (b *Backend) Register(server *grpc.Server) {
    cosiv1.RegisterStateServer(server,
        server_state.NewState(b.cosState, authz.NewRBACInterceptor(b.roles)),
    )
    machine.RegisterMachineServiceServer(server, &machineService{backend: b})
}

#Omni: distributed COSI at fleet scale

Sidero's Omni is the multi-node control plane that manages fleets of Talos machines. It illustrates the gRPC transport from chapter 05 at real-world scale: Omni maintains a persistent gRPC connection to each Talos node and aggregates their individual COSI states into a single federated view. From Omni's perspective, each node is a remote CoreState — reads and watches go over the wire, and Omni's own controllers react to changes on any of them.

#Lessons from a real OS

Talos is the longest-running COSI application. Several patterns appear here that you won't find spelled out in the library documentation:

#Verdict

To apply these patterns to your own systems, see Chapter 06 for the decision framework and the domain-to-COSI mapping table.