Skip to main content

Install Talos Linux for Kubernetes

Talos Linux is a specialized operating system developed by Sidero Labs and designed for running Kubernetes.

It runs in the server's RAM and uses the latest stable Talos version from official releases — more details on the Releases page in the Sidero Labs GitHub repository.

You can connect to a server with Talos via VNC or via the KVM console.

  1. Prepare parameters for cluster node configuration.
  2. Prepare the cluster node configuration.
  3. Apply the configuration to the Control Plane node.
  4. Apply the configuration to the Worker node.
  5. Initialize Kubernetes.

1. Prepare parameters for cluster node configuration

To prepare the configuration files for the Control Plane and Worker nodes, you need to collect the parameters for each server that will be part of the cluster.

  1. Boot the server into Rescue recovery and diagnostics mode.

  2. Connect to the server via SSH or via the KVM console.

  3. Output information about the network configuration:

    ip a && ip r

    The output will contain information about the network interfaces. Copy and save the network parameters. For example:

    2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
        link/ether 1c:1b:0d:65:43:21 brd ff:ff:ff:ff:ff:ff
        altname eno1
        altname enp4s0f0
        altname enxac1f6b47814a
        inet 203.0.113.10/24 brd 203.0.113.255 scope global eth0

    default via 203.0.113.1 dev eth0
    203.0.113.0/24 dev eth0 proto kernel scope link src 203.0.113.10

    Where:

    • 203.0.113.10 — public IP address of the server. The dedicated server IP address can also be viewed in the Control Panel: in the top menu, select Products → Dedicated Servers → Servers → server card → IP address;
    • 203.0.113.1 — default gateway;
    • /24 — subnet mask;
    • 1c:1b:0d:65:43:21 — MAC address of the network interface.

  4. Select the disk to install the Talos OS on. To do this, output the list of disks:

    lsblk

    The output will contain information about the disks. Copy and save the name of the disk you will install the OS on. For example:

    NAME  MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
    loop0   7:0    0 547.9M  1 loop /run/archiso/airootfs
    sda     8:0    0 447.1G  0 disk
    sdb     8:16   0 447.1G  0 disk
    sdc     8:32   0   3.6T  0 disk
    sdd     8:48   0   3.6T  0 disk

  5. Change the server boot template. You can:

    • return to the previous server boot template or reboot the server from the OS. When rebooting the server from the OS, the boot template will automatically revert to the one set before booting the server in Rescue mode;
    • or boot the server directly in Talos mode to continue installing Talos Linux.

  6. Repeat steps 1-5 for each server in the cluster.

2. Prepare the cluster node configuration

  1. Ensure that the talosctl client is installed on the server from which you will install the Talos OS.

  2. Create a base cluster configuration:

    talosctl gen config my-cluster https://<ip_address>:6443

    Specify <ip_address> — the public IP address of the Control Plane server, which you saved in step 3 while preparing parameters in stage 1. The dedicated server IP address can also be viewed in the Control Panel: in the top menu, select Products → Dedicated Servers → Servers → server card → IP address.

    The output will contain information about successful configuration generation. For example:

    generating PKI and tokens
    created controlplane.yaml
    created worker.yaml
    created talosconfig

    Where:

    • controlplane.yaml — configuration template for the Control Plane node;
    • worker.yaml — configuration template for Worker nodes;
    • talosconfig — configuration for the talosctl client.

  3. Create a patch file for the Control Plane node:

    3.1. Create a patch file for the Control Plane node using the vi text editor:

    vi <file_name>

    Specify <file_name> — the name of the file in yaml format, for example patch-cp1.yaml.

    3.2. Add the configuration to the file:

    cluster:
        allowSchedulingOnControlPlanes: true
    machine:
        install:
            disk: /dev/<disk>
        network:
            interfaces:
            - deviceSelector:
                    hardwareAddr: "<mac_address>"
                addresses:
                    - <ip_address>/<mask>
                routes:
                    - network: 0.0.0.0/0
                    gateway: <gateway>
                dhcp: false
            nameservers:
                - <dns_server>

    Specify:

    3.3. Exit the vi text editor, saving your changes:

    :wq

  4. If the cluster uses multiple servers, create a configuration for the Worker node. For a single server (Single Node Cluster), you can skip creating configurations for Worker nodes.

    4.1. Create a patch file for the Worker node using the vi text editor:

    vi <file_name>

    Specify <file_name> — the name of the file in yaml format, for example patch-worker1.yaml.

    4.2. Add the configuration to the file:

    machine:
    install:
        disk: /dev/<disk>
    network:
        interfaces:
        - deviceSelector:
                hardwareAddr: "<mac_address>"
            addresses:
                - <ip_address>/<mask>
            routes:
                - network: 0.0.0.0/0
                gateway: <gateway>
            dhcp: false
        nameservers:
            - <dns_server>

    Specify:

    4.3. Exit the vi text editor, saving your changes:

    :wq

    4.4. If you plan to have a cluster of multiple servers, repeat steps 4.1-4.3 to create separate patch files for each Worker node.

