Installation Guide

Learn how to install Rancher in production environments with Docker, Helm, and Kubernetes

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

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

Kubernetes Installation

• kubectl CLI tool
• Helm 3.2+
• Kubernetes cluster (v1.23+)

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.

1. 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
   
2. 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.

3. Choose SSL/TLS Configuration

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

   Rancher-Generated Certificates

   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
   

   Let's Encrypt

   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
   

   Bring Your Own Certificate

   Use your own TLS certificates from a trusted CA.

   Requires: Creating a Kubernetes secret with your certificate

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

5. Install Rancher with Helm

   Rancher-Generated Certificates

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

   Replace rancher.my.org with your actual hostname.

   Let's Encrypt

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

   Replace:

   • rancher.my.org with your hostname
   • [e-mail] with your email

   Your Own Certificates

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

7. 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 letsEncrypt.email=[e-mail] \
  --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

1. Kubernetes Cluster: 3+ nodes for control plane
2. Rancher Replicas: 3+ pods across different nodes
3. Load Balancer: Layer 4 or 7 load balancer for ingress
4. Persistent Storage: For etcd and Rancher data
5. 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

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

2. Configure Authentication

   Set up external authentication providers:

   • Active Directory / LDAP
   • Azure AD
   • GitHub
   • Google OAuth
   • Okta
   • Keycloak

   See Authentication for details.

3. Set Up Backup

   Configure regular backups of:

   • Rancher data (etcd)
   • Kubernetes cluster state
   • Application data

   See Backup & Restore for procedures.

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

Additional Resources

• Official Installation Documentation
• Best Practices
• Support Matrix
• Rancher Forums