Rancher

An open-source multi-cluster Kubernetes management platform that provides a unified dashboard for deploying, managing, and monitoring clusters across any infrastructure.

Table of Contents#

1. Overview
2. Architecture
3. Installation
4. Post-Installation Setup
5. Cluster Management
6. RBAC and User Management
7. External Authentication
8. Application Deployment
9. Backup and Restore
10. Upgrading Rancher
11. Troubleshooting
12. See Also
13. Sources

1. Overview#

Rancher provides a management layer on top of Kubernetes clusters, unifying operations across on-premise, cloud, and edge environments. It handles cluster provisioning, user authentication, monitoring, alerting, and application cataloging from a single interface.

Key features:

• Multi-cluster management - manage any CNCF-conformant Kubernetes cluster from one dashboard
• Cluster provisioning - create clusters on bare metal (RKE2/K3s), cloud providers (EKS, AKS, GKE), or vSphere
• Application catalog - deploy Helm charts from the built-in catalog or custom repositories
• RBAC - fine-grained role-based access control integrated with external identity providers
• Monitoring - built-in Prometheus/Grafana stack deployment
• CIS scanning - Kubernetes security benchmark scanning
• Continuous delivery - integrated Fleet for GitOps at scale

2. Architecture#

Rancher itself runs on a "local" Kubernetes cluster (often called the management cluster) and manages "downstream" clusters. The downstream clusters do not require direct network access; agents initiate outbound connections to the Rancher server.

3. Installation#

3.1 Prerequisites#

