A zero-latency, privileged debug environment for Talos Linux nodes, fully integrated with Sidero Omni.
Since Talos Linux is designed to be immutable, API-driven, and lacks a traditional SSH server or shell, debugging low-level hardware or network issues can be challenging. This tool acts as the ultimate "break-glass" SSH alternative. It leverages kubectl debug with the sysadmin profile to launch a fully loaded, privileged Alpine container directly on the host network, providing full access to the node's filesystem, processes, and devices.
- Direct Hardware Access: Mounts
/devand the node's root filesystem (under/host), allowing you to useparted,lvm2, andwipefson physical disks. - Sidero Omni Integration: Automatically authenticates with your Omni endpoint to fetch
talosconfigandkubeconfigon the fly. - Pre-installed Tooling:
- Network:
tcpdump,tshark,nmap,socat,iperf3,mtr,iproute2,bind-tools - Storage:
lvm2,e2fsprogs,xfsprogs,parted,drbd-utils,nvme-cli - K8s/Talos:
kubectl,talosctl,omnictl,helm,cri-tools - Cloud:
aws-cli - Utilities:
jq,yq,vim,tmux,lsof,strace,coreutils
- Network:
- Chad UX: Custom
.bashrcwith smart aliases, drbd wrappers, and full auto-completion forkubectl,talosctl,omnictland many others.
Currently, the plugin can be installed locally by placing the executable script in your user's $PATH.
- Clone the repository or download the script:
git clone https://github.com/cappyt/talos-toolbx.git
cd talos-toolbx
- Make the script executable:
chmod +x kubectl-talos_toolbx
- Move it to your local binary path (ensure
~/.local/binis in your$PATH):
mkdir -p ~/.local/bin
cp kubectl-talos_toolbx ~/.local/bin/
- Verify the installation:
kubectl plugin list
# You should see "kubectl-talos_toolbx" in the output
The tool requires authentication with Sidero Omni to seamlessly generate your K8s and Talos credentials from inside the debug pod.
The first time you run the tool, it will generate a configuration template at ~/.config/talos-toolbx/config.env and exit.
Open the file and fill in your details:
OMNI_ENDPOINT="https://<your-omni-account>.siderolabs.io"
OMNI_SERVICE_ACCOUNT_KEY="insert-your-sa-key-here"
OMNI_CLUSTER_NAME="your-cluster-name-on-omni"
(You can generate a Service Account Key from the Omni Web UI -> Settings -> Service Accounts).
To start a debug session, simply run the plugin and specify the target node:
kubectl talos-toolbx <node-name>
Once you drop into the shell, you can instantly load your credentials using the built-in aliases:
- Run
load-talosto authenticatetalosctlvia Omni and point it to the local node. - Run
load-kubeto authenticatekubectlvia Omni with cluster-admin privileges.
Check the physical disks of the node:
lsblk
parted /dev/sda print
Interact with the local container runtime (containerd):
crictl ps
crictl logs <container-id>
Check the node's Talos configuration and logs:
load-talos
t dmesg
t logs kubelet