homelab/docs/06-rancher.md

06 — Rancher

Datum: 2026-03-17 (aktualisiert: 2026-03-20) Version: Rancher v2.13.3 (Helm Chart 2.13.3) Namespace: cattle-system URL: https://rancher.192.168.11.180.nip.io URL (intern): https://rancher.int.elbpro.de

---

Übersicht

Rancher ist eine Kubernetes-Management-Plattform mit Web-UI. Es ermöglicht die zentrale Verwaltung von Kubernetes-Clustern, Workloads, Storage, Netzwerk und Benutzerrechten. In diesem Homelab läuft Rancher im k3s-Cluster selbst (single-cluster setup).

---

Voraussetzungen

• cert-manager v1.20.0 installiert und bereit (05-cert-manager.md)
• Traefik als Ingress Controller aktiv (04-traefik.md)
• Alle 3 Nodes Ready

---

Installation

1. Rancher Helm Repository hinzufügen

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update

Ausgabe:

"rancher-stable" has been added to your repositories
...Successfully got an update from the "rancher-stable" chart repository

2. Namespace erstellen

kubectl create namespace cattle-system

3. Rancher per Helm installieren

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version 2.13.3 \
  --set hostname=rancher.192.168.11.180.nip.io \
  --set ingress.tls.source=rancher \
  --set replicas=2 \
  --wait \
  --timeout 10m

Hinweis: Initial wurde hostname=rancher.192.168.11.170.nip.io (Control-Plane-IP) verwendet. Da Traefik nach MetalLB-Installation auf 192.168.11.180 gebunden ist, musste der Hostname auf .180.nip.io korrigiert werden (siehe Abschnitt "Hostname-Fix").

Wichtig — TLS-Quelle: ingress.tls.source=rancher verwendet Rancher's eigene self-signed CA (nicht Let's Encrypt). Siehe Abschnitt "TLS-Entscheidung" weiter unten.

---

TLS-Entscheidung: Rancher Self-Signed CA statt Let's Encrypt

Erster Versuch: Let's Encrypt

Initial wurde ingress.tls.source=letsEncrypt versucht. Dies schlug fehl:

Error: acme: authorization error for rancher.192.168.11.170.nip.io:
400 urn:ietf:params:acme:error:dns:
no valid A records found for rancher.192.168.11.170.nip.io

Grund: Let's Encrypt benötigt für die HTTP-01 Challenge öffentlichen Internetzugriff auf den Server. Die IP 192.168.11.170 ist eine private RFC1918-Adresse — Let's Encrypt's Validierungsserver können diesen Host nicht erreichen.

Lösung: Rancher Self-Signed CA

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version 2.13.3 \
  --set hostname=rancher.192.168.11.180.nip.io \
  --set ingress.tls.source=rancher \
  --set replicas=2

Rancher erstellt eine eigene CA (tls-rancher Secret) und stellt darüber das Ingress-Zertifikat via cert-manager aus (CA-Issuer rancher in cattle-system). Der Browser zeigt eine Zertifikatswarnung — für ein privates Homelab ist das akzeptabel.

Certificate-Fix

Nach dem Upgrade hatte cert-manager das alte fehlgeschlagene CertificateRequest im Backoff. Das Certificate-Objekt wurde manuell gelöscht, woraufhin Rancher's Controller es sofort neu erstellte:

kubectl delete certificate tls-rancher-ingress -n cattle-system
# → READY: True nach ~20 Sekunden

---

Pod-Status

kubectl get pods -n cattle-system

NAME                                        READY   STATUS      RESTARTS   AGE
rancher-6f98b4d565-94mff                    1/1     Running     0          ...   rnk-wrk02
rancher-6f98b4d565-q7jc4                    1/1     Running     0          ...   rnk-cp01
rancher-webhook-5dcf69b995-4q9sg            1/1     Running     0          ...   rnk-wrk02
system-upgrade-controller-65d9b4b8b-7wvrl   1/1     Running     0          ...   rnk-cp01
helm-operation-*                            0/2     Completed   0          ...   (abgeschlossene Jobs)

• rancher: 2 Replicas, verteilt auf rnk-wrk02 und rnk-cp01
• rancher-webhook: Validierungs-Webhook für Rancher-CRDs
• system-upgrade-controller: Verwaltet k3s-Node-Upgrades

---

Ingress & TLS

kubectl get ingress -n cattle-system
kubectl get certificate -n cattle-system

