OMNI52
Rancher Cheatsheet OMNI52™ GmbH

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
Rancher Cheatsheet Seite 2: Observability, Backup, Ops & Diagnose, 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 + cattle-node-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

rancher-monitoring (kube-prometheus-stack), 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.x (Edition 2026.07).

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

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.

cattle-node-agent (DaemonSet): Node-Operationen, Upgrade-Handling auf importierten Clustern.

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 vs. Provisioned

Imported: bestehender Cluster, Registration-Manifest anwenden, cattle-cluster-agent übernimmt. Rancher verwaltet Zugriff/RBAC, aber keinen Node-Lifecycle.

Provisioned (Provisioning v2): Rancher erzeugt Nodes und Cluster über Cluster API (CAPI). CRD provisioning.cattle.io/v1 Cluster. RKE2/K3s als Distribution. RKE1 (rke.cattle.io): EOL 07/2025, ab Rancher 2.12 entfernt.

Machine-Pools & Registrierung

machinePools: Node-Gruppen mit Rolle (controlPlane/etcd/worker) + Machine-Config je Infra-Provider (Amazon EC2, vSphere, Harvester …).

Import: kubectl apply -f <registrationURL>. Custom-Nodes: docker run ... rancher/rancher-agent mit Node-Rollen-Flags.

apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata: {name: prod-eu, namespace: fleet-default}
spec:
  kubernetesVersion: v1.36.1+rke2r2
  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), GitHub, Google, Azure AD/Entra.

Ein Provider aktiv zur Zeit; Gruppen-Mapping treibt die Rollen-Zuweisung.

Mapping auf Kubernetes-RBAC

Rancher-Rollen sind keine K8s-Objekte — der Management-Controller projiziert sie als ClusterRoleBinding/RoleBinding in den Downstream. 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 (cattle-fleet-system). Manager auf local, Agents im Downstream.

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

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 das Default-Ziel (nur local). fleet.yaml im Repo steuert Overlays, Helm-Values und dependsOn zwischen Bundles.

Observability

rancher-monitoring

Auf Basis kube-prometheus-stack (Prometheus Operator, Prometheus, Alertmanager, Grafana, node-exporter), pro Cluster aus Apps/Charts installiert, Namespace cattle-monitoring-system. Dashboards + ServiceMonitor/PrometheusRule out-of-the-box.

rancher-logging & Alerting

Logging (Banzai Logging Operator: Fluent Bit + Fluentd), CRDs ClusterFlow/ClusterOutput/Flow/Output, Namespace cattle-logging-system.

Alerting: Alertmanager + PrometheusRule, Rancher-Alerting-Drivers für Teams/Slack/PagerDuty.

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.

apiVersion: resources.cattle.io/v1
kind: Backup
metadata: {name: rancher-nightly}
spec:
  resourceSetName: rancher-resource-set
  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. etcd.snapshotScheduleCron + snapshotRetention im Cluster-Spec, S3-Ziel optional. 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
# Registration/Server-URL pruefen:
kubectl -n cattle-system get settings.management.cattle.io \
  server-url -o jsonpath='{.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 (Node-Neustart) oder UI „Rotate Certificates“. Interne Zerts ~1 Jahr gültig, auto-Rotation beim Restart innerhalb 90 d vor Ablauf.

kubectl: Kubeconfig aus der UI proxyt über Rancher (/k8s/clusters/<id>), authentifiziert per Rancher-Token.

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.

Aus der OMNI52 Cheatsheet-Fabrik

Verwandte Sheets in dichter Senior-Qualität:
kubernetes-cheatsheet.de — Kubernetes Core
rke2-cheatsheet.de — RKE2-Distribution
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.