Skip to main content
Rancher can be installed on any Kubernetes cluster using the official Helm chart. This is the recommended method for production environments, enabling high availability and integration with Kubernetes scheduling.

​
Prerequisites

Before installing Rancher, ensure your environment meets the following requirements:

​
Supported Kubernetes Distributions

For installations covered under Rancher Support SLA, the target cluster must be one of:
  • RKE1 - Rancher Kubernetes Engine 1
  • RKE2 - Rancher Kubernetes Engine 2
  • K3s - Lightweight Kubernetes
  • AKS - Azure Kubernetes Service
  • EKS - Amazon Elastic Kubernetes Service
  • GKE - Google Kubernetes Engine

​
Required Tools

  • kubectl - Kubernetes command-line tool
  • helm - Package management for Kubernetes (refer to Helm version requirements)

​
System Requirements

  • Operating system and container runtime requirements
  • Hardware requirements:
    • CPU and Memory
    • Ingress controller
    • Disk storage
  • Networking requirements:
    • Node IP addresses
    • Port requirements

​
Installation Steps

1
Add the Helm Chart Repository
2
Add the Rancher Helm chart repository using the appropriate channel for your use case:
3
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
4
Choose the repository based on your version requirements:
  • rancher-latest - Latest stable releases
  • rancher-stable - Stable releases with extended testing
  • rancher-alpha - Alpha/preview releases
5
Create the Namespace
6
Create the cattle-system namespace where Rancher resources will be installed:
7
kubectl create namespace cattle-system
8
Choose SSL Configuration
9
Rancher requires SSL/TLS configuration. Select one of three certificate options:
10
Option 1: Rancher-Generated Certificates (Default)
11
Rancher generates a self-signed certificate using cert-manager:
12
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org
13
Option 2: Let’s Encrypt
14
Use Let’s Encrypt for automatic certificate generation:
15
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=letsEncrypt \
  --set [email protected]
16
The production environment only allows registering a name 5 times per week. Use letsEncrypt.environment=staging for testing.
17
Option 3: Bring Your Own Certificate
18
Use certificates from files stored as Kubernetes secrets:
19
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret
20
For private CA certificates, add the --set privateCA=true flag:
21
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret \
  --set privateCA=true
22
Install cert-manager (if required)
23
Install cert-manager if using Rancher-generated certificates or Let’s Encrypt:
24
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
25
This step is only required when ingress.tls.source=rancher or ingress.tls.source=letsEncrypt.
26
Verify the Deployment
27
Check the rollout status of the Rancher deployment:
28
kubectl -n cattle-system rollout status deploy/rancher
29
Expected output:
30
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
deployment "rancher" successfully rolled out
31
Verify all replicas are available:
32
kubectl -n cattle-system get deploy rancher
33
Expected output:
34
NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rancher   3         3         3            3           3m
35
Access Rancher
36
Open a web browser and navigate to the hostname you configured (e.g., https://rancher.my.org). You should see the Rancher login page.

​
Common Configuration Options

​
Basic Options

ParameterDefaultDescription
hostname” “Fully Qualified Domain Name for your Rancher Server
ingress.tls.source”rancher”Certificate source: rancher, letsEncrypt, or secret
letsEncrypt.email” “Email address for Let’s Encrypt
letsEncrypt.environment”production”Let’s Encrypt environment: staging or production
privateCAfalseSet to true if using a private CA-signed certificate
replicas3Number of Rancher pod replicas
bootstrapPassword""Set a bootstrap password (random if empty)

​
Advanced Options

ParameterDefaultDescription
antiAffinity”preferred”AntiAffinity rule for Rancher pods: preferred or required
auditLog.enabledfalseEnable the Rancher audit logging system
auditLog.level0API audit log level (0-3, with 3 most verbose)
proxy” “HTTP[S] proxy server for Rancher
noProxy”127.0.0.0/8,…”Comma-separated list of addresses not to proxy
resourcesPod resource requests and limits
systemDefaultRegistry""Private registry for all system Docker images
useBundledSystemChartfalseUse system-charts packaged with Rancher (air-gapped)
ingress.ingressClassName” “Ingress class name if not using defaults

​
Example: Custom Resource Limits

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set replicas=3 \
  --set resources.requests.cpu=1000m \
  --set resources.requests.memory=2Gi \
  --set resources.limits.cpu=2000m \
  --set resources.limits.memory=4Gi

​
Example: Air-Gapped Installation

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

​
Saving Installation Options

Make sure you save the --set options you used during installation. You will need to use the same options when upgrading Rancher to new versions with Helm.

​
Troubleshooting

If deployment exceeds the progress deadline: 
kubectl -n cattle-system get pods
kubectl -n cattle-system logs -l app=rancher
For additional troubleshooting guidance, refer to the Rancher Troubleshooting documentation.

​
Gateway API Configuration

Rancher supports the Gateway API as an alternative to traditional Ingress controllers. This is useful for environments that use Gateway API for routing. 
networkExposure:
  type: gateway  # Options: ingress, gateway
  gateway:
    gatewayClass: istio  # Gateway class to use
    gatewayName: rancher-gateway  # Name of the gateway
    listenerName: https  # Listener name on the gateway
To install Rancher with Gateway API: 
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set networkExposure.type=gateway \
  --set networkExposure.gateway.gatewayClass=istio
Gateway API support requires the Gateway API CRDs to be installed in your cluster and a compatible Gateway controller (e.g., Istio, Envoy Gateway).

​
Resource Requirements

For production deployments, it’s recommended to set resource requests and limits to ensure stable performance: 
resources:
  requests:
    memory: "2Gi"
    cpu: "1"
  limits:
    memory: "4Gi"
    cpu: "2"
Example installation with resource requirements: 
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set resources.requests.memory=2Gi \
  --set resources.requests.cpu=1 \
  --set resources.limits.memory=4Gi \
  --set resources.limits.cpu=2
Adjust these values based on your cluster size and workload. Larger clusters with many downstream clusters may require more resources.

​
Host Network Mode

In some scenarios, Rancher needs to run with host networking enabled. This is particularly common in EKS clusters using non-VPC CNI plugins like Calico. 
hostNetwork: true
Example installation with host network: 
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set hostNetwork=true
Security Implications:
  • Pods will use the host’s network namespace
  • Ports will be exposed directly on the host
  • Bypasses NetworkPolicy controls
  • Should only be used when absolutely necessary (e.g., EKS with Calico CNI)

​
Next Steps

  • Configure high availability for production deployments
  • Set up authentication providers
  • Configure backup and disaster recovery
  • Review best practices for running Rancher in production

Build docs developers (and LLMs) love

Get started for freeTalk to us