How to install Rancher on K3s
This guide installs Rancher Manager on an existing K3s cluster using Helm.
It covers:
- Single-node K3s for testing
- 3-node K3s HA cluster for production
- Helm installation
- cert-manager
- Rancher-generated certificates
- Let's Encrypt
- Bring-your-own TLS certificate
- Ingress
- DNS
- Rancher verification
- Upgrades
- Backup considerations
Rancher officially supports installation on Kubernetes using Helm. K3s already includes an ingress controller by default, so a separate ingress installation is normally not required. (Rancher Manager Documentation)
Architecture
A recommended production topology is:
Users
│
▼
https://rancher.example.com
│
▼
DNS / VIP
│
▼
K3s Ingress
Traefik
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
Rancher Pod Rancher Pod Rancher Pod
│ │ │
└───────────┼───────────┘
│
cattle-system
│
▼
K3s HA Cluster
┌────────┬────────┐
│ │ │
▼ ▼ ▼
k3s-01 k3s-02 k3s-03
etcd etcd etcd
For production, Rancher recommends installing Rancher on a Kubernetes cluster rather than using the single-container Docker installation. Rancher supports K3s as the underlying Kubernetes distribution. (Rancher Manager Documentation)
Prerequisites
You should already have a working K3s cluster.
Verify:
kubectl get nodes
Example HA cluster:
NAME STATUS ROLES AGE
k3s-01 Ready control-plane,etcd,master
k3s-02 Ready control-plane,etcd,master
k3s-03 Ready control-plane,etcd,master
Rancher must be installed on a Kubernetes version supported by the Rancher release you choose. (Rancher Manager Documentation)
If K3s is not yet installed, use:
Ingress Requirement
Rancher exposes its UI and API through Kubernetes Ingress.
K3s installs an ingress controller by default, so you normally do not need to install NGINX ingress separately. (Rancher Manager Documentation)
Check:
kubectl get pods -n kube-system
You should normally see Traefik-related resources.
Check ingress classes:
kubectl get ingressclass
Example:
NAME CONTROLLER
traefik traefik.io/ingress-controller
Install Helm
Rancher installation requires:
kubectl
Helm 3
Rancher's official installation documentation assumes Helm 3. (Rancher Manager Documentation)
Verify:
kubectl version --client
helm version
If Helm is not installed, install Helm 3 using your normal Helm installation method.
Then verify:
helm version
Configure Kubeconfig
K3s stores its administrator kubeconfig at:
/etc/rancher/k3s/k3s.yaml
If running Helm directly on a K3s server:
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Verify:
kubectl get nodes
For a normal user:
mkdir -p ~/.kube
sudo cp \
/etc/rancher/k3s/k3s.yaml \
~/.kube/config
sudo chown \
$USER:$USER \
~/.kube/config
chmod 600 ~/.kube/config
Then:
kubectl get nodes
DNS Requirement
Create a DNS record for Rancher.
Example:
rancher.example.com
│
▼
10.10.10.20
Where:
10.10.10.20
is the IP address that reaches your K3s ingress.
For a simple single-node setup:
rancher.example.com
│
▼
10.10.10.21
For HA:
rancher.example.com
│
▼
Load Balancer / VIP
│
├── k3s-01
├── k3s-02
└── k3s-03
Rancher's production installation expects the configured hostname to resolve to the Rancher ingress/load-balancer endpoint. (Rancher Manager Documentation)
Add Rancher Helm Repository
For production, use the stable repository:
helm repo add \
rancher-stable \
https://releases.rancher.com/server-charts/stable
Update:
helm repo update
Rancher documents the stable repository as the recommended repository for production, while latest is intended for trying newer features. (Rancher Manager Documentation)
Check available charts:
helm search repo rancher-stable/rancher
Create Rancher Namespace
Rancher must be installed into:
cattle-system
Create:
kubectl create namespace cattle-system
Rancher's official chart documentation specifies cattle-system as the Rancher namespace. (Rancher Manager Documentation)
Verify:
kubectl get namespace cattle-system
Choose TLS Method
Rancher requires TLS.
Three common options are:
1. Rancher-generated certificate
2. Let's Encrypt
3. Your own TLS certificate
Rancher-generated and Let's Encrypt certificates require cert-manager. Bring-your-own certificates do not. (Rancher Manager Documentation)
For most internal environments:
Rancher-generated certificate
is the simplest.
For public production environments:
Let's Encrypt
or an existing trusted certificate is usually preferable.
Option 1 — Rancher-Generated Certificate
This is the simplest installation.
Architecture:
Rancher
│
▼
cert-manager
│
▼
Rancher Internal CA
│
▼
TLS Certificate
Rancher's default ingress.tls.source is rancher, which uses cert-manager to issue and maintain the certificate. (Rancher Manager Documentation)
Install cert-manager
The current cert-manager documentation recommends its OCI Helm chart for modern installations. (cert-manager)
At the time of this guide, the current documented chart version is:
v1.21.1
Install:
helm install \
cert-manager \
oci://quay.io/jetstack/charts/cert-manager \
--version v1.21.1 \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
The current official cert-manager chart installs CRDs using:
--set crds.enabled=true
Verify cert-manager
kubectl get pods \
-n cert-manager
Expected components:
cert-manager
cert-manager-cainjector
cert-manager-webhook
All should reach:
Running
Rancher's installation documentation recommends verifying these pods before installing Rancher. (Rancher Manager Documentation)
You can also run:
kubectl wait \
--for=condition=Available \
deployment/cert-manager \
-n cert-manager \
--timeout=180s
Generate Bootstrap Password
Generate a strong initial Rancher administrator password:
openssl rand -base64 32
Example:
RANDOM_LONG_PASSWORD
Save it securely.
The Rancher Helm chart uses:
bootstrapPassword
for the initial admin user. (Rancher Manager Documentation)
Install Rancher
Example hostname:
rancher.example.com
Install:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
The release name should be:
rancher
and the namespace should be:
cattle-system
according to Rancher's official installation workflow. (Rancher Manager Documentation)
Rancher Replica Count
For an HA K3s cluster, use multiple Rancher replicas.
Example:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
This places multiple Rancher replicas across the cluster where scheduling allows.
For a single-node test environment:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=1 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
Rancher's quick-start uses one replica for proof-of-concept installs; production installations should use an HA architecture. (Rancher Manager Documentation)
Verify Rancher Deployment
Wait for the rollout:
kubectl -n cattle-system \
rollout status \
deploy/rancher
Rancher's official verification procedure uses this command. (Rancher Manager Documentation)
Expected:
deployment "rancher" successfully rolled out
Check pods:
kubectl get pods \
-n cattle-system
Example:
rancher-xxxxxxxx-xxxxx 1/1 Running
rancher-xxxxxxxx-xxxxx 1/1 Running
rancher-xxxxxxxx-xxxxx 1/1 Running
Check Deployment
kubectl get deployment \
rancher \
-n cattle-system
For three replicas:
NAME READY UP-TO-DATE AVAILABLE
rancher 3/3 3 3
Rancher's documentation recommends confirming that desired and available replica counts match. (Rancher Manager Documentation)
Check Rancher Ingress
kubectl get ingress \
-n cattle-system
Expected:
NAME HOSTS
rancher rancher.example.com
Detailed:
kubectl describe ingress \
rancher \
-n cattle-system
Check Rancher Service
kubectl get svc \
-n cattle-system
You should see:
rancher
The Rancher service itself is normally exposed through Kubernetes ingress rather than directly as a public NodePort.
Open Rancher
Open:
https://rancher.example.com
Login:
Username:
admin
Use the bootstrap password configured during installation.
After first login, Rancher guides you through the initial configuration.
Self-Signed Certificate Warning
With the default Rancher-generated certificate, browsers may report that the certificate is not publicly trusted.
This is expected because the certificate is issued by Rancher's own CA.
For internal deployments, you can distribute/trust the Rancher CA.
For a public deployment, use:
Let's Encrypt
or your own trusted certificate.
Option 2 — Let's Encrypt
For a publicly accessible Rancher installation:
rancher.example.com
must resolve publicly to the Rancher ingress/load balancer.
Let's Encrypt HTTP-01 validation also requires:
TCP 80
to be reachable. Rancher specifically documents this requirement for the Let's Encrypt option. (Rancher Manager Documentation)
Install Rancher:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD' \
--set ingress.tls.source=letsEncrypt \
--set [email protected] \
--set letsEncrypt.ingress.class=traefik
K3s normally uses Traefik, so:
letsEncrypt.ingress.class=traefik
is appropriate for the default K3s ingress.
Rancher's documented Let's Encrypt chart values include the hostname, email address, TLS source, and ingress class. (Rancher Manager Documentation)
Important agent-tls-mode
For newer Rancher installations, agent-tls-mode defaults to strict.
Rancher's current documentation notes that when strict agent TLS validation is used with Let's Encrypt, the appropriate CA trust configuration must also be supplied or downstream clusters may fail to connect. (Rancher Manager Documentation)
Verify the exact requirements for the Rancher version you are deploying before using this option in production.
Option 3 — Existing TLS Certificate
If you already have:
tls.crt
tls.key
you can use:
ingress.tls.source=secret
This does not require cert-manager. (Rancher Manager Documentation)
Create the TLS secret:
kubectl -n cattle-system \
create secret tls tls-rancher-ingress \
--cert=tls.crt \
--key=tls.key
Install Rancher:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD' \
--set ingress.tls.source=secret
The certificate hostname must match the Rancher hostname. (Rancher Manager Documentation)
Private CA Certificate
If the certificate is signed by your own private CA, additionally configure:
privateCA=true
Example:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD' \
--set ingress.tls.source=secret \
--set privateCA=true
Rancher's official chart documentation requires privateCA=true when Rancher uses a certificate signed by a private CA. (Rancher Manager Documentation)
Firewall
For Rancher access:
TCP 443
must reach the K3s ingress.
For Let's Encrypt HTTP-01:
TCP 80
must also be reachable from the Internet. (Rancher Manager Documentation)
Example UFW:
sudo ufw allow 443/tcp
If using Let's Encrypt:
sudo ufw allow 80/tcp
Your K3s cluster networking ports must also remain available as documented in the K3s installation wiki.
Recommended HA Network Layout
Internet / LAN
│
▼
rancher.example.com
│
▼
10.10.10.20 VIP
│
Load Balancer
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
k3s-01 k3s-02 k3s-03
10.10.10.21 10.10.10.22 10.10.10.23
│ │ │
└─────────────────┼─────────────────┘
│
K3s Traefik
│
▼
Rancher Pods
For HA environments, use a stable DNS name and load-balancer/VIP rather than pointing Rancher DNS at one control-plane node only.
Verify DNS
dig rancher.example.com
or:
nslookup rancher.example.com
Expected:
rancher.example.com → 10.10.10.20
Test HTTPS
curl -I \
https://rancher.example.com
With Rancher's default self-signed certificate during testing:
curl -kI \
https://rancher.example.com
Check Rancher Logs
List pods:
kubectl get pods \
-n cattle-system
Logs:
kubectl logs \
-n cattle-system \
deployment/rancher
Follow:
kubectl logs \
-n cattle-system \
deployment/rancher \
-f
Check cert-manager
kubectl get all \
-n cert-manager
Check certificates:
kubectl get certificates \
-A
Check issuers:
kubectl get issuers \
-A
Check ClusterIssuers:
kubectl get clusterissuers
Check Rancher Certificate
kubectl get secret \
-n cattle-system
For the default Rancher-generated TLS configuration, you should see Rancher-managed TLS secrets after the certificate is issued.
Check Ingress Events
kubectl describe ingress \
rancher \
-n cattle-system
This is useful when DNS works but Rancher is still inaccessible.
Resource Placement
For a three-node K3s server cluster:
k3s-01
k3s-02
k3s-03
Rancher replicas should ideally be distributed among nodes.
Check:
kubectl get pods \
-n cattle-system \
-o wide
Example:
rancher-xxx k3s-01
rancher-yyy k3s-02
rancher-zzz k3s-03
Rancher Manages Its Own K3s Cluster
After installation, Rancher displays the Kubernetes cluster on which Rancher itself runs as the:
local
cluster.
From there, Rancher can manage additional downstream clusters.
Architecture:
Rancher Local K3s Cluster
│
└── Rancher Server
│
├── Production K3s
├── Development K3s
├── RKE2
├── EKS
├── AKS
└── Other Kubernetes Clusters
Install a Specific Rancher Version
For production, consider explicitly pinning the version rather than always installing whatever currently exists in stable.
See available versions:
helm search repo \
rancher-stable/rancher \
--versions
Then:
helm install rancher \
rancher-stable/rancher \
--version <VERSION> \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
Rancher's installation documentation supports selecting a specific chart using the Helm --version option. (Rancher Manager Documentation)
Save Installation Options
Save the Helm values you used.
For example:
hostname: rancher.example.com
replicas: 3
ingress:
tls:
source: rancher
You can store this as:
rancher-values.yaml
Install:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--values rancher-values.yaml \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
Rancher explicitly recommends saving the values/options used during installation because you need the same options during future Helm upgrades. (Rancher Manager Documentation)
Check Installed Helm Release
helm list \
-n cattle-system
Example:
NAME NAMESPACE STATUS
rancher cattle-system deployed
Get values:
helm get values \
rancher \
-n cattle-system
All values:
helm get values \
rancher \
-n cattle-system \
--all
Upgrade Rancher
Before upgrading:
helm repo update
Check available versions:
helm search repo \
rancher-stable/rancher \
--versions
Review the Rancher release notes and supported upgrade path before upgrading.
Then use:
helm upgrade rancher \
rancher-stable/rancher \
--namespace cattle-system \
--version <NEW_VERSION> \
--values rancher-values.yaml
Rancher's current upgrade documentation uses Helm for Rancher installations that were originally installed with Helm. (Rancher Manager Documentation)
Verify After Upgrade
kubectl -n cattle-system \
rollout status \
deployment/rancher
Then:
kubectl get pods \
-n cattle-system
Check:
helm list \
-n cattle-system
Rancher Backup
For production environments, install Rancher's backup operator and regularly back up Rancher configuration.
Backups are important because Rancher stores information such as:
Cluster registrations
Users
Authentication configuration
Projects
Namespaces
RBAC
Catalog configuration
Fleet configuration
Rancher settings
The Rancher backup/restore process is the supported mechanism for migrating or restoring Rancher management state. Rancher's migration documentation uses the Rancher backup chart and restore resources. (Rancher Manager Documentation)
Also maintain K3s embedded-etcd snapshots for the local management cluster.
Recommended Backup Architecture
Rancher
│
Rancher Backup
│
▼
S3 / NAS Storage
K3s
│
etcd Snapshot
│
▼
S3 / NAS Storage
Use both layers for a resilient management-cluster recovery plan.
Troubleshooting — Rancher Pod Not Starting
Check:
kubectl get pods \
-n cattle-system
Describe:
kubectl describe pod \
-n cattle-system \
<RANCHER_POD>
Logs:
kubectl logs \
-n cattle-system \
<RANCHER_POD>
Rancher's troubleshooting documentation identifies cattle-system, traefik, and cert-manager as key namespaces to inspect. (Rancher Manager Documentation)
Troubleshooting — Certificate Not Ready
Check:
kubectl get pods \
-n cert-manager
Then:
kubectl get certificate \
-A
Describe:
kubectl describe certificate \
-n cattle-system \
<CERTIFICATE>
Check cert-manager logs:
kubectl logs \
-n cert-manager \
deployment/cert-manager
Troubleshooting — 404 from Traefik
Check Rancher ingress:
kubectl get ingress \
-n cattle-system
Then:
kubectl describe ingress \
rancher \
-n cattle-system
Check Traefik:
kubectl get pods \
-n kube-system |
grep traefik
Check service:
kubectl get svc \
-n kube-system |
grep traefik
Troubleshooting — DNS Works but UI Does Not Open
Check:
curl -vk \
https://rancher.example.com
Then verify:
DNS
Firewall
Port 443
K3s Traefik
Rancher ingress
Rancher pods
TLS certificate
Troubleshooting — Rancher Cannot Manage Downstream Clusters
Rancher agents running in downstream clusters must be able to reach:
https://rancher.example.com
If downstream clusters cannot reach Rancher's hostname, cluster registration and management will fail.
Rancher's quick-start notes that downstream Kubernetes clusters need network access to the Rancher server endpoint. (Rancher Manager Documentation)
Test from a downstream cluster node:
curl -I \
https://rancher.example.com
Quick Installation — Internal Rancher Certificate
Assume:
Rancher hostname:
rancher.example.com
K3s:
Already installed
Ingress:
Traefik
Add repository:
helm repo add \
rancher-stable \
https://releases.rancher.com/server-charts/stable
helm repo update
Create namespace:
kubectl create namespace cattle-system
Install cert-manager:
helm install \
cert-manager \
oci://quay.io/jetstack/charts/cert-manager \
--version v1.21.1 \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
Verify:
kubectl get pods \
-n cert-manager
Install Rancher:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=3 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
Wait:
kubectl -n cattle-system \
rollout status \
deployment/rancher
Open:
https://rancher.example.com
Quick Installation — Single-Node Test
For one K3s node:
helm repo add \
rancher-stable \
https://releases.rancher.com/server-charts/stable
helm repo update
kubectl create namespace cattle-system
Install cert-manager:
helm install \
cert-manager \
oci://quay.io/jetstack/charts/cert-manager \
--version v1.21.1 \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
Install Rancher:
helm install rancher \
rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.example.com \
--set replicas=1 \
--set bootstrapPassword='YOUR_STRONG_PASSWORD'
Verify:
kubectl -n cattle-system \
rollout status \
deployment/rancher
Recommended Production Configuration
DNS:
rancher.example.com
TLS:
Trusted certificate or managed certificate
K3s:
3 control-plane/etcd nodes
Rancher:
3 replicas
Ingress:
Traefik
External access:
443/TCP
Management cluster:
Dedicated where practical
Backup:
Rancher Backup Operator + K3s etcd snapshots
Architecture:
DNS
rancher.example.com
│
▼
VIP / Load Balancer
│
▼
K3s Traefik
│
┌───────────┼───────────┐
▼ ▼ ▼
Rancher-1 Rancher-2 Rancher-3
│ │ │
└───────────┼───────────┘
│
K3s HA Cluster
┌───────────┼───────────┐
▼ ▼ ▼
k3s-01 k3s-02 k3s-03
etcd etcd etcd
Recommended Production Checklist
- [ ] Install Rancher on a supported K3s/Kubernetes version.
- [ ] Use Helm 3.
- [ ] Use
rancher-stablefor production. - [ ] Use a real DNS hostname.
- [ ] Use a stable load-balancer/VIP address for HA.
- [ ] Use three K3s control-plane/etcd nodes for production HA.
- [ ] Use three Rancher replicas where resources allow.
- [ ] Keep K3s Traefik or another supported ingress controller running.
- [ ] Use TLS for all Rancher access.
- [ ] Install cert-manager when using Rancher-generated or Let's Encrypt certificates.
- [ ] Use trusted certificates for public production access.
- [ ] Restrict administrative access appropriately.
- [ ] Keep TCP
443reachable from downstream clusters. - [ ] Keep port
80reachable when using Let's Encrypt HTTP-01. - [ ] Save Rancher Helm values.
- [ ] Pin Rancher versions in controlled production deployments.
- [ ] Review release notes before upgrades.
- [ ] Back up Rancher management data.
- [ ] Back up K3s embedded etcd.
- [ ] Store backups outside the management cluster.
- [ ] Monitor
cattle-system,cert-manager, and Traefik. - [ ] Ensure downstream cluster nodes can resolve and reach the Rancher hostname.
References
Rancher's official Kubernetes installation guide requires an existing Kubernetes cluster, an ingress controller, kubectl, and Helm 3. Rancher is installed into cattle-system using its Helm chart. K3s already includes an ingress controller by default. (Rancher Manager Documentation)
For production, Rancher provides the rancher-stable Helm repository, while rancher-latest is intended for newer feature testing. (Rancher Manager Documentation)
Rancher supports Rancher-generated certificates, Let's Encrypt, or certificates supplied through Kubernetes secrets. cert-manager is required for Rancher-generated and Let's Encrypt certificate modes. (Rancher Manager Documentation)
The current cert-manager documentation recommends its OCI Helm chart and currently documents v1.21.1 using --set crds.enabled=true. (cert-manager)
Rancher's official installation verification uses:
kubectl -n cattle-system rollout status deploy/rancher
and recommends preserving the Helm values used during installation for future upgrades. (Rancher Manager Documentation)