3. Apply the configuration to the Control Plane node

  1. Boot the Control Plane server into Rescue recovery and diagnostics mode with the Talos template.

  2. Connect to the server via VNC or via the KVM console.

  3. Ensure the server is in Maintenance mode:

    STAGE: Maintenance

  4. Apply the Control Plane node configuration:

    talosctl apply-config \
        --insecure \
        -e <ip_address> \
        -n <ip_address> \
        --file controlplane.yaml \
        --config-patch @<file_name>

    Specify:

    After applying the configuration, you will receive the response Applied configuration without a reboot, and the server will enter STAGE: Installing.

  5. Wait for the OS installation to complete — the server will automatically reboot and enter KUBELET: Healthy.

4. Apply the configuration to the Worker node

  1. Boot the Worker server into Rescue recovery and diagnostics mode with the Talos template.

  2. Connect to the server via VNC or via the KVM console.

  3. Ensure the server is in Maintenance mode:

    STAGE: Maintenance

  4. Apply the Worker node configuration:

    talosctl apply-config \
        --insecure \
        -e <ip_address> \
        -n <ip_address> \
        --file worker.yaml \
        --config-patch @<file_name>

    Specify:

    After applying the configuration, you will receive the response Applied configuration without a reboot, and the server will enter STAGE: Installing.

  5. Wait for the OS installation to complete — the server will automatically reboot and enter KUBELET: Healthy.

5. Initialize Kubernetes

  1. Create a Kubernetes cluster:

    talosctl bootstrap \
        --nodes <ip_address> \
        --endpoints <ip_address> \
        --talosconfig ./talosconfig

    Specify <ip_address> — the public IP address of the Control Plane server, which you saved in step 3 while preparing parameters in stage 1. The dedicated server IP address can also be viewed in the Control Panel: in the top menu, select Products → Dedicated Servers → Servers → server card → IP-address.

  2. Get the configuration file for managing the Kubernetes cluster:

    talosctl kubeconfig \
        --nodes <ip_address> \
        --endpoints <ip_address> \
        --talosconfig ./talosconfig

    Specify <ip_address> — the public IP address of the Control Plane server, which you saved in step 3 while preparing parameters in stage 1. The dedicated server IP address can also be viewed in the Control Panel: in the top menu, select Products → Dedicated Servers → Servers → server card → IP-address.

    The Kubernetes configuration file is saved by default at ~/.kube/config.

  3. Check the status of the Kubernetes nodes:

    kubectl get nodes -o wide

    The output will contain information about node statuses. For example:

    NAME            STATUS   ROLES           VERSION
    talos-lv9-t5t   Ready    control-plane   v1.36.0
    talos-xc9-jfu   Ready    <none>          v1.36.0
    talos-ee2-e9f   Ready    <none>          v1.36.0

    All nodes must have the Ready status.

  4. Check the system pods:

    kubectl get pods -A

    The output will contain information about the pod statuses. For example:

    NAMESPACE     NAME                                        READY   STATUS    RESTARTS   AGE
    kube-system   kube-apiserver-talos-lv9-t5t                1/1     Running   0          5m
    kube-system   kube-controller-manager-talos-lv9-t5t       1/1     Running   0          5m
    kube-system   kube-scheduler-talos-lv9-t5t                1/1     Running   0          5m
    kube-system   coredns-xxxxxxxxxx-xxxxx                    1/1     Running   0          5m

    Core system pods must have the Running status.

  5. Check the list of cluster participants:

    talosctl \
        --talosconfig ./talosconfig \
        -e <ip_address> \
        -n <ip_address> \
        get members

    Specify <ip_address> — the public IP address of the Control Plane server, which you saved in step 3 while preparing parameters in stage 1. The dedicated server IP address can also be viewed in the Control Panel: in the top menu, select Products → Dedicated Servers → Servers → server card → IP-address.

    The output will contain information about the cluster nodes. For example:

    NODE            NAMESPACE   TYPE     ID              VERSION   HOSTNAME        MACHINE TYPE   OS                ADDRESSES
    203.0.113.10    cluster     Member   talos-ee2-e9f   1         talos-ee2-e9f   worker         Talos (v1.13.0)   ["203.0.113.12"]
    203.0.113.10    cluster     Member   talos-lv9-t5t   1         talos-lv9-t5t   controlplane   Talos (v1.13.0)   ["203.0.113.11"]
    203.0.113.10    cluster     Member   talos-xc9-jfu   2         talos-xc9-jfu   worker         Talos (v1.13.0)   ["203.0.113.10"]

    Ensure that all servers are present in the list and have the correct roles.