Instalacja k3s na maszynach fizycznych — krok po kroku i z użyciem Terraform

Instalacja małego klastra Kubernetes z użyciem k3s na homelabie

Page content

Oto krok po kroku instrukcja instalacji
3-węzłowego klastra K3s
na serwerach nago metalowych (1 serwer główny + 2 serwery robocze).

Przewodnik zakłada, że zaczynasz od minimalnej instalacji
Linux
(np. Ubuntu 22.04 lub Debian) na każdym serwerze,
i chcesz samodzielnie hostować swoją płaszczyznę sterowania i obciążenia.

kubernetes baremetal cluster

K3s
jest
lekką wersją Kubernetes,
która dobrze nadaje się do tego małego laboratorium domowego.

⚙️ Topologia klastra

Nazwa węzła Rola Hostname/IP
master-1 Serwer (Płaszczyzna sterowania) 192.168.1.100
worker-1 Agent (Węzeł roboczy) 192.168.1.101
worker-2 Agent (Węzeł roboczy) 192.168.1.102

✅ Wymagania wstępne

🧱 Sprzęt (minimalny):

  • Procesor: 2 rdzenie
  • Pamięć: 2 GB+ na węzeł
  • Dysk: 20 GB+ na węzeł

🛠 Wymagania systemowe:

  • Linux (Ubuntu 22.04, Debian 12 itp.)
  • Zainstalowane: curl, ssh i sudo
  • Dostęp roota lub sudo

🧼 Czysta sieć:

  • Upewnij się, że wszystkie węzły mogą rozwiązywać i pingować się nawzajem według IP lub nazwy hosta.

  • Wyłącz wymianę (swap):

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

🚀 Krok po kroku instalacja

📍Krok 1: Instalacja K3s na płaszczyźnie sterowania (master-1)

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

Po instalacji:

sudo cat /var/lib/rancher/k3s/server/node-token
  • To daje Ci token dołączenia, który jest potrzebny dla węzłów roboczych.

Potwierdź, że klaster działa:

sudo kubectl get nodes

k3s zawiera zainstalowany kubectl, który jest dostępny jako k3s kubectl lub jako symlink kubectl.

📍Krok 2: Instalacja agentów K3s (worker-1 & worker-2)

Powtórz na każdym węźle roboczym:

Zastąp <MASTER_IP> i <NODE_TOKEN> wartościami z kroku 1.

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

Przykłady:

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

📍Krok 3: Weryfikacja klastra z master-1

kubectl get nodes

Powinieneś zobaczyć:

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

🔐 (Opcjonalnie) Włączenie wysokiej dostępności (HA)

Dla HA podobnego do produkcji (opcjonalne w laboratorium domowym):

  • Użyj zewnętrznego bazy danych (np. MySQL/PostgreSQL/etcd).
  • Uruchom wiele węzłów serwerowych z flagą --server i wspólną bazą danych.
  • Zobacz: Dokumentacja K3s HA

🧪 Test wdrożenia

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

Sprawdź dostępność za pomocą curl http://<worker-ip>:<port> lub ustaw MetalLB dla IP LoadBalancer zewnętrznych.

🧰 Przydatne informacje

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

    • Skopiuj do swojego lokalnego komputera i ustaw export KUBECONFIG=..., aby zarządzać zdalnie.

  • Usługi systemd:

    • sudo systemctl status k3s
    • sudo systemctl status k3s-agent (na węzłach roboczych)

💡 Dodatki (opcjonalnie)

  • K9s: Interfejs terminala do zarządzania Kubernetes: brew install k9s lub sudo snap install k9s

  • Dashboard: Włącz za pomocą manifestów:

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

  • MetalLB: Dodaj wsparcie dla load balancing na nago metal:

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

📦 Czyszczenie

Aby usunąć k3s:

# Na serwerze głównym:
/usr/local/bin/k3s-uninstall.sh

# Na węźle roboczym:
/usr/local/bin/k3s-agent-uninstall.sh

Instalacja 3-węzłowego klastra K3s na nago metal za pomocą Terraform

Oto Terraform szablon,
który pomaga w przygotowaniu 3-węzłowego klastra K3s na nago metal, zakładając, że zarządzasz już przygotowanymi serwerami Linux (np. w sieci LAN/laboratorium domowym) za pomocą SSH i Ansible. Terraform wywoła playbooki Ansible, aby zainstalować K3s.

🧱 Zakłady

  • Masz już:

    • 3 serwery z ustalonymi adresami IP, dostępne przez SSH.
    • Dostęp SSH (kluczowy).
    • Lokalnie zainstalowane Terraform i Ansible.

  • System docelowy: Ubuntu/Debian (można dostosować).

  • Używasz Terraform local-exec lub wtyczki Ansible do Terraform (użyjemy local-exec tutaj dla portowalności).

📁 Struktura katalogów

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: Instalacja k3s master
      shell: |
        curl -sfL https://get.k3s.io | sh -        
    - name: Pobranie node-token
      shell: cat /var/lib/rancher/k3s/server/node-token
      register: node_token
      delegate_to: localhost

- hosts: workers
  become: yes
  tasks:
    - name: Dołączenie węzła roboczego do klastra
      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 -

Uwaga: Możesz być zmuszony do dostosowania dostępu do zmiennej IP lub tokena w zależności od wersji Ansible. Możesz również wygenerować token na serwerze głównym i zapisać go do pliku przed uruchomieniem instalacji węzła roboczego.

🚀 Jak uruchomić

Z katalogu k3s-cluster/:

terraform init
terraform apply

🧰 Ulepszenia (opcjonalnie)

  • Użyj dynamicznego generowania listy hostów (np. z DHCP/dnsmasq).
  • Dodaj wdrożenie MetalLB za pomocą Ansible.
  • Dodaj nazwy hostów i funkcje HA.
  • Zastąp rolą Ansible taką jak xanmanning.k3s dla większej elastyczności.

Przydatne linki