Andrew Mercer
on this page

4.1 Architecture

Rancher Manager is itself a Kubernetes application (Go, deployed via Helm) that runs on a local/upstream cluster (ideally a dedicated 3-node RKE2 or K3s cluster). It talks to downstream clusters via the cattle-cluster-agent, which dials out to Rancher over a websocket tunnel — so downstream clusters don't need inbound reachability.

Key internals:

Component Role
Rancher server pods (cattle-system) API, UI, controllers, auth proxy
cattle-cluster-agent (downstream) Tunnel back to Rancher; proxies kube API
cattle-node-agent (legacy/RKE1) Node-level operations
rancher-webhook Admission webhooks for Rancher CRDs
fleet-controller / fleet-agent GitOps
system-upgrade-controller Plan-based node upgrades
Provisioning v2 (provisioning.cattle.io) Cluster objects backed by CAPI machinery
rancher-turtles Cluster API (CAPI) providers integration

The authentication proxy is central: users authenticate to Rancher (local, LDAP/AD, SAML, OIDC, GitHub, Keycloak, Entra ID…), and Rancher impersonates them against downstream clusters, mapping Rancher global/cluster/project roles to Kubernetes RBAC.

4.2 Installing Rancher

# cert-manager first (unless bringing your own certs)
helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager \
  -n cert-manager --create-namespace --set crds.enabled=true

# Rancher
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
kubectl create namespace cattle-system
helm install rancher rancher-stable/rancher -n cattle-system \
  --set hostname=rancher.example.net \
  --set bootstrapPassword='change-me-now' \
  --set replicas=3 \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=[email protected] \
  --set letsEncrypt.ingress.class=nginx

TLS options (ingress.tls.source): rancher (self-signed via cert-manager), letsEncrypt, or secret (your own cert in tls-rancher-ingress, plus privateCA=true and tls-ca secret if internal CA).

Production guidance:

  • Run Rancher on its own cluster — don't host workloads there.
  • 3 nodes, external load balancer (L4) in front of the ingress.
  • Back it up with rancher-backup operator to S3.
  • Check the support matrix for the Kubernetes versions Rancher itself supports running on and managing.

4.3 Core concepts

Concept Meaning
Global scope Users, auth providers, cluster templates, global settings
Cluster A managed downstream cluster (provisioned, imported, or hosted)
Project A Rancher grouping of namespaces with shared RBAC, quotas, PSA config
Cluster/Project roles Role templates rendered into k8s RBAC downstream
Cloud credentials Stored secrets for providers (AWS, Azure, vSphere, Harvester)
Node drivers / machine configs How Rancher creates VMs for provisioned clusters
Apps (Helm) Catalog of charts, including Rancher's own (rancher-charts, partner-charts)
Extensions UI plugins (Harvester UI, Kubewarden, NeuVector, Elemental…)

4.4 Cluster types in Rancher

  1. Provisioned (node driver) — Rancher creates VMs via a driver (Harvester, vSphere, EC2, Azure, DigitalOcean, Linode…) and installs RKE2/K3s.
  2. Custom — you run a registration command on existing machines (bare metal, any VM).
  3. Hosted — Rancher creates and manages EKS/AKS/GKE through the respective operators (eks-operator, aks-operator, gke-operator).
  4. Imported — any conformant cluster; Rancher manages access, apps, and (for K3s/RKE2) can upgrade it.
  5. CAPI via Turtles — clusters created by Cluster API providers and auto-imported.

Rancher provisioning v2 represents every cluster as a clusters.provisioning.cattle.io object in fleet-default:

apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
  name: prod-apps
  namespace: fleet-default
spec:
  kubernetesVersion: v1.34.10+rke2r1
  rkeConfig:
    machinePools:
      - name: cp
        quantity: 3
        etcdRole: true
        controlPlaneRole: true
        machineConfigRef:
          kind: HarvesterConfig
          name: prod-apps-cp
      - name: workers
        quantity: 4
        workerRole: true
        machineConfigRef:
          kind: HarvesterConfig
          name: prod-apps-workers
    machineGlobalConfig:
      cni: cilium
    upgradeStrategy:
      controlPlaneConcurrency: "1"
      workerConcurrency: "1"

That's the object you'd put in Git to manage clusters declaratively.

4.5 Rancher apps worth knowing

  • rancher-monitoring — kube-prometheus-stack packaged with Rancher dashboards.
  • rancher-logging — Logging Operator (Fluent Bit + Fluentd/syslog-ng) with ClusterFlow/ClusterOutput CRDs.
  • rancher-backup — backup/restore of Rancher's own state.
  • rancher-cis-benchmark / compliance operator — kube-bench scans.
  • rancher-istio — deprecated over time; use upstream Istio or a mesh of choice.
  • rancher-gatekeeper — OPA Gatekeeper (Kubewarden is the SUSE-preferred path now).

← Kubernetes distributions: K3s and RKE2 · Index · Fleet: GitOps at scale →