• A Kubernetes cluster for the Rancher server (RKE2, K3s, or any conformant cluster)
• Helm 3
• kubectl configured for the management cluster
• A DNS name for Rancher (e.g., rancher.<domain>)
• TLS certificate (cert-manager, own certificate, or Let's Encrypt)

3.2 Install cert-manager (if using Rancher-generated or Let's Encrypt certs)#

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.crds.yaml

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.16.2

3.3 Add the Rancher Helm Repository#

Choose a release channel:

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update

3.4 Create the Namespace#

kubectl create namespace cattle-system

3.5 Install Rancher#

With Rancher-generated certificates (cert-manager):

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version 2.10.3 \
  --set hostname=rancher.<domain> \
  --set replicas=3 \
  --set bootstrapPassword=<initial-password>

With Let's Encrypt:

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version 2.10.3 \
  --set hostname=rancher.<domain> \
  --set replicas=3 \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=<your-email> \
  --set letsEncrypt.ingress.class=nginx \
  --set bootstrapPassword=<initial-password>

With your own certificate:

kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=<tls-cert-path> \
  --key=<tls-key-path>

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version 2.10.3 \
  --set hostname=rancher.<domain> \
  --set replicas=3 \
  --set ingress.tls.source=secret \
  --set privateCA=true \
  --set bootstrapPassword=<initial-password>

3.6 Verify Installation#

kubectl -n cattle-system rollout status deploy/rancher
kubectl -n cattle-system get pods

Wait until all pods are Running and the rollout is complete.

4. Post-Installation Setup#

4.1 First Login#

1. Navigate to https://rancher.<domain> in your browser
2. Enter the bootstrap password set during installation
3. Set a new admin password
4. Configure the Rancher server URL (should match the hostname)

4.2 Configure the Server URL#

If you need to change it later:

Global Settings > server-url > Edit > https://rancher.<domain>

4.3 Enable Monitoring#

Deploy the built-in Prometheus/Grafana monitoring stack:

Cluster > Apps > Charts > Monitoring > Install

Or via Helm:

helm install rancher-monitoring rancher-stable/rancher-monitoring \
  --namespace cattle-monitoring-system \
  --create-namespace

4.4 Enable Logging#

Cluster > Apps > Charts > Logging > Install

Supports Elasticsearch, Splunk, Fluentd, Kafka, and Syslog as outputs.

4.5 Enable CIS Benchmark Scanning#

Cluster > Apps > Charts > CIS Benchmark > Install

Runs the CIS Kubernetes Benchmark and generates compliance reports.

5. Cluster Management#

5.1 Import an Existing Cluster#

Cluster Management > Import Existing > Generic

Copy and run the provided kubectl apply command on the target cluster. The Rancher agent will connect back to the Rancher server.

5.2 Create a New Cluster (RKE2/K3s)#

Cluster Management > Create > Custom

1. Select Kubernetes version and CNI
2. Configure node roles (etcd, control plane, worker)
3. Copy the registration command and run it on each node

5.3 Create a Cloud-Hosted Cluster#

Cluster Management > Create > Amazon EKS / Azure AKS / Google GKE

Provide cloud credentials, select region, node size, and Kubernetes version.

5.4 Cluster Operations#

6. RBAC and User Management#

6.1 Role Types#

6.2 Built-in Global Roles#

6.3 Create Custom Roles#

Users & Authentication > Roles > Create

Custom roles can grant or deny specific API resources at the global, cluster, or project level.

6.4 Assign Roles to Users#

Cluster > Members > Add

Select the user and assign a cluster role. For project-level access:

Cluster > Projects/Namespaces > <Project> > Members > Add

6.5 Project and Namespace Isolation#

Projects group namespaces and apply shared RBAC, quotas, and network policies:

Cluster > Projects/Namespaces > Create Project

Configure:

• Resource quotas (CPU, memory, pod count)
• Default resource limits for containers
• Network isolation between projects

7. External Authentication#

7.1 LDAP / Active Directory#

Users & Authentication > Auth Provider > ActiveDirectory / OpenLDAP

Required fields:

7.2 SAML (Okta, ADFS, PingIdentity)#

Users & Authentication > Auth Provider > SAML

1. Create a SAML application in your IdP
2. Enter the Metadata XML URL or upload the metadata file
3. Map SAML attributes to Rancher fields (display name, username, groups)
4. Test login before saving

7.3 GitHub / GitLab#

Users & Authentication > Auth Provider > GitHub / GitLab

1. Create an OAuth application in GitHub/GitLab
2. Enter the Client ID and Client Secret
3. Optionally restrict to specific organizations or groups

7.4 OIDC (Keycloak, Azure AD, etc.)#

Users & Authentication > Auth Provider > OpenID Connect

Required fields:

8. Application Deployment#

8.1 Helm Chart Catalog#

Rancher includes built-in chart repositories (Rancher charts, partner charts) and supports adding custom repositories:

Cluster > Apps > Repositories > Create

Name: <repo-name>
Target: http(s)://<chart-repo-url>
# or Git: https://github.com/<org>/<repo>.git

8.2 Deploy from Catalog#

Cluster > Apps > Charts > Select Chart > Install

Configure values via the UI form or paste custom YAML values.

8.3 Fleet (GitOps)#

Fleet is Rancher's built-in GitOps engine for deploying workloads across clusters at scale:

Continuous Delivery > Git Repos > Add Repository

Name: <repo-name>
Repository URL: https://github.com/<org>/<repo>.git
Branch: main
Paths:
- /manifests
Target Clusters:
  Cluster Selector:
    matchLabels:
      env: production

Fleet automatically syncs the Git repository to all matching clusters.

9. Backup and Restore#

9.1 Install the Backup Operator#

Cluster (local) > Apps > Charts > Rancher Backups > Install

Or via Helm:

helm install rancher-backup rancher-stable/rancher-backup \
  --namespace cattle-resources-system \
  --create-namespace

9.2 Create a Backup#

apiVersion: resources.cattle.io/v1
kind: Backup
metadata:
  name: <backup-name>
spec:
  resourceSetName: rancher-resource-set
  storageLocation:
    s3:
      credentialSecretName: <s3-creds-secret>
      credentialSecretNamespace: <namespace>
      bucketName: <bucket>
      region: <region>
      endpoint: <s3-endpoint>
  schedule: "0 2 * * *"
  retentionCount: 10

For local storage (default PV):

apiVersion: resources.cattle.io/v1
kind: Backup
metadata:
  name: <backup-name>
spec:
  resourceSetName: rancher-resource-set

9.3 Restore from Backup#

apiVersion: resources.cattle.io/v1
kind: Restore
metadata:
  name: <restore-name>
spec:
  backupFilename: <backup-filename>
  storageLocation:
    s3:
      credentialSecretName: <s3-creds-secret>
      credentialSecretNamespace: <namespace>
      bucketName: <bucket>
      region: <region>
      endpoint: <s3-endpoint>

9.4 etcd Snapshots (Downstream Clusters)#

For RKE2/K3s downstream clusters, Rancher manages etcd snapshots:

Cluster > Snapshots > Take Snapshot

Snapshots are stored locally on the cluster nodes and optionally in S3.

To restore:

Cluster > Snapshots > Select Snapshot > Restore

10. Upgrading Rancher#

10.1 Pre-Upgrade Checklist#

1. Take a backup of the Rancher server (see section 9)
2. Take etcd snapshots of downstream clusters
3. Review the release notes for breaking changes
4. Verify Kubernetes version compatibility in the support matrix

10.2 Upgrade via Helm#

helm repo update

helm get values rancher -n cattle-system -o yaml > rancher-values.yaml

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version <new-version> \
  -f rancher-values.yaml

10.3 Verify Upgrade#

kubectl -n cattle-system rollout status deploy/rancher
kubectl -n cattle-system get pods

Check the Rancher UI footer for the new version number.

10.4 Rollback#

If the upgrade fails:

helm rollback rancher -n cattle-system

Or restore from the backup taken before the upgrade.

Troubleshooting#

See Also#

• A GitOps Kubernetes cluster, layer by layer
• Helm
• Portainer

Sources#

• Rancher Official Documentation
• Rancher GitHub Repository
• Rancher Installation Guide
• Rancher Backup and Restore
• Fleet Documentation