Rancher Cheatsheet im Volltext

Management-Plane

Rancher Server: Multi-Cluster-Management, via Helm auf einem eigenen lokalen Cluster (RKE2/K3s) deployt. HA: 3 Replicas, zustandslos, State liegt im etcd des lokalen Clusters, nicht im Pod.

local: der Cluster, auf dem Rancher selbst läuft. Downstream: die verwalteten Cluster (imported/provisioned).

Expose (Helm-Values, seit 2.14): networkExposure.type: ingress, gateway oder none. gateway legt Gateway + HTTPRoute an (gateway.gatewayClass.name, Default traefik). ingress.includeDefaultExtraAnnotations ist abgekündigt und steht per Default auf false: wer ingress-nginx behält (upstream seit 03/2026 ohne Fixes), setzt die Timeouts für Shell und Logs (proxy-read/send-timeout 1800) selbst. RKE2 bringt ab 1.36 Traefik als Default-Ingress, ingress-nginx ist dort abgekündigt. Für gateway in RKE2 die Gateway API in rke2-traefik einschalten (HelmChartConfig, providers.kubernetesGateway.enabled: true).

Agents im Downstream

cattle-cluster-agent (Deployment, cattle-system): öffnet den Tunnel ausgehend zu Rancher (remotedialer/websocket). Rancher braucht keinen Inbound-Zugang zum Downstream, kubectl, Metrics, Health laufen durch diesen Tunnel zurück.

rancher-system-agent (systemd-Dienst auf jedem Node Rancher-provisionierter RKE2/K3s-Cluster): führt Plans aus, z. B. K8s-Upgrade, etcd-Snapshot und -Restore. cattle-node-agent gab es nur für RKE1 und fehlt seit 2.12.

API-Frameworks

Norman, legacy v3-API (management.cattle.io, /v3): Cluster, User, Project, RoleTemplate.

Steve, generischer K8s-Proxy (/v1), treibt Cluster Explorer/Dashboard, spricht jede CRD durch.

Ext-API (ext.cattle.io/v1, seit 2.12): eigener Extension-API-Server für Token und Kubeconfig, seit 2.13 auch SelfUser und PasswordChangeRequest. Deshalb braucht der local-Cluster den API Aggregation Layer.

Downstream-Zugriff wird über /k8s/clusters/<id> authentifiziert geproxyt.

Imported

Imported: bestehender Cluster, Registration-Manifest anwenden, cattle-cluster-agent übernimmt. Rancher verwaltet Zugriff/RBAC, aber keinen Node-Lifecycle. Ausnahme bei importierten RKE2/K3s: Ist die Version-Management-Option aktiv (Setting imported-cluster-version-management, Default true), installiert Rancher den system-upgrade-controller samt Plans und steuert K8s-Version und Upgrade-Strategie. Je Cluster: Global default, True oder False. Wer RKE2 außerhalb von Rancher upgradet, schaltet es für den Cluster ab.

Provisioned

Provisioned (Provisioning v2): Rancher erzeugt Nodes und Cluster über Cluster API (CAPI). CAPI-Controller kommen über Rancher Turtles (Chart rancher-turtles, Default seit 2.13, eingebettetes CAPI seit 2.14 entfernt). CRD provisioning.cattle.io/v1 Cluster, darunter rke.cattle.io (RKEControlPlane, ETCDSnapshot). RKE2/K3s als Distribution. RKE1 (Feld rancherKubernetesEngineConfig im v3-Cluster): EOL 07/2025, ab Rancher 2.12 entfernt.

Registrierung

Import: kubectl apply -f <registrationURL>. Custom-Nodes: Registrierungsbefehl aus der UI (system-agent-install.sh mit --server, --token und den Rollen-Flags --etcd, --controlplane, --worker) installiert rancher-system-agent.

Machine-Pools

machinePools: Node-Gruppen mit Rollen-Bools (controlPlaneRole/etcdRole/workerRole) + machineConfigRef je Infra-Provider (Amazon EC2, vSphere, Harvester, …).

apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata: {name: prod-eu, namespace: fleet-default}
spec:
  cloudCredentialSecretName: cattle-global-data:cc-harvester
  kubernetesVersion: v1.36.5+rke2r1
  rkeConfig:
    machinePools:
    - name: cp
      controlPlaneRole: true
      etcdRole: true
      quantity: 3
      machineConfigRef:
        kind: HarvesterConfig
        name: cp-medium
    - name: worker
      workerRole: true
      quantity: 4
      machineConfigRef:
        kind: HarvesterConfig
        name: worker-large

