SUSE Rancher Production Guide

Rancher is an open-source multi-cluster Kubernetes management platform that provides a single pane of glass for deploying, managing, and securing Kubernetes clusters anywhere — on-premises, in the cloud, or at the edge. Originally created by Rancher Labs, the project was acquired by SUSE in December 2020, and is now developed and commercially supported under the SUSE umbrella as Rancher Prime.

The core problem Rancher solves is Kubernetes sprawl. As organizations adopt Kubernetes, they inevitably end up with multiple clusters — dev, staging, production, edge locations, different cloud providers. Managing each cluster independently becomes unsustainable. Rancher centralizes cluster lifecycle management, authentication, policy enforcement, monitoring, and application deployment across all of them from a single UI and API.

What problems does Rancher solve?

• Cluster proliferation — Manage tens or hundreds of clusters from one place instead of kubectl-switching between kubeconfigs
• Consistent RBAC — Enforce authentication and authorization policies across every cluster using a single identity provider
• Cluster provisioning — Spin up new RKE2 or K3s clusters on bare metal, VMs, or cloud providers with a few clicks
• GitOps at scale — Deploy workloads across clusters using Fleet, the built-in GitOps engine
• Unified observability — Centralized monitoring and logging across all clusters
• Edge computing — Manage thousands of lightweight K3s clusters at edge locations

Rancher follows a hub-and-spoke model. The Rancher server (the hub) runs on a dedicated Kubernetes cluster and manages one or more downstream clusters (the spokes). Communication between the Rancher server and downstream clusters is handled by the Rancher Agent, which runs on each managed cluster.

Core components

Communication flow

HA deployment

For production, Rancher should run on a 3-node RKE2 cluster dedicated solely to Rancher. This gives you:

• etcd quorum — 3 etcd members tolerate 1 node failure
• Rancher pod replicas — The Rancher Helm chart defaults to 3 replicas, spread across nodes via preferred anti-affinity rules (configurable to required via the antiAffinity Helm value)
• Load balancer — A Layer 4 load balancer (or DNS round-robin) in front of the 3 nodes distributes traffic to the Rancher ingress

# Install Rancher on a 3-node RKE2 cluster
# Open-source Rancher (use rancher-stable for production)
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
# For Rancher Prime, use the authenticated repo URL from SUSE Customer Center (SCC)
helm repo update

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --create-namespace \
  --set hostname=rancher.example.com \
  --set replicas=3 \
  --set bootstrapPassword="admin" \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=ops@example.com

Rancher provides two primary ways to bring clusters under management: importing existing clusters and provisioning new ones. Both result in a cluster that appears in the Rancher UI with full lifecycle management capabilities.

Importing existing clusters

Any CNCF-conformant Kubernetes cluster can be imported into Rancher. The process is straightforward:

1. In the Rancher UI, click Import Existing
2. Rancher generates a kubectl apply command containing a manifest that deploys the Rancher Agent
3. Run the command on the target cluster
4. The agent connects back to Rancher, and the cluster appears in the dashboard

Imported clusters retain their original provisioner — Rancher does not take over the cluster lifecycle (upgrades, node scaling). It only adds management capabilities (RBAC, monitoring, app deployment).

Provisioning new clusters

Cluster templates

Cluster templates allow platform teams to define standardized cluster configurations that developers can use for self-service provisioning. Templates enforce organizational policies such as:

• Kubernetes version constraints
• Required CNI plugin (Calico, Cilium, Canal)
• Node pool sizing and instance types
• Network and security policies
• Monitoring and logging stack enablement

Node drivers and machine drivers

Node drivers are plugins that allow Rancher to provision VMs on various infrastructure providers. Built-in drivers include AWS EC2, Azure, DigitalOcean, Harvester, and vSphere. Custom drivers can be added for other providers. Machine drivers use Rancher Machine (a maintained fork of the now-deprecated Docker Machine) under the hood to create VMs and prepare them for Kubernetes installation.

Rancher provides a centralized authentication and authorization layer that sits in front of all managed clusters. Instead of configuring RBAC independently on each cluster, you define roles and bindings once in Rancher and they are enforced everywhere.

Identity provider integration

Rancher supports multiple authentication backends:

• Keycloak / OIDC — The recommended approach for enterprise environments. Rancher acts as an OIDC client, delegating authentication to Keycloak (or any OIDC provider)
• SAML — Integration with ADFS, Okta, PingFederate, Shibboleth, and other SAML 2.0 providers
• LDAP / Active Directory — Direct LDAP bind for organizations that haven’t adopted OIDC/SAML
• GitHub / Google / Microsoft Entra ID (Azure AD) — OAuth-based authentication for development environments
• Local — Built-in user database for bootstrap and emergency access

Rancher’s role model

Rancher defines roles at three hierarchical scopes:

