Tag 12: Upgrades
Ziel: Verstehen, welche Kubernetes-Versionen Rancher erlaubt und wo diese Grenze sitzt, ein importiertes k3s über Rancher aktualisieren und festlegen, wie Rancher werk bei einem Upgrade leert. · Dauer: ca. 60 min · Voraussetzung: Tag 11
Briefing
- Jede Rancher-Version unterstützt ein festes Fenster an Kubernetes-Versionen, die Support-Matrix. Rancher 2.15.3 kennt RKE2 und k3s bis v1.36.
- Upgrades von angelegten Clustern (werk) fährt Rancher über Pläne für
den System-Agent (Tag 5), Node für Node nach
upgradeStrategy. - Importierte k3s- und RKE2-Cluster aktualisiert Rancher mit dem
system-upgrade-controller: Ein
Planbeschreibt Zielversion und Nodes, ein Job pro Node tauscht das Binary aus. - Die richtige Reihenfolge: erst Rancher, dann die Cluster. Sonst verwaltet ein altes Rancher Cluster, die es nicht kennt.
Rancher (local) k3s (importiert)
Cluster c-m-…: spec.k3sConfig.kubernetesVersion ─► Plan k3s-master-plan
Job apply-k3s-master-plan-on-k3s
├ cordon
├ k3s-Binary tauschen, Neustart
└ uncordon
Drill 1: Welche Versionen Rancher kennt
source ~/rancher-lab/setup/env.sh
mkdir -p "$LAB/tag12" && cd "$LAB/tag12"
cp "$LAB/code/tag12/"* .
export KUBECONFIG="$LAB/kube/rancher.yaml"
R="https://rancher.$RANCHER.sslip.io"
H="Authorization: Bearer $(cat "$LAB/rancher-token")"
curl -sk -H "$H" "$R/v1-rke2-release/releases" | jq -r '.data[].id' | sort -V | tail -3
curl -sk -H "$H" "$R/v1-k3s-release/releases" | jq -r '.data[].id' | sort -V | tail -3
kubectl get settings.management.cattle.io rke2-default-version k3s-default-version \
-o custom-columns=NAME:.metadata.name,VALUE:.valueErwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):
v1.36.3+rke2r1
v1.36.4+rke2r1
v1.36.5+rke2r1
v1.36.3+k3s1
v1.36.4+k3s1
v1.36.5+k3s1
NAME VALUE
rke2-default-version 1.36.5+rke2r1
k3s-default-version 1.36.5+k3s1
Die Listen kommen aus Ranchers Metadaten (KDM, „Kontainer Driver Metadata”), die Rancher regelmäßig aktualisiert. werk und k3s laufen schon auf der höchsten Version, die Rancher 2.15.3 kennt. Die Oberfläche zeigt das auch: Unter Edit Config von werk stehen nur unterstützte Versionen zur Wahl.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Die Grenze sitzt in der Oberfläche
Was sagt die API, wenn jemand eine Version außerhalb der Liste einträgt? Ein Probelauf genügt:
kubectl -n fleet-default patch clusters.provisioning.cattle.io werk --type merge \
--dry-run=server -p '{"spec":{"kubernetesVersion":"v1.37.1+rke2r1"}}'Erwartet:
cluster.provisioning.cattle.io/werk patched
Achtung: Rancher lehnt die Version nicht ab. Die Support-Matrix erzwingt nur die Oberfläche; per
kubectl, Terraform oder GitOps lässt sich eine nicht unterstützte Version eintragen. Prüfe Versionen vor jedem Upgrade gegen die Matrix aufsuse.com/suse-rancher/support-matrix.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Wie k3s seine Version bekommt
Beim importierten k3s steht die gewünschte Version im Management-Cluster:
K3S_ID=$(kubectl -n fleet-default get clusters.provisioning.cattle.io k3s \
-o jsonpath='{.status.clusterName}')
kubectl get clusters.management.cattle.io "$K3S_ID" -o jsonpath='{.spec.k3sConfig}'
echo
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get plans.upgrade.cattle.io -AErwartet:
{"k3supgradeStrategy":{"serverConcurrency":1,"workerConcurrency":1},
"kubernetesVersion":"v1.36.5+k3s1"}
NAMESPACE NAME IMAGE … COMPLETE
cattle-system system-agent-upgrader rancher/system-agent … True
cattle-system system-agent-upgrader-windows rancher/wins … True
Den system-upgrade-controller hat Rancher beim Import mitgebracht (Tag 4). Bisher gibt es nur Pläne für den System-Agent, noch keinen für k3s selbst.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Das Upgrade
Für das Labor hebst du k3s auf v1.37.1, die aktuelle k3s-Version. Sie
liegt außerhalb der Matrix von Rancher 2.15.3; die Mechanik ist dieselbe
wie bei jedem unterstützten Upgrade, und k3s ist das Cluster, dessen
Verlust am wenigsten schmerzt. Starte vorher im zweiten Terminal die
Messschleife gegen notes.$K3S.sslip.io (Tag 10, Drill
6).
kubectl patch clusters.management.cattle.io "$K3S_ID" --type merge \
-p '{"spec":{"k3sConfig":{"kubernetesVersion":"v1.37.1+k3s1"}}}'
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get plans.upgrade.cattle.io -n cattle-system
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get nodesErwartet (gekürzt, nach etwa einer Minute):
cluster.management.cattle.io/c-m-5pjkcmvg patched
NAME IMAGE … VERSION COMPLETE
k3s-master-plan rancher/k3s-upgrade … v1.37.1+k3s1 False
k3s-worker-plan rancher/k3s-upgrade … v1.37.1+k3s1 True
…
NAME STATUS ROLES AGE VERSION
k3s Ready,SchedulingDisabled control-plane 3h25m v1.36.5+k3s1
Rancher hat zwei Pläne angelegt, einen für Server, einen für Agents. Der für Agents ist sofort fertig, weil k3s keinen Agent hat. Der Server-Node ist gesperrt; ein Job tauscht das Binary aus und startet k3s neu. Nach etwa fünf Minuten:
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get nodes
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get plans.upgrade.cattle.io -n cattle-system \
k3s-master-plan k3s-worker-plan
kubectl --kubeconfig "$LAB/kube/k3s.yaml" -n notes get pods
curl -s "http://notes.$K3S.sslip.io/api/notes"; echoErwartet (gekürzt):
NAME STATUS ROLES AGE VERSION
k3s Ready control-plane 3h25m v1.37.1+k3s1
NAME IMAGE … VERSION COMPLETE
k3s-master-plan rancher/k3s-upgrade … v1.37.1+k3s1 True
k3s-worker-plan rancher/k3s-upgrade … v1.37.1+k3s1 True
NAME READY STATUS RESTARTS AGE
api-84cc5bccd7-4csjb 1/1 Running 2 (58m ago) 58m
db-0 1/1 Running 0 58m
…
[{"id":"395a46da-…","text":"läuft auf k3s"}]
Die Pods von notes liefen durch, ohne Neustart: k3s startet seine Komponenten neu, die Container laufen in containerd weiter. Rancher meldet das Cluster für etwa eine halbe Minute als nicht bereit, solange der Agent die Verbindung neu aufbaut.
In Cluster Management steht k3s jetzt auf v1.37.1, werk und local auf v1.36.5:
Fortschritt speichern? Kostenlos registrieren
Drill 5: Wie werk geleert würde
Für werk legst du fest, wie ein künftiges Upgrade abläuft. Neu ist
der Abschnitt workerDrainOptions:
# tag12/cluster-werk.yaml (Ausschnitt) – Stand Ende Tag 12
upgradeStrategy:
controlPlaneConcurrency: "1"
workerConcurrency: "1"
workerDrainOptions: # neu an Tag 12: Worker vor dem Upgrade leeren
enabled: true
deleteEmptyDirData: true
ignoreDaemonSets: true
timeout: 300Ohne Drain tauscht Rancher RKE2 unter laufenden Pods aus. Mit Drain
räumt es jeden Worker vorher wie kubectl drain (Tag 10 und
„Kubernetes zum Anfassen”, Tag 14); die PodDisruptionBudgets aus dem
Chart werden dabei beachtet.
sed -i '' -e "s|RANCHER_IP|$RANCHER|" \
-e "s|CA_BUNDLE|$(base64 -i "$LAB/tag07/lab-ca.crt")|" cluster-werk.yaml
kubectl apply -f cluster-werk.yaml
kubectl -n fleet-default get machines.cluster.x-k8s.ioErwartet (gekürzt):
cluster.provisioning.cattle.io/werk configured
NAME CLUSTER NODE NAME … PHASE AGE
custom-431ed8f98314 werk werk1 … Running 2h
custom-44fc6b990590 werk werk3 … Running 2h
custom-8e74ab3310e6 werk werk2 … Running 2h
Die Maschinen bleiben, wie sie sind: Eine geänderte Upgrade-Strategie wirkt erst beim nächsten Upgrade, sie baut keinen Node neu.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get nodesErwartet: k3s auf v1.37.1, Ready, nicht gesperrt.
NAME STATUS ROLES AGE VERSION
k3s Ready control-plane 3h30m v1.37.1+k3s1
kubectl -n fleet-default get clusters.provisioning.cattle.io werk \
-o jsonpath='{.spec.rkeConfig.upgradeStrategy.workerDrainOptions.enabled}'; echoErwartet: true.
true
kubectl -n fleet-default get gitrepos.fleet.cattle.io notes \
-o jsonpath='{.status.display.readyBundleDeployments}'; echoErwartet: Fleet ist auch nach dem Upgrade zufrieden.
2/2
Challenge
Ein Kollege fragt, ob Rancher ihn wenigstens vor einem Downgrade von werk schützt. Finde es heraus, ohne werk zu beschädigen.
Hinweis: --dry-run=server schickt eine
Änderung durch alle Prüfungen des API-Servers und der Webhooks,
speichert sie aber nicht.
Lösung
kubectl -n fleet-default patch clusters.provisioning.cattle.io werk --type merge \
--dry-run=server -p '{"spec":{"kubernetesVersion":"v1.36.4+rke2r1"}}'
kubectl -n fleet-default get clusters.provisioning.cattle.io werk \
-o jsonpath='{.spec.kubernetesVersion}'; echoErwartet:
cluster.provisioning.cattle.io/werk patched
v1.36.5+rke2r1
Auch der Downgrade geht durch die Prüfung; gespeichert wurde nichts, werk steht weiter auf v1.36.5. Kubernetes selbst unterstützt keine Downgrades, ein echtes Zurück wäre ein etcd-Restore aus der Zeit vor dem Upgrade (Tag 13). Die Antwort für den Kollegen: Nein, Rancher schützt nicht. Das muss die Freigabe der Änderung leisten.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Reihenfolge: Erst Rancher auf eine Version heben, die die Ziel-Kubernetes-Version kennt, dann die Cluster. Zwischen Rancher-Minor-Versionen keine überspringen.
- Vorher sichern: Vor jedem Upgrade ein etcd-Snapshot (Tag 13) und ein Backup von Rancher selbst. Ein Upgrade lässt sich nicht rückgängig machen, nur wiederherstellen.
- Gestaffelt: Erst ein Test-Cluster, dann die
übrigen, per Label-Gruppen in Fleet oder mit
rolloutStrategy.controlPlaneConcurrencyundworkerConcurrencyauf 1 halten das Risiko pro Cluster klein. - Automatisch: Für viele k3s-Cluster am Rand
übernimmt der system-upgrade-controller mit eigenen Plans und Kanälen
(
channel: stable) die Upgrades ganz ohne Rancher. - Prime: Mit Rancher Prime gibt es verlängerte Supportzeiträume, wenn Cluster nicht im Takt der Kubernetes-Releases mitgehen können.