NAME      CLASS     HOSTS                           ADDRESS                                        PORTS
rancher   traefik   rancher.192.168.11.180.nip.io,rancher.int.elbpro.de   192.168.11.180   80, 443

NAME                  READY   SECRET
tls-rancher-ingress   True    tls-rancher-ingress

---

Helm Release Info

NAME     NAMESPACE      REVISION  STATUS    CHART           APP VERSION
rancher  cattle-system  2         deployed  rancher-2.13.3  v2.13.3

Revision 2: Upgrade von letsEncrypt → rancher TLS-Quelle. Revision 3: Hostname-Fix auf 192.168.11.180.nip.io + int.elbpro.de hinzugefügt.

---

Hostname-Fix (2026-03-20)

Problem

Rancher wurde initial mit hostname=rancher.192.168.11.170.nip.io installiert. nip.io löst .170 auf die Control-Plane-IP auf — dort läuft kein Traefik (Traefik ist nach MetalLB-Installation an 192.168.11.180 gebunden). Ergebnis: Verbindung abgelehnt beim Aufruf der URL.

Diagnose

curl -sk -o /dev/null -w "%{http_code}" https://rancher.192.168.11.170.nip.io
# → 000 (Verbindung abgelehnt)

curl -sk -o /dev/null -w "%{http_code}" https://rancher.192.168.11.180.nip.io
# → 404 (Traefik antwortet, aber kein Ingress-Match für diesen Host)

Fix: Helm Upgrade mit korrektem Hostname

helm upgrade rancher rancher-stable/rancher \
  --set hostname=rancher.192.168.11.180.nip.io \
  --set ingress.tls.source=rancher \
  --set replicas=2 \
  --reuse-values=false \
  --wait --timeout 5m

Nach dem Upgrade sofort erreichbar:

curl -sk -o /dev/null -w "%{http_code}" https://rancher.192.168.11.180.nip.io
# → 200

---

Interner Hostname: int.elbpro.de (2026-03-20)

Alle Homelab-Services wurden mit einem zweiten Ingress-Host (*.int.elbpro.de) versehen, damit saubere DNS-Namen ohne IP-Einbettung nutzbar sind.

Ingress patchen

kubectl patch ingress rancher -n cattle-system --type=json -p='[
  {"op":"add","path":"/spec/rules/-","value":{
    "host":"rancher.int.elbpro.de",
    "http":{"paths":[{"path":"/","pathType":"Prefix",
      "backend":{"service":{"name":"rancher","port":{"number":80}}}}]}
  }}
]'

DNS-Voraussetzung

# Pi-hole oder Omada: A-Record oder Wildcard
*.int.elbpro.de  →  192.168.11.180

Aktuelle Ingress-Konfiguration

kubectl get ingress rancher -n cattle-system
NAME      HOSTS
rancher   rancher.192.168.11.180.nip.io, rancher.int.elbpro.de
          ADDRESS: 192.168.11.180   PORTS: 80, 443

---

Erster Login

URLs

URL	Erreichbar
https://rancher.192.168.11.180.nip.io	immer (nip.io)
https://rancher.int.elbpro.de	wenn DNS gesetzt (siehe unten)

Browser zeigt Zertifikatswarnung (self-signed CA) → "Trotzdem fortfahren"

Bootstrap Password abrufen

kubectl get secret --namespace cattle-system bootstrap-secret \
  -o go-template='{{.data.bootstrapPassword|base64decode}}{{ "\n" }}'

Bootstrap Password (einmalig): vks6s469l7h5dtm25hh8vz6hzcpmkjx6jc87qdshm7c7ggq9n84q9m

Nach dem ersten Login wird ein neues Passwort gesetzt — das Bootstrap Password danach nicht mehr gültig.

Direkter Setup-Link

echo https://rancher.192.168.11.180.nip.io/dashboard/?setup=$(kubectl get secret \
  --namespace cattle-system bootstrap-secret \
  -o go-template='{{.data.bootstrapPassword|base64decode}}')

---

Nächste Schritte

• Ersten Login durchführen, Admin-Passwort setzen
• Hostname auf MetalLB-IP korrigiert
• int.elbpro.de Hostname hinzugefügt
• Cluster in Rancher registrieren / importieren
• Longhorn-Storage in Rancher-UI prüfen
• User und Rollen konfigurieren
• Rancher-eigenen Monitoring-Stack prüfen (optional)
• Wildcard-DNS *.int.elbpro.de → 192.168.11.180 in Pi-hole eintragen