Michael van Tricht

Software Engineer

Migrating my homelab to a Kubernetes cluster using Talos

After earning my Certified Kubernetes Application Developer (CKAD) certification, I wanted to bring Kubernetes to my homelab to maintain and expand my skills. Having previously followed Kelsey Hightower’s “Kubernetes the Hard Way”, I sought an experience that would be simpler, more streamlined, and less error-prone. This led me to Talos, an operating system purpose-built for running Kubernetes.

Talos offers a lightweight, secure, and fully automated way to deploy Kubernetes clusters. Designed with immutable infrastructure principles, Talos ensures that all management is API-driven, with no SSH access or package manager on the nodes, keeping the footprint minimal. This design makes Kubernetes clusters easier to install, manage, and upgrade.

Talos dashboard Talos dashboard awaiting installation instructions.

The setup

In my homelab, I use two Dell OptiPlex microform computers running Proxmox. To start off I created one control plane VM and two worker VMs booting using the Talos iso. To avoid opening any ports to the outside world, Talos includes built-in WireGuard functionality called KubeSpan, which seamlessly handles secure connectivity between nodes multi-cloud.

To enable external access, I’ve also configured a VPS on Hetzner as a Talos Kubernetes worker node, accessing the three other nodes in my homelab through Wireguard. This provides an accessible entry point to my cluster from the outside world while ensuring my local environment remains secure.

Homelab setup Homelab setup with 4 Kubernetes nodes. Diagram created using d2lang.

Installing Talos

The Talos documentation is much more comprehensive and clearer, so I highly recommend following it. My goal is to demonstrate how easy it is to install, use and upgrade a Kubernetes cluster. These steps are for installing Talos on the VMs running inside Proxmox, but it is also possible to run a test cluster inside docker.

  1. Download the Talos CLI

    $ curl -Lo talosctl https://github.com/siderolabs/talos/releases/latest/download/talosctl-$(uname -s)-$(uname -m)
$ chmod +x talosctl
$ sudo mv talosctl /usr/local/bin/

  2. Generate cluster configuration

    $ talosctl gen config my-cluster https://$CONTROL_PLANE_IP:6443

    This command generates the necessary configuration files (worker.yaml and controlplane.yaml) for your cluster.

  3. Install the control plane
    Boot your node(s) using the Talos image, then apply the configuration to the control plane node and bootstrap etcd:

    $ talosctl apply-config --insecure --nodes $CONTROL_PLANE_IP --file controlplane.yaml
$ export TALOSCONFIG="talosconfig"
$ talosctl config endpoint $CONTROL_PLANE_IP
$ talosctl config node $CONTROL_PLANE_IP
$ talosctl bootstrap
$ talosctl kubeconfig ~/.kube/config

  4. Add additional nodes
    Apply the appropriate configuration file (worker.yaml or controlplane.yaml) to the new node:

    $ talosctl apply-config --nodes <NODE_IP> --file <worker|controlplane>.yaml

Talos dashboard Talos dashboard after installation.

Upgrading

Upgrading Talos is straightforward and seamless. Use the following command to upgrade nodes:

$ talosctl upgrade --nodes <NODE_IP> --image ghcr.io/siderolabs/talos:<NEW_VERSION>

With Talos, upgrading Kubernetes is just as easy:

$ talosctl upgrade-k8s --nodes $CONTROL_PLANE_IP --version <NEW_K8S_VERSION>

Migrating docker-compose files

If you’re transitioning from docker-compose, Talos supports the migration process with Kompose, a tool for converting docker compose files into Kubernetes manifests.

  1. Install Kompose

    $ curl -L https://github.com/kubernetes/kompose/releases/download/v1.35.0/kompose-linux-amd64 -o kompose
$ chmod +x kompose
$ sudo mv kompose /usr/local/bin/

  2. Convert your docker compose file

    $ kompose convert -f docker-compose.yaml -o application

This generates Kubernetes manifests that you can deploy to your Talos cluster.

Essential components

I recommend these essential Kubernetes tools: