Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 5: Cluster anlegen

Ziel: Rancher ein RKE2-Cluster auf drei leeren VMs bauen lassen, die Rollen der Nodes festlegen, eine kubeconfig über Rancher holen und verstehen, wie Rancher die Nodes steuert. · Dauer: ca. 75 min · Voraussetzung: Tag 4

Briefing

  • Ein Custom Cluster baut Rancher auf Maschinen, die du selbst bereitstellst. Du beschreibst das Cluster als YAML, Rancher liefert einen Registrierungsbefehl.
  • Auf jedem Node läuft danach der rancher-system-agent. Er holt sich von Rancher einen Plan (welche Dateien, welche Dienste) und setzt ihn um. RKE2 installiert er selbst.
  • Die Rollen vergibst du pro Node: etcd, controlplane, worker. Im Labor hat werk1 alle drei, werk2 und werk3 sind Worker.
  • kubectl spricht mit dem neuen Cluster über den Rancher-Proxy. Die kubeconfig dafür erzeugt Rancher.
 VM rancher                                      VMs werk1..3
 ┌────────────────────────────┐   Plan holen    ┌───────────────────────────────┐
 │ Cluster werk (YAML)        │◄────────────────┤ rancher-system-agent          │
 │ Maschinen custom-…         │                 │   installiert und steuert RKE2 │
 │ Plan-Secrets custom-…-plan │ cluster-agent   │ werk1: etcd, controlplane,    │
 │ Proxy /k8s/clusters/c-m-…  │◄────────────────┤        worker                 │
 └──────────▲─────────────────┘                 │ werk2, werk3: worker          │
            │ kubectl (kube/werk.yaml)          └───────────────────────────────┘
          Mac

Drill 1: Drei leere VMs

source ~/rancher-lab/setup/env.sh
for n in 1 2 3; do
  multipass launch 24.04 --name "werk$n" --cpus 2 --memory 3G --disk 30G
done
for n in 1 2 3; do
  echo "export WERK$n=$(multipass info "werk$n" --format json \
    | jq -r ".info.werk$n.ipv4[0]")" >> "$LAB/setup/vms.env"
done
source "$LAB/setup/env.sh"
mkdir -p "$LAB/tag05" && cd "$LAB/tag05"
cp "$LAB/code/tag05/"* .

Erwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):

Launched: werk1
Launched: werk2
Launched: werk3

Mit 16 GB RAM auf dem Mac startest du nur werk1. Alles in diesem Buch funktioniert auch mit einem Node, nur Drain und Longhorn (Tag 10) brauchen mehr.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Cluster beschreiben

# tag05/cluster-werk.yaml – Stand Ende Tag 5: ein RKE2-Cluster, das Rancher baut
apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
  name: werk
  namespace: fleet-default
  labels:
    lab: rancher-lab
spec:
  kubernetesVersion: v1.36.5+rke2r1
  rkeConfig:
    machineGlobalConfig:
      cni: canal
    upgradeStrategy:
      controlPlaneConcurrency: "1"
      workerConcurrency: "1"

Anders als beim Import (Tag 4) gibt es ein rkeConfig. machineGlobalConfig landet als RKE2-Konfiguration auf jedem Node, upgradeStrategy legt fest, wie viele Nodes Rancher bei einem Upgrade gleichzeitig anfasst (Tag 12).

export KUBECONFIG="$LAB/kube/rancher.yaml"
kubectl apply --dry-run=server -f cluster-werk.yaml
kubectl apply -f cluster-werk.yaml
kubectl -n fleet-default get clusters.provisioning.cattle.io werk
ID=$(kubectl -n fleet-default get clusters.provisioning.cattle.io werk \
  -o jsonpath='{.status.clusterName}')
echo "$ID"

Erwartet (gekürzt):

cluster.provisioning.cattle.io/werk created (server dry run)
cluster.provisioning.cattle.io/werk created
NAME   VERSION          CLUSTER NAME   AGE   KUBECONFIG   READY
werk   v1.36.5+rke2r1   c-m-ct8fr7hj   4s
c-m-ct8fr7hj

Fortschritt speichern? Kostenlos registrieren

Drill 3: Der Registrierungsbefehl

Rancher legt wie in Tag 4 einen default-token an. Diesmal interessiert der Befehl für Nodes. So sieht er aus, mit verdecktem Token:

kubectl -n "$ID" get clusterregistrationtokens.management.cattle.io default-token \
  -o jsonpath='{.status.insecureNodeCommand}' \
  | sed -E 's/--ca-checksum [^ ]+/--ca-checksum <…>/'; echo