Mapping external groups to Rancher roles

When an external IdP is configured, you can map IdP groups directly to Rancher roles. For example:

• LDAP group cn=platform-admins → Global Restricted Admin
• LDAP group cn=team-alpha → Cluster Member on prod-cluster + Project Owner on alpha-project
• OIDC group claim devops → Cluster Owner on all dev clusters

Rancher provides an app marketplace that simplifies deploying Helm charts across managed clusters. This is the primary mechanism for installing both infrastructure components (monitoring, logging, ingress controllers) and user applications.

Helm chart repositories

Rancher uses standard Helm chart repositories as its catalog backend. There are three types:

• Built-in — Rancher ships with curated charts for monitoring, logging, Istio, OPA Gatekeeper, CIS benchmarks, and more
• Partner — Charts from SUSE partners available through the Rancher marketplace
• Custom — Add any Helm repository URL (public or private) to make its charts available in the Rancher UI

Deploying apps across clusters

From the Rancher UI, you can install a Helm chart on any managed cluster in a few clicks. Rancher proxies the Helm install through its API, so you don’t need direct kubectl access. For deploying the same app across multiple clusters, Rancher integrates with Fleet for GitOps-driven multi-cluster deployment.

Fleet for GitOps at scale

Fleet is Rancher’s built-in GitOps engine designed for managing deployments across large numbers of clusters. Instead of manually installing charts on each cluster, you define your desired state in a Git repository and Fleet ensures every targeted cluster converges to that state. See the next section for a deep dive.

Fleet is a GitOps engine built into Rancher that enables continuous delivery across a large number of clusters. It watches Git repositories for changes and automatically deploys workloads to targeted clusters. Fleet was designed from the ground up for the multi-cluster use case — it can scale to manage thousands of clusters, making it ideal for edge deployments.

Core concepts

Example: multi-cluster deployment

# fleet.yaml - placed in your Git repo
defaultNamespace: my-app
helm:
  releaseName: my-app
  chart: ./charts/my-app
  values:
    replicaCount: 3

targetCustomizations:
- name: staging
  clusterSelector:
    matchLabels:
      env: staging
  helm:
    values:
      replicaCount: 1

- name: production
  clusterSelector:
    matchLabels:
      env: production
  helm:
    values:
      replicaCount: 5
      resources:
        requests:
          memory: "512Mi"
          cpu: "500m"

# GitRepo resource - registered in the Rancher local cluster
apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: my-app
  namespace: fleet-default
spec:
  repo: https://github.com/org/my-app-deploy
  branch: main
  paths:
  - /
  targets:
  - clusterSelector:
      matchLabels:
        env: production
  - clusterSelector:
      matchLabels:
        env: staging

Rancher provides integrated monitoring and logging stacks that can be deployed to any managed cluster with a single click from the Rancher UI. These are based on well-established open-source projects and are packaged as Helm charts maintained by the Rancher team.

Monitoring stack

Rancher’s monitoring solution is based on the Prometheus Operator and includes:

• Prometheus — Metrics collection and storage with pre-configured scrape targets for Kubernetes components, nodes, and common workloads
• Grafana — Dashboards for cluster health, node resources, pod metrics, and workload performance. Rancher ships with curated dashboards out of the box
• Alertmanager — Alert routing and notification via email, Slack, PagerDuty, webhooks, and more
• Node Exporter & kube-state-metrics — Exporters for OS-level and Kubernetes object metrics

Per-cluster vs global dashboards

Monitoring is deployed per cluster — each managed cluster gets its own Prometheus and Grafana instance. This ensures metrics stay local and avoids cross-cluster data transfer. For a global view, you can:

• Use Thanos or Cortex to aggregate Prometheus metrics across clusters into a central query layer
• Configure remote_write on each cluster’s Prometheus to push metrics to a central TSDB
• Use the Rancher UI’s cluster switcher to navigate between per-cluster Grafana instances

Logging integration

Rancher’s logging integration is based on the Banzai Cloud Logging Operator. It deploys Fluent Bit as a DaemonSet on each node to collect and enrich logs with Kubernetes metadata, then forwards them to Fluentd (or syslog-ng) for filtering and routing. Supported outputs include:

• Elasticsearch / OpenSearch
• Splunk
• Amazon CloudWatch
• Azure Log Analytics
• Syslog
• Kafka
• Custom HTTP endpoints

Alerting

Rancher exposes Alertmanager configuration through the UI, allowing operators to define alert rules and notification channels without editing YAML directly. Pre-built alert rules cover common scenarios:

• Node not ready, high CPU/memory, disk pressure
• Pod crash loops, OOMKills, pending pods
• etcd health, API server latency, scheduler failures
• Certificate expiration warnings