Rollen-Ebenen

Global: Rancher-weite Rechte (User anlegen, Cluster erstellen). Cluster: cluster-owner, cluster-member. Project: project-owner, project-member, read-only.

RoleTemplate (management.cattle.io) definiert die aggregierten Regelsätze, custom Rollen davon abgeleitet.

Auth-Provider

Local, Active Directory, LDAP (OpenLDAP/FreeIPA), SAML (Keycloak, Okta, ADFS, PingID, Shibboleth), OIDC (generisch, Keycloak, Amazon Cognito), GitHub (OAuth oder GitHub App), Google, Azure AD/Entra.

Gruppen-Mapping treibt die Rollen-Zuweisung. Ab 2.15 blendet das Feature-Flag hide-local-auth-provider (Default aus), wenn aktiviert, den lokalen Login aus, sobald ein externer Provider aktiv ist.

Mapping auf Kubernetes-RBAC

Rancher-Rollen sind CRDs im local-Cluster (GlobalRole, RoleTemplate, Bindings CRTB/PRTB), kein natives RBAC im Downstream. Der Management-Controller projiziert sie dort als ClusterRole/ClusterRoleBinding/RoleBinding. Zugriff läuft über den Proxy als impersonate-User; native K8s-RBAC greift zusätzlich. Gruppen aus dem Auth-Provider → Rancher-Rolle → K8s-Binding.

Token & Härtung (Defaults 2.15)

Session: auth-user-session-ttl-minutes 960 (16 h), Idle-Timeout auth-user-session-idle-ttl-minutes ebenfalls 960.

Token: Obergrenze auth-token-max-ttl-minutes 129600 (90 d), Kubeconfig-Token kubeconfig-default-token-ttl-minutes 43200 (30 d).

Audit-Log: Helm auditLog.enabled (Default false), auditLog.level 0 bis 3.

Fleet-Workspaces: Standard User dürfen sie ab Werk anlegen, bis zu den Patches vom 29.10.2026 der Einstieg für CVE-2026-94290 (kritisch, cluster-admin auf local). Wer das nicht will, setzt statt Standard User eine Kopie davon ohne create auf fleetworkspaces als newUserDefault und bindet Bestandsnutzer um.

Project-Abstraktion

Ein Project bündelt Namespaces (Rancher-Konstrukt, im Management-Cluster gespeichert, nicht im Downstream-API). Namespace-Zuordnung via Annotation field.cattle.io/projectId. RBAC und Quotas hängen am Project, nicht am einzelnen Namespace.

Resource-Quotas & PSA

Project-Quota: Gesamtbudget, das Rancher auf die Namespaces verteilt (Project-Limit + Namespace-Default).