Erwartet (gekürzt):

 curl --insecure -fL https://rancher.….sslip.io/system-agent-install.sh | sudo  sh -s
- --server https://rancher.….sslip.io --label 'cattle.io/os=linux' --token {token}
--ca-checksum <…>

Der Befehl lädt den Installer des System-Agents und übergibt ihm die Adresse von Rancher, den Token und die Prüfsumme der Rancher-CA. Mit der Prüfsumme kontrolliert der Agent, dass er wirklich mit deinem Rancher spricht, obwohl curl --insecure nutzt. {token} ersetzt du wie in Tag 4.

Baue den Befehl einmal zusammen und hänge pro Node Name und Rollen an:

reg() {
  local c t
  c=$(kubectl -n "$ID" get clusterregistrationtokens.management.cattle.io \
    default-token -o jsonpath='{.status.insecureNodeCommand}')
  t=$(kubectl -n "$ID" get secret crt-token-default-token \
    -o jsonpath='{.data.token}' | base64 -d)
  printf '%s %s' "${c/\{token\}/$t}" "$1"
}

reg gibt den fertigen Befehl aus. Benutze die Funktion nur innerhalb von $( … ), dann landet der Token nie auf dem Bildschirm.

Fortschritt speichern? Kostenlos registrieren

Drill 4: werk1 mit allen Rollen

multipass exec werk1 -- bash -c \
  "$(reg '--node-name werk1 --etcd --controlplane --worker')" | tail -2

Erwartet:

Created symlink /etc/systemd/system/multi-user.target.wants/rancher-system-agent.servi…
[INFO]  Starting/restarting rancher-system-agent.service

Nach einer Viertelminute läuft der System-Agent. RKE2 gibt es auf der VM noch nicht; das installiert der Agent gleich selbst, sobald Rancher ihm den Plan schickt.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Zwei Worker

multipass exec werk2 -- bash -c "$(reg '--node-name werk2 --worker')" | tail -1
multipass exec werk3 -- bash -c "$(reg '--node-name werk3 --worker')" | tail -1
kubectl -n fleet-default get machines.cluster.x-k8s.io

Erwartet (gekürzt):

[INFO]  Starting/restarting rancher-system-agent.service
[INFO]  Starting/restarting rancher-system-agent.service
NAME                  CLUSTER   NODE NAME   …   READY     AVAILABLE   …   PHASE
custom-2eca1ac97cff   werk                  …   Unknown   False       …   Provisioning
custom-431ed8f98314   werk                  …   Unknown   False       …   Provisioning
custom-8e74ab3310e6   werk                  …   Unknown   False       …   Provisioning

Jeder registrierte Node wird zu einer Maschine (custom-…), einem Objekt aus Cluster API. Die Worker warten, bis die Control Plane auf werk1 steht.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Warten, aber richtig

kubectl -n fleet-default get clusters.provisioning.cattle.io werk
f='{range .status.conditions[?(@.type=="Ready")]}{.status} {.message}{end}'
kubectl -n fleet-default get clusters.provisioning.cattle.io werk -o jsonpath="$f"; echo

Erwartet (gekürzt, nach etwa vier Minuten):

NAME   VERSION          CLUSTER NAME   AGE     KUBECONFIG        READY
werk   v1.36.5+rke2r1   c-m-ct8fr7hj   5m43s   werk-kubeconfig   true
Unknown non-ready bootstrap machine(s) custom-431ed8f98314: Waiting for Cluster
control plane to be initialized and join url to be available on bootstrap …

Achtung: Die Spalte READY steht schon auf true, wenn Rancher die interne kubeconfig angelegt hat. Fertig ist das Cluster erst, wenn die Bedingung Ready True ist und alle Maschinen Running sind.

kubectl -n fleet-default wait clusters.provisioning.cattle.io/werk \
  --for=condition=Ready --timeout=900s
kubectl -n fleet-default get machines.cluster.x-k8s.io

Erwartet (gekürzt):

cluster.provisioning.cattle.io/werk condition met
NAME                  CLUSTER   NODE NAME   …   READY   AVAILABLE   …   PHASE
custom-2eca1ac97cff   werk      werk3       …   True    True        …   Running
custom-431ed8f98314   werk      werk1       …   True    True        …   Running
custom-8e74ab3310e6   werk      werk2       …   True    True        …   Running

