Skip to content
application · talos · homelab

Bare-metal workers,Talos.

Add Intel NUC devices as Talos Linux worker nodes to the existing KBVE cluster on Hetzner. Cluster traffic tunnels over WireGuard, every node is managed declaratively through talosctl, and each NUC joins as a standard Kubernetes worker — from hardware prep to troubleshooting.

Hardware prepInstall TalosJoin the clusterTroubleshooting

Homelab meets cloud

Home-based NUCs and Hetzner control-plane nodes communicate over an encrypted WireGuard overlay as if on one private subnet — no shell, no SSH, just declarative machine configs.

  • Immutable OS — Talos is API-driven with no shell or SSH.
  • WireGuard overlay — unique key and 10.0.0.x IP per NUC.
  • Declarative join — talosctl apply-config per worker.
11th+NUC generation
8GBMinimum RAM
256GB NVMeStorage
WireGuardOverlay

On this page

What this guide covers

Hardware requirements

Compatible NUC models, RAM and SSD sizing, and the full assembly checklist before any software touches the box.

Talos installation

Download and verify the ISO, flash bootable USB drives, and boot each NUC into Talos maintenance mode.

Join the cluster

Apply the per-node worker config, verify the node registers, and test pod scheduling over the WireGuard mesh.

Troubleshooting

WireGuard connection failures, nodes that refuse to join, and hardware compatibility checks with talosctl.

Start here

Overview

This guide covers adding Intel NUC devices as worker nodes to the existing Talos Linux cluster running on Hetzner with WireGuard networking.

Flow: hardware prep → Talos install → cluster config → join → troubleshooting.

Shopping list

Hardware Requirements

Intel NUC Specifications

Section titled “Intel NUC Specifications”
  • Compatible Models: Intel NUC 11th gen or newer (tested on NUC11TNHi5, NUC11TNKi5)
  • RAM: 8GB minimum (16GB recommended for production workloads)
  • Storage: 256GB SSD minimum (NVMe preferred)
  • Network: Gigabit Ethernet (built-in)
  • Power: Compatible power supply unit (PSU)

Hardware Checklist

Section titled “Hardware Checklist”
  • Intel NUC units
  • Compatible PSUs for each NUC
  • 8GB+ RAM per NUC
  • 256GB+ SSDs per NUC
  • USB flash drives for installation (8GB+)
  • Ethernet cables
  • Network access for initial setup

Phase one

Phase 1: Hardware Preparation

  1. Assemble Hardware

    Install RAM and SSD in each Intel NUC:

    Terminal window
    # Power off and unplug the NUC
    # Remove bottom cover screws
    # Install SO-DIMM RAM in available slots
    # Install M.2 SSD in available slot
    # Reassemble and connect power

  2. BIOS Configuration

    Boot each NUC and configure BIOS settings:

    • Enable UEFI boot mode
    • Disable Secure Boot
    • Enable Intel VT-x/VT-d
    • Set primary boot device to USB
    • Save settings and exit

  3. Network Planning

    Document network configuration for each NUC:

    Terminal window
    # Example IP assignments
    NUC-01: 192.168.1.10 (DHCP) -> WG: 10.0.0.10
    NUC-02: 192.168.1.11 (DHCP) -> WG: 10.0.0.11
    NUC-03: 192.168.1.12 (DHCP) -> WG: 10.0.0.12

Phase two

Phase 2: Talos Linux Installation

  1. Download Talos Linux

    Download the latest Talos Linux ISO:

    Terminal window
    # Download Talos ISO
    curl -Lo talos-amd64.iso https://github.com/siderolabs/talos/releases/latest/download/talos-amd64.iso
    

    # Verify checksum
    curl -Lo talos-amd64.iso.sha256 https://github.com/siderolabs/talos/releases/latest/download/talos-amd64.iso.sha256
    sha256sum -c talos-amd64.iso.sha256

  2. Create Bootable USB

    Create bootable USB drives for each NUC:

    Terminal window
    # Replace /dev/sdX with your USB device
    sudo dd if=talos-amd64.iso of=/dev/sdX bs=4M status=progress
    sync

  3. Boot and Install Talos

    For each NUC:

    Terminal window
    # Insert USB and boot from it
    # Talos will load and provide an IP address
    # Note down the IP address for each NUC

Phase three

