Build Daily

Tinley Park · November 2, 2026
platformSUSE (originally Rancher Labs)applied

Rancher

SUSE's open-source multi-cluster Kubernetes management plane. A Helm-installed control plane on a dedicated RKE2, K3s or hosted cluster manages any number of downstream clusters through an outbound-only agent tunnel, so managed clusters need no inbound access. Rancher roles are templates rendered into native Kubernetes RBAC on each cluster, projects are annotated namespace groups, every managed object is a CRD on the host, and Fleet pushes Git-defined baselines to clusters by label. Apache 2.0 and free; Rancher Prime is the paid build of the same code. Budget 4 vCPU / 16 GB for the host and a monthly patch cadence.

Updated October 17, 2026

Rancher is SUSE's open-source management server for Kubernetes clusters. It puts many clusters (on-prem, edge, EKS, AKS, GKE) behind one UI, one single sign-on login and one set of roles, so an operator does not keep a separate kubeconfig and permission setup for each cluster. This page covers what it is and when it fits; 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 has the same features; Prime adds support and supply-chain assurances.

SUSE ships Rancher alongside related projects that it installs or manages:

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

How it works

Rancher runs on one cluster and manages others. Two flows carry most of the traffic. The agent tunnel connects each downstream cluster to Rancher, and every proxied kubectl call and UI view travels over it. The sign-in flow turns an identity from an external provider (here OpenID Connect against Keycloak) into a Rancher user whose role bindings decide what that user can do on each cluster.

How Rancher reaches a cluster and signs a user in

Step 1 of 5. At start-up the agent dials out to the Rancher URL over 443 and keeps a WebSocket open. It checks the server CA against CATTLE_CA_CHECKSUM, so the cluster needs no inbound rule.

Two paths: the agent tunnel that carries kubectl traffic, and an OIDC sign-in against Keycloak.

Both flows end at the same place: role bindings stored as custom resources on the local cluster. The components, the tunnel and the RBAC model below give the detail.

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

Aspect 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

Rancher v2.15.2 manages all three K3s clusters behind builddaily.io, paiddaily.io and the other products. The clusters run as Lima VMs on one Mac: a management cluster, a beta cluster and a prod cluster.

  • Where it runs. Rancher runs as a single replica on the management cluster, which Rancher therefore shows as its local cluster. The beta and prod clusters are imported, so each one runs a cattle-cluster-agent that dials out to Rancher. K3s upgrades on all three are driven from Rancher through system-upgrade-controller.
  • Sign-in. Login goes through Keycloak over OIDC, and access is restricted to one user. The local admin account stays as a break-glass login; its password lives in OpenBao, not in the cluster or in Git.
  • Exposure. The public Rancher URL is published through a Cloudflare tunnel and gated by Cloudflare Access to one identity, so the Mac opens no inbound ports.
  • Settings chosen. Token hashing is on. The continuous-delivery feature (the Fleet UI and GitRepos) is off, because Argo CD already does all application GitOps; Fleet stays installed only to deliver Rancher's own agent bundles. The Harvester feature and the partner chart repository are off, because neither is used.
  • Backup. The Rancher Backup operator takes a nightly encrypted backup of Rancher's resources. A restore was drilled on a throwaway VM: Rancher's resources were back in 51 seconds, and Rancher installed on top came up with all users, auth settings and clusters in place.

Gotchas

  • Supported hosts are a short list. 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, the next deploy can fail to schedule.
  • 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.
  • Fleet v0.16 credential change. Rancher v2.15 ships Fleet v0.16, which no longer forwards Helm repository credentials to a chart repository unless the URL matches the GitRepo's helmRepoURLRegex. A pre-upgrade migration job fills the field on existing GitRepos; GitRepos created by hand without it fail to pull private charts. GitRepoRestriction is deprecated in favour of the new Policy resource.
  • Token hashing is one-way. Turning on the token-hashing feature stores only a SHA256 hash of each token, and the docs state it cannot be turned off again. Test it on a non-production install and take a backup first.
  • Backups on Kubernetes v1.36. The v2.15.0 release notes list a known issue where Rancher Backups does not show under Cluster Tools on v1.36 clusters. Installing the rancher-backup chart with Helm still works.
  • The Docker single-node install is for trials only. It is the fastest way to try Rancher, but SUSE documents it for development and testing only. Use it to evaluate, then move to a Helm install on a Kubernetes host.

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 is down, the clusters keep running, but the SSO login, proxied kubectl and UI stop. Keep break-glass kubeconfigs and a local admin account.
  • Credential concentration. Rancher holds admin-level access to every managed cluster. Its API tokens, its local admin password and its backup encryption key need the same protection as cluster-admin credentials.
  • Upgrade cadence. Several patch lines ship together roughly monthly. Falling behind turns into a multi-step upgrade dance between Rancher and Kubernetes versions.

Alternatives

Related