Zum Inhalt springen
Trainingslager IT-Trainingslager

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 in provisioning.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 -A

Erwartet (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.io

Erwartet (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-token löschen und mit spec.clusterName neu 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 T

Erwartet:

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-operation

Erwartet (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:

Cluster Management mit dem importierten k3s und dem local-Cluster

Die Spalte Provider unterscheidet Imported und Local. Explore öffnet ein Cluster. Erwartet: das Cluster Dashboard von k3s wie in der Abbildung.

Cluster Dashboard des importierten k3s

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:

Die drei Deployments von notes im importierten Cluster

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.io

Erwartet: 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 deploy

Erwartet: 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"; echo

Erwartet: 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"; echo

Erwartet (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.