Installation Guide

Installation Overview

Rancher can be installed in multiple ways depending on your requirements. This guide covers production-ready installation methods with proper SSL/TLS configuration and high availability.

For a quick development setup, see the Quick Start Guide.

Installation Methods

Single-Node Docker

Quick setup for development, testing, or small deployments on a single Linux host.

Helm on Kubernetes

Production-grade installation on existing Kubernetes clusters with high availability.

RKE2/K3s Cluster

Deploy Rancher on Rancher’s own Kubernetes distributions for optimal integration.

Hosted Kubernetes

Install on managed Kubernetes services like AKS, EKS, or GKE.

System Requirements

Operating Systems

Refer to the Support Matrix for specific OS versions supported by each Rancher version.

Supported operating systems include:

Ubuntu 20.04+ (64-bit)
RHEL/CentOS 7.9+ (64-bit)
SLES 15+ (64-bit)
Oracle Linux 7.9+ (64-bit)

Hardware Requirements

For Development/Testing (Single-Node)

Resource	Minimum	Recommended
CPU	2 cores	4 cores
RAM	4 GB	8 GB
Disk	50 GB	100 GB

For Production (High Availability)

Resource	Per Node	Nodes Required
CPU	4 cores	3+
RAM	8 GB	3+
Disk	100 GB	3+

Networking Requirements

Required Ports

Port	Protocol	Direction	Purpose
80	TCP	Inbound	HTTP (redirect to HTTPS)
443	TCP	Inbound	HTTPS / Rancher UI
6443	TCP	Inbound	Kubernetes API Server

Ensure your firewall rules allow traffic on these ports. Additional ports may be required for node-to-node communication in Kubernetes clusters.

Software Prerequisites

Docker Installation
Kubernetes Installation

Docker 20.10+ (Docker CE recommended)
Docker Compose (optional)

Method 1: Single-Node Docker Installation

Best for development, testing, or small production workloads.

Basic Installation

sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher

With Persistent Data

To persist Rancher data across container restarts:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -v /opt/rancher:/var/lib/rancher \
  rancher/rancher:stable

Using a Specific Version

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:v2.13.3

The stable tag always points to the latest stable release. For production, it’s recommended to pin to a specific version.

Method 2: Helm Installation on Kubernetes

Recommended for production environments requiring high availability.

Add the Helm Chart Repository

Add the Rancher Helm repository:

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

For stable releases, use:

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

Update the repository:

helm repo update

Create a Namespace

Create the cattle-system namespace where Rancher will be installed:

kubectl create namespace cattle-system

The namespace must be named cattle-system as this is where Rancher expects to run.

Choose SSL/TLS Configuration

Rancher requires SSL/TLS configuration. Choose one of three options:

Rancher-Generated Certificates
Let's Encrypt
Bring Your Own Certificate

Rancher will generate and manage its own self-signed certificates.Requires: cert-manager installed

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

Use Let’s Encrypt to automatically provision and renew certificates.Requires: cert-manager installed and publicly accessible hostname

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

Install cert-manager (if required)

If using Rancher-generated certificates or Let’s Encrypt:

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

Verify cert-manager is running:

kubectl get pods --namespace cert-manager

Wait until all pods show Running status.

Install Rancher with Helm

Rancher-Generated Certificates
Let's Encrypt
Your Own Certificates

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org

Replace rancher.my.org with your actual hostname.

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=letsEncrypt \
  --set [email protected]

Replace:

rancher.my.org with your hostname
[email protected] with your email

First, create a Kubernetes secret with your certificate:

kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

Then install Rancher:

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret

For private CA certificates, add --set privateCA=true:

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret \
  --set privateCA=true

Verify Installation

Check the rollout status:

kubectl -n cattle-system rollout status deploy/rancher

Expected output:

Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
deployment "rancher" successfully rolled out

Verify the deployment:

kubectl -n cattle-system get deploy rancher

Output should show:

NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rancher   3         3         3            3           3m

The DESIRED and AVAILABLE counts should match. If deployment times out, check pod status with kubectl -n cattle-system get pods.

Access Rancher

