Rancher

Rancher is the answer to "we have more Kubernetes clusters than people who understand them." It puts every cluster — on-prem, edge, EKS, AKS, GKE — behind one UI, one login and one permission model. This page is the orient-and-decide surface — the official docs at ranchermanager.docs.rancher.com and SUSE's support matrix own the exact versions, which move every few weeks.

What it is

A Kubernetes application (installed with Helm into the cattle-system namespace) that manages other Kubernetes clusters. The cluster it runs on is the local (or upstream) cluster; every cluster it manages is a downstream cluster. Each downstream cluster runs a small agent (cattle-cluster-agent) that dials back to the Rancher server, so Rancher never needs inbound access to the clusters it manages.

The current line is v2.15 (v2.15.2 shipped 2026-09-23, with v2.14, v2.13, v2.12 and v2.11 patch lines released the same day). License is Apache 2.0. Rancher Prime is SUSE's commercial edition built on the same source: signed images with SBOMs, longer support windows, and a support contract. The community build is fully featured — Prime is a support and supply-chain purchase, not a feature unlock.

Rancher is the center of a family, and the family is the real value:

• RKE2 — SUSE's hardened, CIS-leaning Kubernetes distro. The recommended Rancher host.
• K3s — a single-binary, lightweight Kubernetes for edge, homelab and small boxes.
• Fleet — GitOps at fleet scale, built into Rancher (shown as "Continuous Delivery" in the UI).
• Longhorn — distributed block storage. NeuVector — container security. Harvester — HCI/VM platform on Kubernetes.

Architecture

Components

Where	Namespace	Workload	Job
Local cluster	cattle-system	rancher (Deployment, 3 replicas by default)	API server, UI, auth, cluster controllers
Local cluster	cattle-system	rancher-webhook	Validating/mutating admission for Rancher CRDs (RBAC escalation checks, field defaults)
Local cluster	cattle-fleet-system	fleet-controller, gitjob	Watches Git, renders bundles, schedules them to clusters
Local cluster	cert-manager	cert-manager	Issues the ingress cert when ingress.tls.source=rancher or letsEncrypt
Downstream	cattle-system	cattle-cluster-agent	Outbound tunnel to Rancher; proxies Kubernetes API calls
Downstream	cattle-fleet-system	fleet-agent	Pulls assigned bundles and applies them locally

How the tunnel works

The downstream agent opens an outbound WebSocket over 443 to the Rancher server URL and keeps it open. Rancher multiplexes Kubernetes API traffic back down that connection (the remotedialer library). Consequences:

• Downstream clusters need egress to the Rancher URL only — no inbound firewall rule, no public API server. That's why clusters behind NAT, in plants or on customer premises can still be managed.
• The agent pins the server CA by checksum (CATTLE_CA_CHECKSUM). Change Rancher's certificate to a different CA and every agent disconnects until it is re-registered or the cacerts setting is fixed.
• If Rancher is down, workloads keep running, but UI, Rancher API and proxied kubectl stop. Authorized Cluster Endpoint (RKE2/K3s clusters) issues kubeconfigs that hit the downstream API server directly, with Rancher's auth webhook, as the break-glass path.

APIs

• Steve — /v1. The current API the dashboard uses: a thin, watch-capable view over Kubernetes resources, aggregated across clusters.
• Norman — /v3. The legacy management API (tokens, users, imports). Still live; most automation and the Terraform provider use it.
• Proxied Kubernetes — /k8s/clusters/<cluster-id>. A standard Kubernetes API endpoint for each managed cluster, authenticated with a Rancher API token. Kubeconfigs downloaded from the UI point here. The host cluster's ID is local.
• Everything Rancher manages is a CRD on the local cluster — clusters.management.cattle.io, clusters.provisioning.cattle.io (in fleet-default), projects.management.cattle.io, globalroles, roletemplates, and so on. kubectl get on the local cluster is the ground truth; the UI is a view of it.

The RBAC model

Rancher roles are templates rendered into native Kubernetes RBAC on each downstream cluster:

Rancher object	Scope	Renders as
GlobalRole + GlobalRoleBinding	Whole Rancher install	Rancher permissions (create clusters, manage users) and optionally ClusterRoles on every cluster
RoleTemplate (context cluster) + ClusterRoleTemplateBinding	One cluster	ClusterRole + ClusterRoleBinding on that cluster
RoleTemplate (context project) + ProjectRoleTemplateBinding	One project	Role + RoleBinding in every namespace of the project