Sieben bis acht Minuten nach der Registrierung von werk1 steht das Cluster. In Cluster Management ist es als Custom mit drei Maschinen zu sehen:

Drei Cluster: importiert, local und das neue werk

Ein Klick auf werk zeigt die Details. Erwartet: die Maschinen mit ihren Rollen wie in der Abbildung.

Detailseite von werk mit Maschinen und Rollen

Der Reiter Provisioning Log zeigt, was Rancher Schritt für Schritt getan hat, Registration den Befehl aus Drill 3 zum Kopieren.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Eine kubeconfig über Rancher

Das Secret werk-kubeconfig aus der Ausgabe oben ist für Rancher selbst und zeigt auf eine interne Adresse. Eine kubeconfig für dich erzeugt Rancher über seine API, genau wie der Knopf Download KubeConfig. Dafür brauchst du einen API-Token; den holt eine Anmeldung als admin:

R="https://rancher.$RANCHER.sslip.io"
( umask 077
  curl -sk -X POST "$R/v3-public/localProviders/local?action=login" \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","password":"lab-admin-pw-123","responseType":"json",
         "description":"rancher-lab cli"}' | jq -r .token > "$LAB/rancher-token" )
wc -c < "$LAB/rancher-token"
curl -sk -X POST -H "Authorization: Bearer $(cat "$LAB/rancher-token")" \
  "$R/v3/clusters/$ID?action=generateKubeconfig" | jq -r .config > "$LAB/kube/werk.yaml"
chmod 600 "$LAB/kube/werk.yaml"
grep -E 'server:|current-context' "$LAB/kube/werk.yaml"
kubectl --kubeconfig "$LAB/kube/werk.yaml" get nodes

Erwartet (gekürzt):

67
    server: "https://rancher.….sslip.io/k8s/clusters/c-m-ct8fr7hj"
current-context: "werk"
NAME    STATUS   ROLES                       AGE     VERSION
werk1   Ready    control-plane,etcd,worker   11m     v1.36.5+rke2r1
werk2   Ready    worker                      5m57s   v1.36.5+rke2r1
werk3   Ready    worker                      5m55s   v1.36.5+rke2r1

Der Server ist Rancher, nicht werk1. Jede Anfrage geht durch den Rancher-Proxy und den cattle-cluster-agent ins Cluster, und Rancher prüft dabei deine Rechte (Tag 6). Fällt Rancher aus, ist auch diese kubeconfig tot (Tag 14).

Sicherheit: rancher-token ist ein vollwertiger Admin-Zugang zu Rancher und allen Clustern. Er liegt nur mit Rechten 600 in ~/rancher-lab und gehört nie in ein Repository.

In der Oberfläche erreichst du dieselben Nodes über Explore:

Die drei Nodes von werk im Explorer

Fortschritt speichern? Kostenlos registrieren

Drill 8: Wie Rancher die Nodes steuert

Auf werk1 hat der System-Agent RKE2 installiert und eine eigene Konfigurationsdatei geschrieben:

multipass exec werk1 -- systemctl is-active rancher-system-agent rke2-server
multipass exec werk1 -- sudo ls /etc/rancher/rke2/config.yaml.d
multipass exec werk1 -- sudo grep -v token \
  /etc/rancher/rke2/config.yaml.d/50-rancher.yaml

Erwartet (gekürzt):

active
active
50-rancher.yaml
{
  "cni": "canal",
  …
  "node-label": [
    "cattle.io/os=linux",
    "plan.cattle.io/cluster-name=werk",
    …
  ],
  "node-name": "werk1",
  "private-registry": "/etc/rancher/rke2/registries.yaml"
}

cni: canal kommt aus machineGlobalConfig in Drill 2. Die Zeilen mit den Tokens filtert grep -v heraus, sie gehören nicht auf den Bildschirm. Die Pläne selbst liegen als Secrets im local-Cluster, einer pro Maschine:

kubectl -n fleet-default get secrets | grep -E 'NAME|machine-plan |rke-state'

Erwartet (gekürzt):

NAME                               TYPE                          DATA   AGE
custom-431ed8f98314-machine-plan   rke.cattle.io/machine-plan    15     20m
custom-44fc6b990590-machine-plan   rke.cattle.io/machine-plan    15     4m1s
custom-8e74ab3310e6-machine-plan   rke.cattle.io/machine-plan    15     19m
werk-rke-state                     rke.cattle.io/cluster-state   2      20m

