↓ Skip to main content
mi-homes.org

Rancher setup

Table of Contents

This guide installs and operates Rancher on an existing Kubernetes cluster using Helm and cert-manager.

Official docs: Install/Upgrade Rancher on a Kubernetes Cluster

Prerequisites
#

  • Kubernetes cluster (K3s, RKE2, EKS, or any supported distribution)
  • kubectl and Helm installed

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 (default). Skip if you use your own certificates (ingress.tls.source=secret) or TLS termination on an external load balancer.

CRDs are applied separately so they are not removed on helm uninstall; use 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
#

Use one of the methods below. Set hostname to the DNS name that points to your cluster (e.g. load balancer, node, or Cloudflare Tunnel). If you use a Cloudflare Tunnel, use Rancher-generated certs or certificates from files; Let’s Encrypt HTTP-01 is usually not suitable behind a tunnel.

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

Expect 5–15 minutes for the first install. It is slow because:

  • Image pulls: Rancher and cert-manager pull several large images; first pull on a node is the main cost.
  • Certificate issuance: With Rancher-generated certs, cert-manager must create and issue the TLS certificate (often 1–2 minutes).
  • Bootstrap: On first start Rancher initializes its database, runs migrations, installs CRDs, and deploys internal components (e.g. Fleet); only then does the deployment become Ready.

To watch progress: kubectl get pods -n cattle-system -w and kubectl get certificate -n cattle-system.

Then go to the URL to log in and register clusters.