Pod Security Admission: Rancher liefert PSA Configuration Templates (Ersatz für die entfernten PSP-Templates), clusterweit oder pro Namespace via pod-security.kubernetes.io/*-Labels.

Fleet-Modell

Continuous Delivery über viele Cluster, mit Rancher gebündelt (Fleet 0.16, cattle-fleet-system). Manager auf local, Agents im Downstream, auch einer auf local (Agent in cattle-fleet-local-system, Cluster-Objekt local in fleet-local).

GitRepo (fleet.cattle.io) → rendert Bundles → BundleDeployment je Ziel-Cluster. Targeting per clusterSelector/clusterGroup.

HelmOp (seit 2.12 per Default aktiv) rollt Helm-Charts direkt aus einem Helm-/OCI-Repo aus, ohne Git, mit SemVer-Constraint und Polling.

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata: {name: platform, namespace: fleet-default}
spec:
  repo: https://git.example.com/platform
  branch: main
  paths: [infra/, apps/]
  targets:
  - name: prod
    clusterSelector:
      matchLabels: {env: prod}

Targeting-Regeln

Labels auf dem Fleet-Cluster-Objekt treiben die Auswahl. Ohne targets greift clusterGroup: default. Ab Werk legt Fleet diese Gruppe nur in fleet-local an (enthält local). In fleet-default rollt ohne eigene Gruppe default nichts aus. fleet.yaml im Repo steuert Overlays, Helm-Values und dependsOn zwischen Bundles.

Multi-Tenancy: GitRepoRestriction ist abgekündigt, Ersatz ist Policy (fleet.cattle.io). Git-Webhooks immer mit webhookSecret: Fleet kündigt das Ende unauthentifizierter Webhook-Aufrufe an, seit 2.15.2 (CVE-2026-93539) wirken Spec-Änderungen per Webhook nur noch mit Secret.

Seit 2.15.3 (Fleet 0.16.3): Ein Cluster, der ein kubeconfig-Secret aus einem anderen Namespace nutzt, braucht am Secret das Label fleet.cattle.io/kubeconfig-referenceable-from=<Cluster-Namespace> (für seine eigenen Secrets setzt Rancher es selbst; Fix der kritischen CVE-2026-94290). Agent-initiiert registrierte Cluster bleiben an ihr Fleet-Registration-Token gebunden, ein Wechsel braucht die Annotation fleet.cattle.io/registered-token mit dem neuen Token-Namen (Fix von CVE-2026-104615).

Monitoring (ab 2.15 entkoppelt)

Neuinstallation: rancher-monitoring-dashboards liefert nur Dashboards und UI-Integration, Prometheus, Alertmanager und Grafana bringt ihr selbst mit (z. B. kube-prometheus-stack). Voraussetzung: rancher-monitoring deinstallieren.

Bestand: rancher-monitoring (kube-prometheus-stack 80.9.1, cattle-monitoring-system) läuft weiter, ist im 2.15-Katalog aber ausgeblendet.

rancher-logging & Alerting

Logging (Logging Operator 4.10 von kube-logging, vormals Banzai Cloud: Fluent Bit + Fluentd), CRDs ClusterFlow/ClusterOutput/Flow/Output (logging.banzaicloud.io), Namespace cattle-logging-system.

Alerting: Alertmanager + PrometheusRule. Slack, PagerDuty und Teams (msteamsv2_configs) sind native Receiver. rancher-alerting-drivers (Teams via prom2teams, SMS via Sachet) hat keine Chart-Version für 2.15.

rancher-backup Operator

Sichert den Rancher-Server-State (Management-CRDs, User, Cluster, Rollen), nicht Downstream-Workloads. CRDs Backup/Restore (resources.cattle.io), Ziel S3 oder PVC. Kernszenario: DR/Migration des Rancher-Servers.

ResourceSets rancher-resource-set-basic (ohne Secrets) und -full (mit Secrets, Verschlüsselung per encryptionConfigSecretName dringend empfohlen).

apiVersion: resources.cattle.io/v1
kind: Backup
metadata: {name: rancher-nightly}
spec:
  resourceSetName: rancher-resource-set-full
  encryptionConfigSecretName: backup-encryption
  schedule: "0 2 * * *"
  retentionCount: 7
  storageLocation:
    s3:
      bucketName: rancher-backups
      endpoint: s3.eu-central-1.amazonaws.com
      credentialSecretName: s3-creds
      credentialSecretNamespace: cattle-resources-system

etcd-Snapshots (Downstream)

Getrennt vom rancher-backup: RKE2/K3s sichern ihr eigenes etcd. rkeConfig.etcd.snapshotScheduleCron + snapshotRetention (lokal). S3 unter etcd.s3 mit cloudCredentialName (ns:name) und seit 2.14 eigener retention, die ohne eigene Angabe snapshotRetention erbt.

Restore: UI oder rkeConfig.etcdSnapshotRestore (name, generation hochzählen, restoreRKEConfig none, kubernetesVersion oder all). Snapshot sofort: etcdSnapshotCreate.generation hochzählen. RKE2 ohne Rancher: rke2 server --cluster-reset --cluster-reset-restore-path.

cattle-cluster-agent (Fehlerquelle #1)

Cluster Unavailable? Fast immer der Agent-Tunnel: server-url falsch/nicht erreichbar, CA-Mismatch (Agent braucht Ranchers CA), Proxy/DNS, abgelaufenes Token.

Importierte Cluster: seit 2.15 rotiert Rancher per Default das Cluster-Registration-Token (Flag crt-token-ttl-rotation, TTL 30 d, Gnadenfrist crt-default-grace-period-minutes 180). Rotiert es während einer Trennung, die länger als die Gnadenfrist dauert: 400 cluster not found, Registrierungsbefehl erneut anwenden; vor geplanten Ausfällen Gnadenfrist erhöhen.

agent-tls-mode: strict (Default bei Neuinstallation seit 2.9) vertraut nur der CA im Setting cacerts, system-store (Wert nach Upgrade von älteren Versionen) jeder CA im System-Trust-Store. Gilt für cluster-, fleet- und system-agent. Vor dem Wechsel auf strict je Cluster die Condition AgentTlsStrictCheck prüfen.

kubectl -n cattle-system logs -l app=cattle-cluster-agent
kubectl -n cattle-system get deploy cattle-cluster-agent
# auf local: Server-URL
kubectl get settings.management.cattle.io server-url \
  -o jsonpath='{.value}'
# im Downstream: Ziel des Agents
kubectl -n cattle-system get deploy cattle-cluster-agent \
  -o jsonpath='{..env[?(@.name=="CATTLE_SERVER")].value}'

Stuck-States & Zerts

Updating/Unavailable: Agent-Disconnect, Cert-Expiry oder etcd/controlplane not ready, describe cluster, Agent-Logs.

Cert-Rotation: RKE2/K3s über rke2 certificate rotate bzw. k3s certificate rotate (Dienst stoppen, rotieren, starten) oder UI „Rotate Certificates“. Interne Zerts 365 d gültig, auto-Rotation beim Start innerhalb 120 d vor Ablauf, ab 120 d Event CertificateExpirationWarning. Deklarativ: rkeConfig.rotateCertificates.generation hochzählen, optional services. CA: rke2 certificate rotate-ca.

kubectl: Kubeconfig aus der UI proxyt über Rancher (/k8s/clusters/<id>), authentifiziert per Rancher-Token. Für Zugriff bei ausgefallenem Rancher: Authorized Cluster Endpoint (spec.localClusterAuthEndpoint.enabled), DaemonSet kube-api-auth als Auth-Webhook am API-Server, zusätzlicher Kontext in der Kubeconfig. Nur RKE2/K3s, nicht EKS/AKS/GKE.

Highlights (30.07.2026)

Cluster API ist GA: native CAPI-Infrastruktur-Provider im Provisioning v2 (v2prov) sind von Tech Preview auf GA gehoben, CAPI selbst auf v1.13.

Mit installiertem CAPA-Provider spiegelt Rancher die AWS-Cloud-Credentials und legt ein AWSClusterStaticIdentity im Namespace fleet-default an.

Standard User und Create Clusters dürfen CAPI-Infra-Objekte in fleet-default anlegen und ändern.

Bootstrap-cloud-config wird bei nativen CAPI-Providern im Jinja-Format erzeugt.

inheritedNamespacedRules in GlobalRoles: Regeln je namentlich genanntem Namespace, aktiv in jedem Downstream-Cluster (nicht local, keine Wildcards, greift auch in später angelegten Namespaces). Vor 2.15.3 ohne Prüfung auf Rechteausweitung (CVE-2026-88810): bestehende GlobalRoles mit diesem Feld durchsehen.

Versions-Fenster

2.15 nimmt Kubernetes 1.36 auf und lässt 1.33 fallen: vor dem Rancher-Upgrade prüfen, ob alle Downstream-Cluster in der neuen Matrix liegen. Stand v2.15.3 (29.10.2026): RKE2/K3s v1.36.5 (Default), v1.35.9, v1.34.12. Für 1.37 gibt es noch keine 2.15-Freigabe.

Upgrade-Voraussetzungen (seit 2.12): API Aggregation Layer im local-Cluster aktiv, Helm-Client ab 3.18.

Chart-Retention: das Rancher-Repo stellt auf die sieben jüngsten Minors um (rund 2,5 Jahre). Wer ältere Charts pinnt, spiegelt sie selbst.

Was du nicht tun solltest

Rancher-Server + Prod-Workloads im selben Cluster: der local-Cluster ist Management-Plane, kein Workload-Cluster, Blast-Radius und Upgrade-Kopplung.

Keine etcd-Backups: rancher-backup sichert nur den Server, nicht die Downstream-Cluster, beide brauchen einen Plan.

Version-Skew: Rancher-Version zu Downstream-K8s außerhalb der Support-Matrix koppelt Upgrades hart.

Self-signed Certs ohne Rotation: Agent-Tunnel bricht bei Ablauf, Cluster geht Unavailable.

Cluster-Zugriff nur über UI: kein GitOps, Drift. Fleet/GitRepo als Source of Truth.