Phase 3: Cluster Configuration

  1. Generate WireGuard Keys

    Generate unique WireGuard keys for each NUC:

    Terminal window
    # Generate keys for each NUC worker
    for i in {10..12}; do
      echo "Generating keys for NUC-$(printf "%02d" $((i-9)))"
      wg genkey | tee nuc-$i-private.key | wg pubkey > nuc-$i-public.key
    done

  2. Prepare Worker Configuration

    Customize the worker configuration for each NUC:

    Terminal window
    # Get the existing cluster configuration from Hetzner control plane
    talosctl get mc v1alpha1 -o jsonpath='{.spec}' -n [HETZNER_CONTROL_PLANE_IP] > base-worker.yaml
    

    # Or use the template from the repository
    cp apps/kube/talos-worker.yaml worker-template.yaml

  3. Update WireGuard Configuration

    For each NUC, update the worker configuration:

    # Update machine.network.interfaces.wg0.wireguard section
    machine:
      network:
        hostname: "nuc-01"  # nuc-01, nuc-02, nuc-03, etc.
        interfaces:
          - interface: wg0
            wireguard:
              privateKey: "PRIVATE_KEY_FROM_STEP_1"
              peers:
                - publicKey: "HETZNER_CONTROL_PLANE_PUBLIC_KEY"
                  endpoint: "HETZNER_CONTROL_PLANE_IP:51820"
                  allowedIPs:
                    - 10.0.0.0/24
            addresses:
              - 10.0.0.10/32  # Increment for each NUC

Phase four

Phase 4: Join NUCs to Cluster

  1. Apply Worker Configuration

    Apply the configuration to each NUC:

    Terminal window
    # For each NUC, apply the customized worker config
    talosctl apply-config --insecure --nodes [NUC_IP] --file worker-nuc-01.yaml
    talosctl apply-config --insecure --nodes [NUC_IP] --file worker-nuc-02.yaml
    talosctl apply-config --insecure --nodes [NUC_IP] --file worker-nuc-03.yaml

  2. Verify Node Join

    Check that nodes are joining the cluster:

    Terminal window
    # Check cluster nodes
    kubectl get nodes -o wide
    

    # Verify WireGuard connectivity
    talosctl dmesg --nodes [NUC_WG_IP] | grep -i wireguard

  3. Test Connectivity

    Verify the setup is working:

    Terminal window
    # Test pod scheduling on NUC workers
    kubectl run test-pod --image=nginx --restart=Never
    kubectl get pods -o wide
    

    # Check WireGuard peer status
    sudo wg show

When it breaks

Troubleshooting

Common Issues

Section titled “Common Issues”

  1. WireGuard Connection Failed

    Terminal window
    # Check WireGuard status
    sudo wg show
    

    # Verify endpoint connectivity
    ping HETZNER_CONTROL_PLANE_IP
    

    # Check firewall rules
    sudo ufw status

  2. Node Not Joining Cluster

    Terminal window
    # Check Talos logs
    talosctl logs --nodes [NUC_IP] kubelet
    

    # Verify cluster token
    talosctl get secrets --nodes [CONTROL_PLANE_IP]

  3. Hardware Compatibility

    Terminal window
    # Check system compatibility
    talosctl dmesg --nodes [NUC_IP] | grep -i error
    

    # Verify hardware detection
    talosctl get hardware --nodes [NUC_IP]

More nodes

Scaling

To add additional Intel NUC worker nodes:

  1. Follow hardware preparation steps
  2. Generate unique WireGuard keys
  3. Assign next available WireGuard IP (10.0.0.13, 10.0.0.14, etc.)
  4. Apply worker configuration
  5. Verify cluster integration

Lock it down

Security Considerations

  • Store WireGuard private keys securely
  • Use unique keys for each node
  • Consider using hardware TPM for key storage
  • Regular security updates via Talos upgrades
  • Monitor cluster access logs

Further reading

References

Questions

Frequently asked

What is Talos Linux?

Talos Linux is a minimal, immutable, API-driven operating system purpose-built for Kubernetes. It has no shell or SSH — every node is managed declaratively through talosctl and a machine config — which makes bare-metal nodes like Intel NUCs reproducible and secure.

Can I add bare-metal Intel NUCs to a cloud Kubernetes cluster?

Yes. This guide joins Intel NUC workers to an existing Talos control plane running on Hetzner by tunneling cluster traffic over WireGuard. Each NUC gets a unique WireGuard key and IP, applies a worker machine config, and registers as a standard worker node.

Why use WireGuard to join remote worker nodes?

WireGuard creates an encrypted overlay network so home-based NUCs and cloud control-plane nodes communicate securely across the public internet as if on one private subnet. It is lightweight, fast, and integrates directly into the Talos machine network config.

What are the minimum hardware requirements for a Talos NUC worker?

An Intel NUC 11th gen or newer with at least 8GB RAM (16GB recommended), a 256GB+ SSD (NVMe preferred), and gigabit Ethernet. Enable UEFI boot, disable Secure Boot, and turn on Intel VT-x/VT-d in the BIOS before installing Talos.

How do I troubleshoot a NUC that will not join the cluster?

Check WireGuard connectivity with wg show and ping the control-plane endpoint, inspect kubelet logs via talosctl logs --nodes, and confirm the cluster secrets and keys match. Most join failures trace back to an incorrect WireGuard key or an unreachable endpoint.

Keep exploring

Related applications

WireGuardThe encrypted overlay network that links home NUCs to the cloud control plane.KubernetesThe cluster these bare-metal workers join and serve.ProxmoxThe other homelab pillar — virtualized nodes alongside bare metal.