Navigate to the hostname you configured (e.g., https://rancher.my.org).You’ll be prompted to set the admin password on first login.

Advanced Helm Configuration Options

Common Options

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set replicas=3 \
  --set ingress.tls.source=letsEncrypt \
  --set [email protected] \
  --set letsEncrypt.environment=production

Key Configuration Parameters

Parameter	Default	Description
`hostname`	(required)	Fully Qualified Domain Name for Rancher Server
`replicas`	3	Number of Rancher pod replicas
`ingress.tls.source`	`rancher`	Certificate source: `rancher`, `letsEncrypt`, `secret`
`letsEncrypt.email`	`""`	Email for Let’s Encrypt notifications
`letsEncrypt.environment`	`production`	`staging` or `production`
`privateCA`	`false`	Set to `true` for private CA certificates
`bootstrapPassword`	(random)	Set initial bootstrap password
`antiAffinity`	`preferred`	Pod anti-affinity: `preferred` or `required`
`auditLog.enabled`	`false`	Enable audit logging

For a complete list of options, see the Helm Chart Options documentation.

Proxy Configuration

For environments requiring an HTTP proxy:

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set proxy="http://proxy.example.com:8080" \
  --set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local"

Air-Gapped Installation

For air-gapped environments:

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set rancherImage=registry.example.com/rancher/rancher \
  --set systemDefaultRegistry=registry.example.com \
  --set useBundledSystemChart=true

High Availability Considerations

For production deployments, always use a high-availability setup with at least 3 nodes.

Recommended HA Architecture

Kubernetes Cluster: 3+ nodes for control plane
Rancher Replicas: 3+ pods across different nodes
Load Balancer: Layer 4 or 7 load balancer for ingress
Persistent Storage: For etcd and Rancher data
Backup Strategy: Regular etcd and cluster backups

Supported Kubernetes Distributions

For production deployments, Rancher supports:

RKE2

Rancher’s security-focused Kubernetes distribution

K3s

Lightweight Kubernetes for edge and IoT

RKE1

Rancher Kubernetes Engine (legacy)

Hosted Kubernetes

AKS, EKS, GKE with specific version requirements

Post-Installation Steps

Save Your Configuration

Save the Helm values you used for installation:

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

You’ll need these values for future upgrades.

Configure Authentication

Set up external authentication providers:

Active Directory / LDAP
Azure AD
GitHub
Google OAuth
Okta
Keycloak

See Authentication for details.

Set Up Backup

Configure regular backups of:

Rancher data (etcd)
Kubernetes cluster state
Application data

See Backup & Restore for procedures.

Configure Monitoring

Enable monitoring and alerting:

Install Prometheus and Grafana
Configure alerts
Set up log aggregation

See Monitoring for setup.

Upgrading Rancher

To upgrade Rancher to a new version:

helm upgrade rancher rancher-latest/rancher \
  --namespace cattle-system \
  --reuse-values

Always review the release notes before upgrading and test upgrades in a non-production environment first.

Troubleshooting

Deployment exceeds progress deadline

Check pod status:

kubectl -n cattle-system get pods
kubectl -n cattle-system describe pod <pod-name>

Common causes:

Insufficient resources
Image pull failures
Network connectivity issues

cert-manager issues

Verify cert-manager is running:

kubectl get pods -n cert-manager

Check certificate status:

kubectl -n cattle-system get certificate
kubectl -n cattle-system describe certificate

Ingress not working

Verify ingress controller is installed:

kubectl get ingressclass
kubectl get ingress -n cattle-system

Check if hostname resolves correctly:

nslookup rancher.my.org

Can't access Rancher UI

Check all pods are running:

kubectl -n cattle-system get all

View Rancher logs:

kubectl -n cattle-system logs -l app=rancher

For more troubleshooting help, see the Rancher Troubleshooting Guide.

Next Steps

Provision Clusters

Create and manage Kubernetes clusters

Configure Authentication

Set up user authentication and authorization

High Availability Setup

Configure HA for production deployments

Backup & Restore

Set up backup procedures

Getting Started

Architecture

​Installation Overview

​Installation Methods

Single-Node Docker

Helm on Kubernetes

RKE2/K3s Cluster

Hosted Kubernetes

​System Requirements

​Operating Systems

​Hardware Requirements

​For Development/Testing (Single-Node)

​For Production (High Availability)

​Networking Requirements

​Required Ports

​Software Prerequisites

​Method 1: Single-Node Docker Installation

​Basic Installation

​With Persistent Data

​Using a Specific Version

​Method 2: Helm Installation on Kubernetes

​Advanced Helm Configuration Options

​Common Options

​Key Configuration Parameters

​Proxy Configuration

​Air-Gapped Installation

​High Availability Considerations

​Recommended HA Architecture

​Supported Kubernetes Distributions

RKE2

K3s

RKE1

Hosted Kubernetes

​Post-Installation Steps

​Upgrading Rancher

​Troubleshooting

​Next Steps

Provision Clusters

Configure Authentication

High Availability Setup

Backup & Restore

​Additional Resources

Build docs developers (and LLMs) love

Installation Overview

Installation Methods

System Requirements

Operating Systems

Hardware Requirements

For Development/Testing (Single-Node)

For Production (High Availability)

Networking Requirements

Required Ports

Software Prerequisites

Method 1: Single-Node Docker Installation

Basic Installation

With Persistent Data

Using a Specific Version

Method 2: Helm Installation on Kubernetes

Advanced Helm Configuration Options

Common Options

Key Configuration Parameters

Proxy Configuration

Air-Gapped Installation

High Availability Considerations

Recommended HA Architecture

Supported Kubernetes Distributions

Post-Installation Steps

Upgrading Rancher

Troubleshooting

Next Steps

Additional Resources