Adding more nodes to an existing Talos Kubernetes cluster is straightforward. This guide includes optional automation steps that streamline the process, such as editing node configuration files, but these can also be performed manually.

Assumptions

Before proceeding, ensure the following conditions are met:

  1. You have deployed a single-node Talos-based Kubernetes cluster following the instructions in this guide.
  2. The additional node will also have the control-plane role. (If this is not the case, additional node configuration editing will be required.)
  3. Talos is already installed on the new node, and it is currently in “Maintenance” mode with an IP address assigned.
  4. (Optional) You are using GitOps for storing Kubernetes configuration.

Steps to Add a Node

1. (Optional) Install yq

yq is a YAML processor required for modifying the node configuration. Install the correct version using the commands below, do not use apt install yq:

sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq
sudo chmod +x /usr/bin/yq

2. Create a New Folder for Machine Configurations

If you plan to store the cluster configuration in a Git repository, create the folder in the root of the repository:

mkdir -p machineconfigs

3. (Optional) Prepare a Temporary Patch File

Create a temporary patch file to replace the node hostname or to make other changes. For example:

# machineconfigs/temp-n2-patch.yaml
---
- op: replace
  path: /machine/network/hostname
  value: n2

4. Pull the Existing Node Configuration, Patch It, and Save It

Retrieve the configuration of the existing node (e.g., n1), apply the patch, and save the configuration for the new node (e.g., n2):

export N1_IP=<Node N1 IP address>
talosctl -n $N1_IP get machineconfig -o yaml | yq eval '.spec' - > machineconfigs/n1.yaml
talosctl machineconfig patch --patch @machineconfigs/temp-n2-patch.yaml machineconfigs/n1.yaml | yq . > machineconfigs/n2.yaml

You can make the same edit manually without using yq and patch file but it might be tricky:

export N1_IP=<Node N1 IP address>
talosctl -n $N1_IP get machineconfig -o yaml > machineconfigs/n1.yaml
cp machineconfigs/n1.yaml machineconfigs/n2.yaml
# edit machineconfigs/n2.yaml manually

5. Apply the Configuration to the New Node

Set the IP address of the new node and apply the configuration:

export N2_IP=xxx.xxx.xxx.184
talosctl --nodes $N2_IP apply-config --file machineconfigs/n2.yaml --insecure

6. Update Talos Config

Edit ~/.talos/config and add new node in Endpoints: and Nodes: sections (Optional) Do the same for talosconfig in your repo.

7. (Optional) Encrypt and Commit Configuration Files to Git

If you’re using GitOps, encrypt the configuration files before committing them to the repository. Ensure the files are encrypted by verifying that secretboxEncryptionSecret contains the expected value.

Encrypt the files:

sops -e -i machineconfigs/n1.yaml
sops -e -i machineconfigs/n2.yaml

Verify the encryption in n2.yaml:

if grep -q "secretboxEncryptionSecret: ENC\[AES256_GCM" machineconfigs/n2.yaml; then
  echo "[INFO] Encryption verified for n2.yaml"
else
  echo "[WARNING] Encryption failed for n2.yaml"
fi

If the encryption is successful, commit the changes to your Git repository:

git add -A
git commit -m "Nodes machineconfig files"
git push origin main

Notes

  • The example above assumes the new node’s hostname is n2. Adjust the hostname in temp-n2-patch.yaml and other relevant commands if needed.
  • Always verify that the configuration files are encrypted properly before pushing them to a repository to avoid exposing sensitive information.
  • If additional configuration changes are required (e.g., non-control-plane roles), edit the generated machine configuration files (n1.yaml and n2.yaml) accordingly.