Tag 4: Cluster importieren
Ziel: Den k3s-Cluster aus Tag 2 per YAML in Rancher anmelden, den Agent darin verstehen und notes in der Oberfläche von Rancher wiederfinden. · Dauer: ca. 45 min · Voraussetzung: Tag 3
Briefing
- Importieren heißt: Ein vorhandenes Cluster bleibt, wie es ist. Rancher verwaltet es, baut es aber nicht und rüstet es nicht von selbst um.
- Im Ziel-Cluster läuft danach der cattle-cluster-agent. Er baut von innen eine Verbindung zu Rancher auf (WebSocket über HTTPS). Rancher muss das Cluster also nicht erreichen können, nur umgekehrt.
- Angelegt wird ein
Cluster-Objekt inprovisioning.cattle.io. Rancher erzeugt dazu einen Registrierungstoken und ein Manifest für den Agent. - Der Token ist ein Geheimnis: Wer ihn hat, kann ein beliebiges Cluster unter diesem Namen anmelden.
VM k3s VM rancher
┌──────────────────────────────┐ ┌──────────────────────────────────┐
│ cattle-system: │ wss:// │ rancher (cattle-system) │
│ cattle-cluster-agent ───────┼──443──►│ Cluster k3s = c-m-… │
│ cattle-fleet-system: │ │ Fleet (Tag 8) │
│ fleet-agent ────────────────┼───────►│ │
│ notes (aus Tag 2) läuft weiter └──────────────────────────────────┘
└──────────────────────────────┘
Drill 1: Tagesstart
source ~/rancher-lab/setup/env.sh
mkdir -p "$LAB/tag04" && cd "$LAB/tag04"
cp "$LAB/code/tag04/"* .
export KUBECONFIG="$LAB/kube/rancher.yaml"
kubectl get clusters.provisioning.cattle.io -AErwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):
NAMESPACE NAME VERSION CLUSTER NAME AGE KUBECONFIG READY
fleet-local local local 1h local-kubeconfig true
kubectl spricht heute mit dem local-Cluster, also mit
Rancher. Für den k3s-Cluster gibst du die zweite kubeconfig jeweils
einzeln an.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Das Cluster-Objekt
# tag04/cluster-k3s.yaml – Stand Ende Tag 4: ein importiertes Cluster
apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
name: k3s
namespace: fleet-default
labels:
lab: rancher-lab
spec: {}Ein leeres spec heißt: importiert. Ein Cluster, das
Rancher selbst baut, bekommt an Tag 5 ein rkeConfig. Der
Namespace fleet-default ist der Ort für alle Cluster außer
local.
kubectl apply --dry-run=server -f cluster-k3s.yaml
kubectl apply -f cluster-k3s.yaml
kubectl -n fleet-default get clusters.provisioning.cattle.io k3s
ID=$(kubectl -n fleet-default get clusters.provisioning.cattle.io k3s \
-o jsonpath='{.status.clusterName}')
echo "$ID"
kubectl -n "$ID" get clusterregistrationtokens.management.cattle.ioErwartet (gekürzt):
cluster.provisioning.cattle.io/k3s created (server dry run)
cluster.provisioning.cattle.io/k3s created
NAME VERSION CLUSTER NAME AGE KUBECONFIG READY
k3s c-m-5pjkcmvg 10s
c-m-5pjkcmvg
NAME AGE
default-token 9s
Rancher vergibt eine interne ID der Form c-m-…. Unter
diesem Namen gibt es einen Namespace im local-Cluster; darin liegt der
Registrierungstoken default-token.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Token und Manifest
Der Token selbst steht nicht im Token-Objekt, sondern in einem Secret
daneben. Das Objekt enthält nur die Adresse des Manifests, mit dem
Platzhalter {token}:
kubectl -n "$ID" get clusterregistrationtokens.management.cattle.io default-token \
-o jsonpath='{.status.tokenSecretName}'; echo
kubectl -n "$ID" get clusterregistrationtokens.management.cattle.io default-token \
-o jsonpath='{.status.manifestUrl}' | grep -o '/v3/import/{token}_[^.]*'Erwartet (gekürzt):
crt-token-default-token
/v3/import/{token}_c-m-5pjkcmvg
Sicherheit: Gib den Token nie aus, auch nicht in Logs oder Tickets. Die folgenden Befehle setzen ihn nur in eine Variable ein und löschen sie gleich wieder. Ist er doch einmal sichtbar geworden: Objekt
default-tokenlöschen und mitspec.clusterNameneu anlegen. Rancher erzeugt dann einen neuen Token.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Den Agent einspielen
Das Manifest kommt von Rancher und wird im
k3s-Cluster angewendet. -k ist nötig, weil
der Mac der Rancher-CA nicht vertraut (Tag 3):
URL=$(kubectl -n "$ID" get clusterregistrationtokens.management.cattle.io \
default-token -o jsonpath='{.status.manifestUrl}')
T=$(kubectl -n "$ID" get secret crt-token-default-token \
-o jsonpath='{.data.token}' | base64 -d)
curl -sfk "${URL/\{token\}/$T}" | kubectl --kubeconfig "$LAB/kube/k3s.yaml" apply -f -
unset URL TErwartet:
clusterrole.rbac.authorization.k8s.io/proxy-clusterrole-kubeapiserver created
clusterrolebinding.rbac.authorization.k8s.io/proxy-role-binding-kubernetes-mas… created
namespace/cattle-system created
serviceaccount/cattle created
clusterrolebinding.rbac.authorization.k8s.io/cattle-admin-binding created
secret/cattle-credentials-d18a5e6a19 created
clusterrole.rbac.authorization.k8s.io/cattle-admin created
deployment.apps/cattle-cluster-agent created
service/cattle-cluster-agent created
${URL/\{token\}/$T} ersetzt den Platzhalter in der
Adresse durch den Token. Ohne Ersetzung antwortet Rancher mit
cluster not found or invalid token. Der Agent bekommt
cattle-admin, also volle Rechte im Cluster: Rancher
verwaltet es damit vollständig.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Das Cluster meldet sich
kubectl --kubeconfig "$LAB/kube/k3s.yaml" -n cattle-system \
rollout status deploy/cattle-cluster-agent --timeout=300s
kubectl -n fleet-default wait clusters.provisioning.cattle.io/k3s \
--for=jsonpath='{.status.ready}'=true --timeout=300s
kubectl -n fleet-default get clusters.provisioning.cattle.io
c='NAME:.metadata.name,DISPLAY:.spec.displayName,VERSION:.status.version.gitVersion'
c+=',PROVIDER:.status.provider'
kubectl get clusters.management.cattle.io -o custom-columns="$c"Erwartet (gekürzt):
deployment "cattle-cluster-agent" successfully rolled out
cluster.provisioning.cattle.io/k3s condition met
NAME VERSION CLUSTER NAME AGE KUBECONFIG READY
k3s c-m-5pjkcmvg 21m k3s-kubeconfig true
NAME DISPLAY VERSION PROVIDER
c-m-5pjkcmvg k3s v1.36.5+k3s1 k3s
local local v1.36.5+rke2r1 rke2
Nach etwa zwei Minuten ist k3s bereit. Rancher erkennt
die Distribution von allein. Ein paar Minuten später hat es im
k3s-Cluster weitere Helfer installiert:
kubectl --kubeconfig "$LAB/kube/k3s.yaml" get pods -A | grep -E 'NAMESPACE|cattle' \
| grep -v helm-operationErwartet (gekürzt):
NAMESPACE NAME READY STATUS
cattle-fleet-system fleet-agent-55c4598cb8-7tqvr 1/1 Running
cattle-system apply-system-agent-upgrader-on-k3s-with-… 0/1 Completed
cattle-system cattle-cluster-agent-ccfdbf89f-wcqn7 1/1 Running
cattle-system rancher-webhook-cbf65548f-ql56j 1/1 Running
cattle-system system-upgrade-controller-5dc7c44677-drsmr 1/1 Running
- fleet-agent: Über ihn rollst du an Tag 8 und 9 Anwendungen per GitOps aus.
- rancher-webhook: prüft Änderungen an Rancher-Objekten, jetzt auch in k3s.
- system-upgrade-controller: fährt Upgrades von k3s
(Tag 12). Der Job
apply-system-agent-upgrader-…hat damit gleich den System-Agent eingerichtet.
Fortschritt speichern? Kostenlos registrieren
Drill 6: k3s in der Oberfläche
In Cluster Management stehen jetzt zwei Cluster:
Die Spalte Provider unterscheidet
Imported und Local. Explore
öffnet ein Cluster. Erwartet: das Cluster Dashboard von k3s wie in der
Abbildung.
Oben stehen Kennzahlen, darunter die Auslastung und der Zustand der Komponenten: Etcd, Scheduler, Controller Manager, dazu die Agents Cattle und Fleet. Unter Workloads › Deployments findest du notes aus Tag 2:
Rancher hat an notes nichts geändert. Es zeigt nur, was ohnehin da
war. Ab hier kannst du im Cluster genauso über die Oberfläche arbeiten
wie mit kubectl.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kubectl -n fleet-default get clusters.provisioning.cattle.ioErwartet: k3s mit READY true und einer
kubeconfig k3s-kubeconfig.
NAME VERSION CLUSTER NAME AGE KUBECONFIG READY
k3s c-m-5pjkcmvg 25m k3s-kubeconfig true
kubectl --kubeconfig "$LAB/kube/k3s.yaml" -n cattle-system get deployErwartet: Agent, Webhook und Upgrade-Controller laufen, alle
1/1.
NAME READY UP-TO-DATE AVAILABLE AGE
cattle-cluster-agent 1/1 1 1 8m6s
rancher-webhook 1/1 1 1 2m56s
system-upgrade-controller 1/1 1 1 2m30s
curl -s "http://notes.$K3S.sslip.io/api/notes"; echoErwartet: notes läuft unverändert weiter, mit deiner Notiz aus Tag 2.
[{"id":"395a46da-…","text":"läuft auf k3s"}]
Challenge
Was sieht Rancher, wenn der Agent fehlt? Skaliere
cattle-cluster-agent im k3s-Cluster auf null, lies die
Bedingung Ready des Management-Clusters und hol den Agent
zurück.
Hinweis: Die Bedingung steht in
.status.conditions von
clusters.management.cattle.io.
Lösung
kubectl --kubeconfig "$LAB/kube/k3s.yaml" -n cattle-system \
scale deploy/cattle-cluster-agent --replicas=0
f='{range .status.conditions[?(@.type=="Ready")]}{.status} {.reason} {.message}{end}'
kubectl get clusters.management.cattle.io "$ID" -o jsonpath="$f"; echo
kubectl --kubeconfig "$LAB/kube/k3s.yaml" -n cattle-system \
scale deploy/cattle-cluster-agent --replicas=1
kubectl get clusters.management.cattle.io "$ID" -o jsonpath="$f"; echoErwartet (gekürzt, beim zweiten Mal eventuell erst nach einer halben
Minute True):
deployment.apps/cattle-cluster-agent scaled
False Disconnected Cluster agent is not connected
deployment.apps/cattle-cluster-agent scaled
True
Nach wenigen Sekunden ohne Verbindung steht das Cluster auf
Disconnected, in der Oberfläche als
Unavailable. notes läuft dabei ungestört weiter: Der
Agent ist nur Ranchers Draht ins Cluster, nicht Teil des Datenpfads.
Nach etwa 30 Sekunden ist die Verbindung wieder da.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Nur ausgehend: Weil der Agent die Verbindung aufbaut, lassen sich Cluster hinter Firewalls oder NAT importieren. Freigeben musst du nur HTTPS zu Rancher.
- Vertrauen: In Produktion stammt das
Rancher-Zertifikat aus einer CA, der die Cluster vertrauen. Dann
entfällt
-k, und der Agent prüft den Server. - Gehostete Cluster: EKS, AKS und GKE importiert Rancher genauso. Mit Zugangsdaten zur Cloud kann es sie auch selbst anlegen und aktualisieren.
- Token-Pflege: Registrierungstoken laufen nach etwa
30 Tagen ab. Nach einem Leck wird der Token neu erzeugt; der laufende
Agent nutzt eigene Zugangsdaten (
cattle-credentials-…) und ist davon nicht betroffen. - Abmelden: Löschst du ein importiertes Cluster in Rancher, versucht Rancher, die Agents zu entfernen. notes und alle anderen Workloads bleiben stehen.