🚀 talos-homelab-core

Minimalist, Immutable Kubernetes on Bare Metal

Buzzwords: Infrastructure-as-Code • GitOps-Ready • Immutable OS • Security-Hardened • Zero-SSH • Bare-Metal • Sidero Labs

---

📖 Overview

This repository contains a streamlined workflow for deploying a Talos Linux cluster. Unlike traditional distributions, Talos is immutable, ephemeral, and managed entirely via API.

🏗️ The Architecture

+--------------------------------------+
|        Kubernetes Workloads          |
|  (Pods, Deployments, Services, Helm) |
+--------------------------------------+
                  ▲
                  |
+--------------------------------------+
|          Talos Immutable OS          |
| - Read-only root filesystem          |
| - No SSH / No package installs       |
| - Configured via talosctl only       |
| - Consistent & secure across reboots |
+--------------------------------------+
                  ▲
                  |
+--------------------------------------+
|      Physical / Virtual Machine      |
| - CPU, RAM, Storage, Network         |
+--------------------------------------+

🛡️ Understanding Immutability

“Immutable” literally means unchangeable. In the context of Talos Linux:
No Direct SSH: You cannot SSH into the node to apt install or manually tweak files.
Read-Only Root FS: The OS is locked at runtime.
Every reboot restores the OS to a known, perfect state.
API-Driven: All changes (networking, users, K8s settings) are made via YAML configuration and talosctl.
The Analogy: Think of Talos as a Fridge. You can put food inside (Pods/Apps), but you cannot change the internal wiring or the compressor firmware.

🛠️ Prerequisites & Setup

1️⃣ Install Management Tools (Ubuntu)

On your management machine, install the required binaries:

curl -sL [https://talos.dev/install](https://talos.dev/install) | sh
sudo mv talosctl /usr/local/bin/
talosctl version

👉 Build & Download ISO -> https://factory.talos.dev/

2️⃣ Generate Custom ISO

Use the Talos Factory to include specific drivers for Intel hardware (i915 Graphics & Microcode):
Platform: metal | Arch: amd64
Extensions: siderolabs/i915, siderolabs/intel-ucode

Boot your target machine from the ISO. Note the IP address shown on the console. Identify your installation disk:

# Replace <NODE_IP> with your actual node IP
talosctl -n <NODE_IP> get disks --insecure -o yaml

Generate Cluster Configuration

talosctl gen config martinos https://<NODE_IP>:6443

Edit controlplane.yaml.

Set install.disk to your identified disk (e.g., /dev/nvme0n1).

For single-node clusters, ensure you allow scheduling on the control plane.

Apply & Bootstrap

Apply configuration (Installs OS to disk and reboots)

talosctl apply-config -n <NODE_IP> --insecure --file controlplane.yaml

Wait 2 minutes for reboot, then Bootstrap Kubernetes

talosctl bootstrap --nodes <NODE_IP> --endpoints <NODE_IP> --talosconfig=talosconfig

Merge Kubeconfig for kubectl access

export TALOSCONFIG=talosconfig
talosctl config endpoint <NODE_IP>
talosctl kubeconfig -n <NODE_IP>

📉 Essential Management

Check Cluster Health: talosctl health -n <NODE_IP>
Monitor Node: talosctl dashboard -n <NODE_IP>
Verify K8s: kubectl get nodes -o wide
Shutdown Node: talosctl shutdown -n <NODE_IP>