A project is a namespace label, not a new object on the downstream cluster: namespaces carry the annotation field.cattle.io/projectId: <cluster-id>:<project-id>, and Rancher fans the project's bindings, quotas and (optionally) NetworkPolicies out to each one. SSO identities (OIDC, SAML, AD/LDAP, GitHub) map to principals, so a group in the identity provider binds once and lands on every cluster.

When to use it

Reach for it when:

• You run more than one cluster and want one place to see and operate them all.
• You need centralized access control — one SSO login (OIDC, SAML, AD, GitHub) mapped to per-cluster and per-project roles, instead of a pile of kubeconfigs.
• You provision clusters often — Rancher creates RKE2/K3s clusters on VMs, bare metal or cloud nodes, and manages their upgrades, etcd snapshots and key rotation from the UI.
• You want monitoring, logging, backup and policy installed the same way on every cluster, as Rancher apps.
• You have edge or many-small-cluster sites. Fleet's pull model is designed for thousands of clusters, not a handful.

Skip it when:

• You have one cluster. Most of Rancher's value is multiplied by cluster count; with one, you pay the overhead and get a dashboard.
• You're already on Argo CD for app delivery and happy with it. Fleet overlaps it; running both means two GitOps systems to reason about.
• Your cluster isn't a supported Rancher host (see Gotchas) and you don't want to stand up a second cluster just to run the manager.
• All you want is a UI over kubectl — Headlamp or k9s give you that for a fraction of the footprint.

At a glance

Core concepts

• Local cluster — where Rancher itself runs. Should run nothing else important.
• Downstream cluster — a cluster Rancher manages: provisioned (Rancher built it, full lifecycle control), hosted (EKS/AKS/GKE driven through the cloud API) or imported (any existing cluster, registered by running one kubectl apply).
• Project — Rancher's grouping of namespaces inside a cluster. Roles, quotas and network isolation attach to projects, not single namespaces.
• Global / cluster / project roles — the three RBAC tiers, mapped onto native Kubernetes RBAC.
• Fleet GitRepo and bundles — the GitOps unit: a repo path rendered (raw YAML, Helm or Kustomize) into bundles and targeted at clusters by label.
• Cluster tools — Monitoring (Prometheus + Grafana), Logging, Backups, Istio, CIS scans, installed per cluster as apps.

Requirements (v2.15)

Item	Value
Supported Rancher hosts	RKE2, K3s, EKS, AKS, GKE, ACK — Kubernetes v1.34 to v1.36
Small install (≤150 clusters / 1,500 nodes)	4 vCPU, 16 GB RAM per node
HA production	3 nodes
Single-node Docker install	Dev/test only: 1–2 vCPU, 4–8 GB
Architectures	x86_64, arm64, mixed
New in 2.15	Host cluster must have the Kubernetes API aggregation layer enabled
Downstream (imported)	Any conformant Kubernetes

Fleet vs Argo CD

	Fleet	Argo CD
Model	Two-stage pull: controller pulls Git, agents pull from controller	Controller pulls Git, pushes to target clusters
Built for	Many clusters, edge	Rich app delivery
UI	Basic, inside Rancher	Resource graph, diffs, per-resource sync
Ordering	Bundle dependencies	Sync waves and hooks
RBAC / SSO	Through Rancher	Built in (Dex or OIDC)

A common split with many clusters: Fleet pushes cluster baseline config, Argo CD delivers applications.

How to integrate

Install on RKE2 or K3s (Helm)

# cert-manager (skip if you bring your own cert: ingress.tls.source=secret)
helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager --create-namespace --set crds.enabled=true

# Rancher from the stable channel
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm install rancher rancher-stable/rancher \
  --namespace cattle-system --create-namespace \
  --set hostname=rancher.example.com \
  --set bootstrapPassword="$(openssl rand -hex 16)"

kubectl -n cattle-system rollout status deploy/rancher

Useful chart values: replicas (set 1 on a single-node host), ingress.tls.source (rancher | letsEncrypt | secret), privateCA=true with a tls-ca secret for an internal CA, systemDefaultRegistry for air-gapped installs pulling from a private registry. Upgrade with helm upgrade rancher rancher-stable/rancher -n cattle-system --reuse-values --version <x.y.z>, one minor at a time.

For a throwaway trial, the single-container install is enough:

