Talos Linux integration: OS updates and cluster state in Home Assistant

This is probably a pretty niche integration, but I run my homelab on Kubernetes, powered by Talos Linux. I wanted the Talos OS updates to land in Home Assistant right next to my Kubernetes updates, so every update and status across the homelab sits in one place. That meant talking to the Talos API directly, which the generic Kubernetes integration doesn't do. You can find it on GitHub at GitHub - FireBall1725/talos-hass: Home Assistant (HACS) integration for Talos Linux clusters: node versions, available upgrades, machine stage, etcd, per-node metrics, and schematic-aware OS upgrades over the Talos API. · GitHub (AGPL-3.0, currently at 0.1.5).

The existing kubernetes integration reads nodes through the Kubernetes API. From there a Talos node looks like any other node: a version string, a kubelet version, a ready condition. Talos keeps everything else behind its own gRPC API (apid) on port 50000: the running Talos version, the machine stage, installed system extensions, the Image Factory schematic ID, etcd member health, and per-node CPU, memory, and disk. This integration reads that API over mTLS.

The feature I care about most is the per-node update entity. It reads each node's Image Factory schematic, then builds the exact installer image for that schematic when you upgrade. An upgrade started from Home Assistant keeps that node's system extensions instead of stripping them back to a stock image, which is what you get if you upgrade with the wrong installer.

Entities

Per node: Talos version, machine stage, CPU/memory/disk usage, last boot, schematic ID, extension count, architecture, and platform, plus an update entity and two binary sensors (reachable and ready). The cluster device carries node count, control-plane count, Talos version spread, the latest Talos release on offer, and (new in 0.1.5) a client-certificate expiry timestamp, so the talosconfig cert that authenticates the integration doesn't lapse without warning.

The optional Talos sidebar panel shows more than the entities do: every node as a row with ready state, IP, CPU and memory bars, and uptime, expanding into the full detail grid, installed extensions, Talos service health, and etcd members. The entities and services work without it.

Write actions and safety

Write actions (reboot, upgrade, apply config, reset) are gated three ways at once. The matching options toggle has to be on, the cert's RBAC role has to allow it (os:operator or os:admin), and the service call has to pass a confirm_node field that string-matches the target node. A tier that's disabled isn't registered as a service at all.

There's no orchestration in this integration. It won't cordon, drain, or sequence anything for you. Rebooting or upgrading more than one control-plane node at a time breaks etcd quorum, so ordering across nodes is your job, in your own automation.

One implementation note

Talos issues an Ed25519 PKI by default, and grpcio's bundled BoringSSL can't negotiate Ed25519 mTLS. So the client is pure Python on grpclib over the stdlib ssl module (OpenSSL), which handles it. No grpcio wheel, so there's no architecture-specific build step for the client.

Requirements and install

You need a Talos cluster reachable on apid port 50000, and a talosconfig with at least the os:reader role. Write actions need os:operator or os:admin.

It's not in the HACS default store yet. Add https://github.com/FireBall1725/talos-hass as a custom repository in HACS, install Talos Linux, restart, then add the integration. The config flow asks for one control-plane endpoint and your talosconfig; apid proxies to the rest, so node discovery is automatic.

It's pre-release and under active development, so expect breaking changes before 1.0. Bug reports and "this broke on my cluster" issues are welcome. Repo and issue tracker: GitHub - FireBall1725/talos-hass: Home Assistant (HACS) integration for Talos Linux clusters: node versions, available upgrades, machine stage, etcd, per-node metrics, and schematic-aware OS upgrades over the Talos API. · GitHub

2 Likes