Homelab - Day 2 - Setting Up a New K3s Control Plane and Node

Posted on Fri 21 February 2025 in homelab

After going back and forth multiple times and making plenty of mistakes, I finally managed to set up a new K3s control plane and node. It turned out to be relatively straightforward once I got the steps right, so I’m documenting this for future reference!

Aims

The goal was to set up a fresh K3s cluster, ensuring that: - The control plane and node are configured correctly. - Flux is properly bootstrapped to manage cluster state. - Common pitfalls are documented to save time in the future.

What I Did

Control Plane Setup

  1. Install K3s: sh curl -sfL https://get.k3s.io | sh
  2. Add an SSH key for Flux to connect to GitHub.
  3. Bootstrap Flux with Git: sh flux bootstrap git \ --url=ssh://git@github.com/<your-repo> \ --branch=main \ --private-key-file=/home/<user>/.ssh/<flux_key> \ --path=clusters/k3s
  4. Retrieve the control plane token: sh cat /var/lib/rancher/k3s/server/token
  5. Allow traffic on the K3s API port: sh iptables -A INPUT -p tcp --dport 6443 -j ACCEPT

Node Setup

To join a new node to the cluster:

K3S_TOKEN="<your-k3s-token>" \
K3S_URL="<your-k3s-url>" \
sh -c "$(curl -sfL https://get.k3s.io)"

Lessons Learned

CA Certificates Issues

  • I kept running into problems with CA certificates not being authorized. This was likely due to wiping the server and recreating it multiple times or some Flux configuration persisting in the repository.
  • Fix: sh sudo cp <path-to-ca-cert> <path-to-cert-destination> sudo update-ca-certificates

Image Pull Failures

  • At one point, I was pulling my hair out trying to figure out why I couldn't pull container images. After a lot of debugging, it turned out that docker.io was simply down.
  • Lesson: Always check by running: sh ping docker.io
  • Sometimes (though rarely), it's not your fault!

Final Thoughts

Despite the initial struggles, setting up K3s is quite straightforward. The biggest challenges I faced were external issues (e.g., Docker Hub being down) and ensuring CA certificates were recognized properly. Hopefully, this documentation will make things smoother next time!

Have you run into similar K3s setup challenges? Let me know how you solved them!