Talos Linux - Installation and Setup

talos-linux-installation-and-setup.md

Talos Linux Installation Guide (macOS)

This guide walks you through creating a bootable Talos Linux USB drive from macOS and booting your target machine.

Prerequisites

• A USB flash drive (at least 2GB). Warning: All data on this drive will be erased.
• A Mac with Terminal access.
• Target machine (bare metal) with x86_64 architecture (amd64).

0. Install talosctl

Before you begin, install the talosctl CLI tool using Homebrew:

brew install talosctl

1. Download Talos Linux ISO

Option 1: CLI Download (Recommended)

Open Terminal and run the following commands to create a directory and download the ISO:

# Create a directory in your home folder
mkdir -p ~/talos-install
cd ~/talos-install

# Download the ISO image
curl -L -o metal-amd64.iso https://github.com/siderolabs/talos/releases/download/v1.12.3/metal-amd64.iso

Option 2: Browser Download

Alternatively, you can download the file manually: Download metal-amd64.iso

Note: If you need a different version or architecture (e.g., arm64), visit the Talos Releases Page or use the Talos Image Factory for custom images.

2. Identify Your USB Drive

Insert your USB flash drive into your Mac. Open Terminal and run:

diskutil list

Look for your USB drive in the output (it will likely be external, physical). Identify its identifier (e.g., /dev/disk2).

Caution

Be extremely careful identifying the disk number. Picking the wrong disk (like /dev/disk0 or /dev/disk1, which are usually your system drives) will result in permanent data loss.

3. Flash the ISO to USB

1. Unmount the disk so we can write to it (replace N with your disk number from step 2, e.g., disk2):

   diskutil unmountDisk /dev/diskN

2. Write the image. We will use dd to copy the ISO to the drive.

   • The command below uses the file we just downloaded to ~/talos-install.
   • Replace /dev/rdiskN with your disk identifier (e.g., /dev/rdisk2).

   sudo dd if=/Users/username/talos-install/metal-amd64.iso of=/dev/rdiskN bs=1m status=progress

   • Enter your macOS user password when prompted.
   • Wait for the process to finish. It may take a few minutes.

3. Eject the drive:

   diskutil eject /dev/diskN

4. Boot and Install

1. Insert the USB drive into your target machine.

2. Power on the machine and access the Boot Menu (usually F10, F12, or Esc depending on the manufacturer).

3. Select the USB drive to boot from.

4. Talos will boot into memory. It does not install to the disk automatically.

5. Once Talos is running, it will grab an IP address via DHCP. You can verify this on your router or simply wait a moment.

6. To install Talos to the machine's drive, you will need to use talosctl from your Mac to apply a configuration.

   (Optional) To bootstrap a single-node cluster from your Mac:

   # Create a directory for your cluster configuration (these files contain secrets!)
   mkdir -p ~/.talos/my-cluster
   cd ~/.talos/my-cluster
   
   # Generate configuration
   talosctl gen config my-cluster https://<TARGET_IP>:6443
   
   # Inspect available disks to check the install target (e.g., /dev/sda, /dev/nvme0n1)
   talosctl get disks --insecure --nodes <TARGET_IP>
   # Note: If this times out, ensure you are on the same network as the node.
   
   # Update the configuration file with the correct disk
   # open controlplane.yaml and change:
   # - `install: disk: /dev/sda` to your actual disk
   # - `allowSchedulingOnControlPlanes: true` to allow workloads to run on
   # the control plane node (recommended for single-node clusters)
   
   # Apply configuration to install (WARNING: Wipes target disk)
   talosctl apply-config --insecure --nodes <TARGET_IP> --file controlplane.yaml
   
   # Bootstrap the cluster
   talosctl bootstrap -n <TARGET_IP> -e <TARGET_IP> --talosconfig ./talosconfig
   
   # Access the dashboard
   talosctl dashboard -n <TARGET_IP> -e <TARGET_IP> --talosconfig ./talosconfig
   
   # View logs for a specific service (e.g., etcd)
   # The -f flag follows the log output
   talosctl logs -f -n <TARGET_IP> -e <TARGET_IP> --talosconfig ./talosconfig etcd
   
   # List all services
   talosctl -n <TARGET_IP> -e <TARGET_IP> --talosconfig ./talosconfig services
   
   # Retrieve kubeconfig
   talosctl -e <TARGET_IP> -n <TARGET_IP> --talosconfig ./talosconfig kubeconfig ./kubeconfig
   
   # Set KUBECONFIG environment variable (for current session)
   export KUBECONFIG=~/.talos/my-cluster/kubeconfig
   
   # Verify cluster status with kubectl (alias 'k' is common)
   kubectl get nodes