OMNI52
Rancher Cheatsheet OMNI52™ GmbH
Neu in Rancher 2.15Native CAPI-Infrastruktur-Provider · Kubernetes-Fenster verschiebt sich auf 1.34 bis 1.36 · API Aggregation Layer wird PflichtAlle Neuerungen →

Rancher
auf einem Blatt.

Dichte Referenz für Senior Platform Engineers und SREs. Architektur, Cluster-Management, Auth & RBAC, Projects, Fleet-GitOps, Observability, Backup/Restore, Diagnose und Anti-Patterns. Keine Einsteiger-Folien.

Vorschau (2 Seiten A4 quer + Brand-Rückseite)

Rancher Cheatsheet Seite 1: Architektur, Cluster-Management, Auth & RBAC, Projects, Fleet, Observability
Rancher Cheatsheet Seite 2: Backup, Ops & Diagnose, Neu in 2.15, Anti-Patterns

PDF herunterladen

Direkter Download, keine Mail-Adresse nötig. CC BY-SA 4.0: kopieren, drucken, weiterverteilen ist ausdrücklich erlaubt, solange die Quellenangabe sichtbar bleibt.

Rancher Cheatsheet (PDF, ~100 KB)

Was drin steht

Architektur

Rancher Server als Management-Plane, cattle-cluster-agent + rancher-system-agent, Steve/Norman-API, local vs. Downstream.

Cluster-Management

Imported vs. Provisioned, Provisioning v2 über Cluster API, RKE2/K3s, Machine-Pools, Registration-Command.

Auth & RBAC

Global/Cluster/Project-Rollen, Auth-Provider (AD/LDAP/SAML/OIDC), Mapping der Rancher-Rollen auf Kubernetes-RBAC.

Projects & Fleet

Project-Abstraktion über Namespaces, Resource-Quotas, Pod Security Admission. Fleet-GitOps mit GitRepo, Bundles, Targeting.

Observability & Backup

Monitoring ab 2.15 entkoppelt (rancher-monitoring-dashboards, Prometheus-Stack selbst betrieben), rancher-logging, Alerting. rancher-backup-Operator + etcd-Snapshots der Downstream-Cluster.

Diagnose

kubectl über Rancher-Proxy, cattle-cluster-agent-Konnektivität (Fehlerquelle #1), Stuck-States, Zertifikats-Rotation, Anti-Patterns.

Cheatsheet im Volltext

Derselbe Inhalt wie im PDF, zum Mitlesen, Durchsuchen und direkten Kopieren der YAML-Snippets. Stand: Rancher 2.15 (Edition 2026.10).

Architektur

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 (ingress-nginx-Retirement 03/2026) und steht per Default auf false: die nginx-Timeouts für Shell und Logs (proxy-read/send-timeout 1800) selbst setzen.

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. Downstream-Zugriff wird über /k8s/clusters/<id> authentifiziert geproxyt.

Cluster-Management

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 hebt die K8s-Version. Wer RKE2 außerhalb von Rancher upgradet, schaltet das je Cluster ab.

Provisioned

Provisioned (Provisioning v2): Rancher erzeugt Nodes und Cluster über Cluster API (CAPI). CAPI-Controller kommen seit 2.14 über Rancher Turtles (Chart rancher-turtles). CRD provisioning.cattle.io/v1 Cluster. RKE2/K3s als Distribution. RKE1 (rke.cattle.io): 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.4+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

Auth & RBAC

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.

Projects & Namespaces

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 (GitOps)

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.

Observability

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.

Backup & Restore

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 über Rancher-UI oder rke2 server --cluster-reset --cluster-reset-restore-path.

Ops & Diagnose

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.

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.

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.

Neu in 2.15

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, nur wo der Namespace existiert).

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.2 (23.09.2026): RKE2/K3s v1.36.4 (Default), v1.35.8, v1.34.11. Für 1.37 gibt es noch keine 2.15-Freigabe.

Upgrade-Voraussetzungen: 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.

Anti-Patterns

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.

Verwandte Cheatsheets

Ebenfalls von OMNI52:
kubernetes-cheatsheet.de, Kubernetes Core
rke2-cheatsheet.de, RKE2-Distribution
flux-cheatsheet.de, GitOps/CD
service-mesh-cheatsheet.de, Service Mesh im Vergleich

Lizenz & Weiterverteilung

CC BY-SA 4.0. Du darfst dieses Cheatsheet kopieren, weiterverteilen, ausdrucken und in eigenen Materialien zitieren. Bedingung: Quellenangabe „Rancher Cheatsheet, OMNI52 GmbH, rancher-cheatsheet.de“ bleibt sichtbar, und abgeleitete Werke stehen unter der gleichen Lizenz (Share-Alike).

Nicht erlaubt: Logo, Marken oder den Eindruck zu vermitteln, dass der Inhalt von dir/euch stammt oder dass OMNI52 GmbH die Weiterverwendung sponsort.

Volltext der Lizenz: creativecommons.org/licenses/by-sa/4.0/deed.de.

Rancher is a trademark of SUSE LLC. OMNI52™ is a trademark of OMNI52 GmbH (filed, not yet registered). This website is operated by OMNI52 GmbH and is not affiliated with, endorsed by, or sponsored by SUSE LLC. „Rancher“ is used in a descriptive sense to indicate the technology this cheatsheet documents.