Het installeren van k3s op baremetal - stap-voor-stap walkthrough en met terraform

Installeren van little k3s Kubernetes op homelab-cluster

Inhoud

Hier is een stap-voor-stap walkthrough van
installatie van een 3-knooppunt K3s cluster
op bare-metal servers (1 master + 2 workers).

Deze gids veronderstelt dat je begint met een minimale
Linux installatie
(bv. Ubuntu 22.04 of Debian) op elke server,
en dat je je controleplane en workloads zelf wilt hosten.

kubernetes baremetal cluster

K3s
is een
lichtgewicht variant van Kubernetes,
die goed werkt voor deze kleine homelab.

⚙️ Cluster Topologie

Node Naam Rol Hostnaam/IP
master-1 Server (Control Plane) 192.168.1.100
worker-1 Agent (Worker Node) 192.168.1.101
worker-2 Agent (Worker Node) 192.168.1.102

✅ Voorwaarden

🧱 Hardware (Minimum):

  • CPU: 2 cores
  • RAM: 2GB+ per knooppunt
  • Schijf: 20GB+ per knooppunt

🛠 OS Voorwaarden:

  • Linux (Ubuntu 22.04, Debian 12, enz.)
  • curl, ssh, en sudo geïnstalleerd
  • Root of sudo toegang

🧼 Netwerk:

  • Zorg ervoor dat alle knooppunten elkaar kunnen oplossen en pingen via IP of hostnaam.

  • Schakel swap uit:

    sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

🚀 Stap-voor-stap installatie

📍 Stap 1: Installeer K3s op de controleplane (master-1)

curl -sfL https://get.k3s.io | sh -

Na installatie:

sudo cat /var/lib/rancher/k3s/server/node-token
  • Dit geeft je de aanmeldtoken dat nodig is voor de worker-knooppunten.

Controleer of het cluster draait:

sudo kubectl get nodes

k3s bevat een kubectl geïnstalleerd als k3s kubectl of als symlink kubectl.

📍 Stap 2: Installeer K3s Agents (worker-1 & worker-2)

Herhaal dit op elk worker-knooppunt:

Vervang <MASTER_IP> en <NODE_TOKEN> met de waarden uit stap 1.

curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.100:6443 K3S_TOKEN=<NODE_TOKEN> sh -

Voorbeelden:

K3S_URL=https://192.168.1.100:6443 \
K3S_TOKEN=K10abcde123456789::server:abcde123456789 \
sh -c "$(curl -sfL https://get.k3s.io)"

📍 Stap 3: Controleer het cluster vanaf master-1

kubectl get nodes

Je zou moeten zien:

NAME        STATUS   ROLES    AGE   VERSION
master-1    Ready    control  5m    v1.29.2+k3s1
worker-1    Ready    <none>   2m    v1.29.2+k3s1
worker-2    Ready    <none>   2m    v1.29.2+k3s1

🔐 (Optioneel) Schakel High Availability (HA) in

Voor productie-achtige HA (optioneel in home labs):

  • Gebruik een externe DB (bv. MySQL/PostgreSQL/etcd).
  • Start meerdere serverknooppunten met de --server vlag en gedeelde DB.
  • Zie: K3s HA Doc

🧪 Test een implementatie

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --type=LoadBalancer
kubectl get svc

Controleer toegang via curl http://<worker-ip>:<poort> of stel MetalLB in voor externe LoadBalancer IP’s.

🧰 Nuttige aantekeningen

  • Kubeconfig: /etc/rancher/k3s/k3s.yaml

    • Kopieer naar je lokale machine en export KUBECONFIG=... om af te handelen vanaf afstand.

  • Systemd Services:

    • sudo systemctl status k3s
    • sudo systemctl status k3s-agent (op workers)

💡 Extra’s (Optioneel)

  • K9s: Terminal UI voor het beheren van Kubernetes: brew install k9s of sudo snap install k9s

  • Dashboard: Schakel in met manifesten:

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

  • MetalLB: Voeg load balancing ondersteuning toe voor bare-metal:

    kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

📦 Opheffen

Om k3s te verwijderen:

# Op master:
/usr/local/bin/k3s-uninstall.sh

# Op worker:
/usr/local/bin/k3s-agent-uninstall.sh

Installeer een 3-knooppunt bare-metal K3s cluster met Terraform

Hier is een Terraform sjabloon
die helpt bij het inrichten van een 3-knooppunt bare-metal K3s cluster, aangenomen dat je al ingebruik genomen Linux-servers beheert (bv. in je LAN/home lab) via SSH en Ansible. Terraform zal Ansible playbooks aanroepen om K3s te installeren.

🧱 Aannames

  • Je hebt al:

    • 3 servers met vaste IP-adressen, toegankelijk via SSH.
    • SSH-toegang (sleutelgebaseerd).
    • Terraform en Ansible lokaal geïnstalleerd.

  • Doel OS: Ubuntu/Debian (kan worden aangepast).

  • Je gebruikt Terraform local-exec of Ansible provisioner plugin (we gebruiken hier local-exec voor draagbaarheid).

📁 Mapstructuur

k3s-cluster/
├── main.tf
├── inventory.ini
├── ansible/
│   └── install_k3s.yml
└── variables.tf

📄 variables.tf

variable "master_ip" {
  default = "192.168.1.100"
}

variable "worker_ips" {
  default = ["192.168.1.101", "192.168.1.102"]
}

variable "ssh_user" {
  default = "your_user"
}

variable "ssh_private_key" {
  default = "~/.ssh/id_rsa"
}

📄 main.tf

provider "null" {}

resource "null_resource" "install_k3s" {
  provisioner "local-exec" {
    command = "ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -i inventory.ini ansible/install_k3s.yml --private-key ${var.ssh_private_key} -u ${var.ssh_user}"
  }

  triggers = {
    always_run = "${timestamp()}"
  }
}

📄 inventory.ini

[masters]
192.168.1.100

[workers]
192.168.1.101
192.168.1.102

[all:vars]
ansible_python_interpreter=/usr/bin/python3

📄 ansible/install_k3s.yml

---
- hosts: masters
  become: yes
  tasks:
    - name: Installeer k3s master
      shell: |
        curl -sfL https://get.k3s.io | sh -        
    - name: Haal node-token op
      shell: cat /var/lib/rancher/k3s/server/node-token
      register: node_token
      delegate_to: localhost

- hosts: workers
  become: yes
  tasks:
    - name: Voeg worker toe aan cluster
      shell: |
        curl -sfL https://get.k3s.io | K3S_URL=https://{{ hostvars['192.168.1.100']['ansible_host'] }}:6443 K3S_TOKEN={{ hostvars['192.168.1.100']['node_token']['stdout'] }} sh -

Opmerking: Je moet mogelijk de IP- of tokenvariabele toegang aanpassen afhankelijk van Ansible-versies. Je kunt ook het token op de master genereren en opslaan in een bestand voordat je de worker-installatie uitvoert.

🚀 Hoe uit te voeren

Vanuit de k3s-cluster/ map:

terraform init
terraform apply

🧰 Verbeteringen (Optioneel)

  • Gebruik dynamische inventarisgeneratie (bv. vanaf DHCP/dnsmasq).
  • Voeg MetalLB-implementatie toe via Ansible.
  • Voeg hostnamen en HA-functies toe.
  • Vervang met Ansible rol zoals xanmanning.k3s voor meer flexibiliteit.