Rancher schreibt den gewünschten Zustand in den Plan, der Agent auf dem Node holt ihn und meldet den Fortschritt zurück. So laufen später auch Upgrades (Tag 12) und etcd-Snapshots (Tag 13).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl --kubeconfig "$LAB/kube/werk.yaml" get nodes

Erwartet: drei Nodes, alle Ready, werk1 mit allen Rollen.

NAME    STATUS   ROLES                       AGE     VERSION
werk1   Ready    control-plane,etcd,worker   13m     v1.36.5+rke2r1
werk2   Ready    worker                      8m32s   v1.36.5+rke2r1
werk3   Ready    worker                      8m30s   v1.36.5+rke2r1
kubectl -n fleet-default get machines.cluster.x-k8s.io

Erwartet: drei Maschinen in Phase Running.

NAME                  CLUSTER   NODE NAME   …   READY   AVAILABLE   …   PHASE
custom-2eca1ac97cff   werk      werk3       …   True    True        …   Running
custom-431ed8f98314   werk      werk1       …   True    True        …   Running
custom-8e74ab3310e6   werk      werk2       …   True    True        …   Running
kubectl -n fleet-default get clusters.provisioning.cattle.io

Erwartet: k3s und werk, beide READY true.

NAME   VERSION          CLUSTER NAME   AGE   KUBECONFIG        READY
k3s                     c-m-5pjkcmvg   1h    k3s-kubeconfig    true
werk   v1.36.5+rke2r1   c-m-ct8fr7hj   14m   werk-kubeconfig   true

Challenge

Nimm werk3 aus dem Cluster, indem du seine Maschine löschst. Was bleibt auf der VM zurück? Bring werk3 danach als Worker zurück.

Hinweis: Auf jeder Node-VM liegen zwei Skripte zum Aufräumen unter /usr/local/bin.

Lösung

f='{range .items[?(@.status.nodeRef.name=="werk3")]}{.metadata.name}{end}'
M=$(kubectl -n fleet-default get machines.cluster.x-k8s.io -o jsonpath="$f")
kubectl -n fleet-default delete machines.cluster.x-k8s.io "$M"
kubectl --kubeconfig "$LAB/kube/werk.yaml" get nodes
multipass exec werk3 -- systemctl is-active rancher-system-agent rke2-agent
multipass exec werk3 -- sudo rancher-system-agent-uninstall.sh > /dev/null
multipass exec werk3 -- sudo rke2-uninstall.sh > /dev/null
multipass exec werk3 -- bash -c "$(reg '--node-name werk3 --worker')" | tail -1
kubectl --kubeconfig "$LAB/kube/werk.yaml" wait --for=condition=Ready node/werk3 \
  --timeout=600s

Erwartet (gekürzt):

machine.cluster.x-k8s.io "custom-2eca1ac97cff" deleted from fleet-default namespace
NAME    STATUS   ROLES                       AGE     VERSION
werk1   Ready    control-plane,etcd,worker   13m     v1.36.5+rke2r1
werk2   Ready    worker                      8m32s   v1.36.5+rke2r1
active
active
[INFO]  Starting/restarting rancher-system-agent.service
node/werk3 condition met

Das Löschen der Maschine dauert eine halbe Minute; der Node verschwindet aus dem Cluster. Auf der VM laufen RKE2 und der System-Agent aber weiter. Wer eine VM wieder verwenden will, räumt sie mit den beiden Skripten ab. Gut zwei Minuten nach der neuen Registrierung ist werk3 zurück, als neue Maschine mit neuem Namen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Rollen trennen: In Produktion laufen etcd und Control Plane auf drei eigenen Nodes, Anwendungen nur auf Workern. Die Rollen vergibst du mit denselben Flags.
  • Maschinen aus der Cloud: Mit machinePools und einem Node-Treiber (vSphere, Harvester, Amazon EC2, Azure) legt Rancher die VMs selbst an und ersetzt kaputte automatisch. Custom Clusters eignen sich für Blech und fremd verwaltete VMs.
  • Labels und Taints: --label und --taints im Registrierungsbefehl setzen sie schon beim Beitritt, etwa für GPU- oder Datenbank-Nodes.
  • Vorlagen: Ein Cluster-YAML im Git-Repository, ausgerollt per GitOps oder Terraform-Provider rancher2, macht Cluster reproduzierbar.
  • Tokens: Der Login-Token hat eine Laufzeit; für Automatisierung legst du eigene API-Tokens mit Ablaufdatum und begrenztem Umfang an (Tag 14).