↓ Skip to main content
mi-homes.org

Rancher

Table of Contents

This guide installs Rancher on an existing Kubernetes cluster with Helm and cert-manager. Official install and upgrade notes are in Install/Upgrade Rancher on a Kubernetes Cluster.

You need a supported cluster (K3s, RKE2, EKS, or similar) plus kubectl and Helm on the workstation.

Installation
#

1. Add Helm repos
#

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

2. Create namespace
#

kubectl create namespace cattle-system

3. Install cert-manager
#

Required for Rancher-generated TLS certificates (the default). Skip this if you use your own certificates (ingress.tls.source=secret) or terminate TLS on an external load balancer.

Apply CRDs separately so they survive helm uninstall, and set crds.enabled=false so Helm does not try to manage them:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.3/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 \
  --set crds.enabled=false

4. Install Rancher
#

Set hostname to the DNS name that points at the cluster (load balancer, node, or Cloudflare Tunnel). Behind a Cloudflare Tunnel, use Rancher-generated certs or certificates from files; Let’s Encrypt HTTP-01 is usually not suitable.

Rancher-generated certificates (default):

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword='<CHANGE_ME>'

Let’s Encrypt:

helm upgrade --install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword='<CHANGE_ME>' \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=[email protected] \
  --set letsEncrypt.ingress.class=nginx

Your own certificates: create a Kubernetes secret with tls.crt and tls.key, then:

helm upgrade --install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword='<CHANGE_ME>' \
  --set ingress.tls.source=secret

5. Verify
#

kubectl -n cattle-system rollout status deploy/rancher

The first install often takes 5–15 minutes. Rancher and cert-manager pull large images, cert-manager issues the TLS certificate (often 1–2 minutes with generated certs), and Rancher then initializes its database, runs migrations, installs CRDs, and deploys internal components such as Fleet before the Deployment becomes Ready. Watch with kubectl get pods -n cattle-system -w and kubectl get certificate -n cattle-system. When the rollout finishes, open the hostname to log in and register clusters.