The Rancher Backup Operator (rancher-backup) provides a Kubernetes-native way to back up and restore the Rancher server’s state. This is critical because losing the Rancher server means losing centralized management of all downstream clusters (though the clusters themselves continue to operate independently).

What gets backed up

• All Rancher Custom Resources (clusters, projects, users, roles, tokens, settings)
• Rancher-managed namespaces and their contents
• Catalog/app configurations
• Fleet GitRepo and Bundle resources

The backup operator does not back up downstream cluster workloads — those need their own backup strategy (e.g., Velero).

Backup configuration

apiVersion: resources.cattle.io/v1
kind: Backup
metadata:
  name: rancher-daily-backup
spec:
  resourceSetName: rancher-resource-set
  schedule: "0 2 * * *"           # Daily at 2 AM
  retentionCount: 10              # Keep last 10 backups
  storageLocation:
    s3:
      bucketName: rancher-backups
      region: us-east-1
      endpoint: s3.amazonaws.com
      credentialSecretName: s3-creds
      credentialSecretNamespace: cattle-system

Restoring Rancher

Restoration deploys a fresh Rancher installation on a new RKE2 cluster, installs the backup operator, and applies a Restore CR pointing to the backup location. The operator reconciles all Rancher CRDs and resources, reconnecting downstream clusters automatically (agents reconnect via the same URL).

apiVersion: resources.cattle.io/v1
kind: Restore
metadata:
  name: rancher-restore
spec:
  backupFilename: rancher-daily-backup-2026-03-18T02-00-00Z.tar.gz
  storageLocation:
    s3:
      bucketName: rancher-backups
      region: us-east-1
      endpoint: s3.amazonaws.com
      credentialSecretName: s3-creds
      credentialSecretNamespace: cattle-system

Migrating Rancher to a new cluster

The backup/restore process doubles as a migration strategy. To move Rancher to a new cluster:

1. Take a backup on the old Rancher server
2. Provision a new RKE2 cluster and install Rancher with the same hostname
3. Install the backup operator and apply the Restore CR
4. Update DNS to point the Rancher hostname to the new cluster’s load balancer
5. Downstream cluster agents will reconnect automatically

Upgrading a Rancher environment involves two independent concerns: upgrading the Rancher server itself and upgrading the downstream Kubernetes clusters it manages.

Upgrading Rancher server

Rancher server is deployed via Helm, so upgrades are a standard helm upgrade:

# 1. Back up Rancher before upgrading
kubectl apply -f rancher-backup.yaml

# 2. Update the Helm repo
helm repo update

# 3. Upgrade Rancher
helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.example.com \
  --set replicas=3 \
  --version 2.13.3

• Always take a backup before upgrading (use the Rancher Backup Operator)
• Read the release notes — Rancher publishes detailed upgrade notes with known issues and breaking changes
• Upgrade sequentially — Rancher recommends upgrading through each consecutive minor version. Skipping minor versions is not supported and increases the risk of issues due to accumulated changes
• Upgrade the underlying RKE2 cluster if needed — check the Rancher support matrix for compatible Kubernetes versions

Upgrading downstream clusters

For Rancher-provisioned clusters (RKE2, K3s), upgrades are initiated from the Rancher UI or API:

• Select the target Kubernetes version from the available list
• Rancher orchestrates a rolling upgrade of control plane nodes first, then workers
• For RKE2, the upgrade uses the System Upgrade Controller (SUC) to coordinate node-by-node upgrades
• Configure drain settings (max unavailable, drain timeout) to control upgrade speed vs availability

For hosted clusters (EKS/AKS/GKE), Rancher calls the cloud provider’s API to trigger the managed upgrade process.

Upgrade strategy

Rancher has a straightforward licensing model that separates the free open-source project from the commercial offering.

Rancher (Open Source)

The core Rancher project is 100% open source under the Apache 2.0 license. You can download, deploy, and use Rancher in production without any license key or subscription. All core features — multi-cluster management, RBAC, Fleet, monitoring integration, app catalog — are available for free.

Rancher Prime (SUSE Commercial)

Rancher Prime is SUSE’s commercially supported distribution of Rancher. As of 2025, it is priced per CPU core / vCPU (charged per pair of physical cores or per four vCPUs), replacing the previous per-node model. What you get with Rancher Prime:

• Enterprise support — 24/7 support with SLAs from SUSE’s Kubernetes experts
• Hardened images — SUSE-built, FIPS 140-2 validated container images with BoringCrypto
• Extended lifecycle — Longer support windows for Rancher and RKE2 versions
• Security patches — Priority access to CVE fixes and security advisories
• SUSE Registry — Access to SUSE’s private container registry with verified images
• UI extensions — Additional UI capabilities for enterprise governance
• Integrations — Certified integrations with SUSE Linux Enterprise, NeuVector, and Longhorn

Use this checklist when planning, deploying, or auditing a Rancher environment.