docker run -d --restart=unless-stopped --privileged \
  -p 80:80 -p 443:443 rancher/rancher:v2.15.2
docker logs <container> 2>&1 | grep "Bootstrap Password:"

Import an existing cluster

1. In Rancher: Cluster Management → Import Existing → Generic. Name it and set labels (env=prod, region=us-east) — Fleet targets on these.
2. Run the generated command against the target cluster with a cluster-admin kubeconfig: kubectl apply -f https://rancher.example.com/v3/import/<token>_<cluster-id>.yaml. If the Rancher cert is self-signed, use the curl --insecure … | kubectl apply -f - variant it also shows.
3. Watch kubectl -n cattle-system get pods on the target until cattle-cluster-agent is Ready; the cluster goes Active in the UI.
4. Generic imports get RBAC, projects, workload management, monitoring and logging. Version upgrades and etcd snapshot/restore are RKE2/K3s-only.

Fleet: one baseline, many clusters

A GitRepo on the local cluster points Fleet at a repo and picks target clusters by label. fleet-default holds downstream clusters; fleet-local holds the Rancher host itself.

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: cluster-baseline
  namespace: fleet-default
spec:
  repo: https://github.com/example/cluster-baseline
  branch: main
  paths:
    - monitoring
    - policies
  targets:
    - name: all-prod
      clusterSelector:
        matchLabels:
          env: prod

Each path holds a fleet.yaml that sets the namespace, the chart and per-cluster overrides:

defaultNamespace: monitoring
helm:
  repo: https://prometheus-community.github.io/helm-charts
  chart: kube-prometheus-stack
  version: <pinned-version>
  values:
    grafana:
      enabled: false
targetCustomizations:
  - name: edge
    clusterSelector:
      matchLabels:
        site: edge
    helm:
      values:
        prometheus:
          prometheusSpec:
            retention: 2d

Check rollout with kubectl -n fleet-default get gitrepo,bundles and kubectl -n fleet-default get bundledeployments -A on the local cluster. Bundle state Modified means someone edited the object by hand on the downstream cluster — Fleet reports drift and corrects it.

Back up Rancher itself

Install the Rancher Backups operator (rancher-backup chart) on the local cluster and schedule a Backup resource to S3-compatible storage with a retention count. It captures Rancher's CRDs and secrets, not workload data. A Restore from that backup onto a fresh cluster is also the supported way to migrate Rancher to a new host.

In the GL stack

builddaily.io

• Not in use. The GL products' backing services run on a single Kubernetes cluster delivered by Argo CD — the one-cluster case where Rancher adds overhead without adding control. The trigger to adopt is a second cluster: a separate prod cluster for a product, or a site that has to run on its own.

Gotchas

• The host matters more than the app. Rancher runs best on RKE2 or K3s. Docker Desktop, kind, minikube and plain kubeadm clusters are fine to import, not supported to host.
• Kubernetes version lag. Each Rancher minor supports a fixed Kubernetes window. Upgrade the cluster past that window and Rancher's upgrade path breaks — check the support matrix before every cluster upgrade.
• Pod and memory budget. Rancher, its webhook, Fleet, cert-manager and the CAPI/turtles controllers add pods to the host cluster. On a node near the 110-pod default, that's an outage waiting for a deploy.
• Uninstalling is not helm uninstall. Rancher leaves CRDs, webhooks and finalizers across the cluster. Use the official rancher-cleanup script, or plan to keep it.
• v2.15 Fleet RBAC change. Fleet now applies downstream RBAC to copied Secrets and ConfigMaps — bundles that pin a ServiceAccount without rights to create their namespace stop deploying until the rights are granted.
• The Docker single-node install is a trap for production. It's the fastest way to try Rancher and the hardest to grow out of. Use it to look, then throw it away.

Risks

• Single-vendor stewardship. SUSE owns the project and sets the roadmap. The code is Apache 2.0 and forkable, but the release cadence, chart repos and Prime split are SUSE's calls.
• Another control plane to keep alive. Rancher becomes the front door to every cluster. If it's down, the clusters keep running, but your login, RBAC and UI path don't — keep break-glass kubeconfigs.
• Upgrade cadence. Several patch lines ship together roughly monthly. Falling behind turns into a multi-step upgrade dance between Rancher and Kubernetes versions.

Related

• Postgres, Redis and Neo4j — three of the services the cluster runs. Rancher would manage the cluster under them, not the services.