--- title: "How to Install Rancher on K3s with Helm and Let's Encrypt" description: "Install Rancher on a K3s cluster on Ubuntu 24.04 with Helm and cert-manager, secure it with Let's Encrypt, log in and import an existing Kubernetes cluster." category: "Kubernetes Advanced" language: en source: https://cubepath.com/docs/kubernetes-advanced/rancher-installation-for-kubernetes-management updated: 2026-09-25 --- # How to Install Rancher on K3s with Helm and Let's Encrypt Rancher is an open source management platform for Kubernetes. From one web interface you can import existing clusters, provision new RKE2 or K3s clusters, manage users and RBAC across all of them, and deploy applications from Helm charts. In this tutorial you will install Rancher on a single-node K3s cluster running on Ubuntu 24.04, secure it with a Let's Encrypt certificate through cert-manager, complete the first login, and import another Kubernetes cluster into it. ## Prerequisites To follow this tutorial, you will need: - A server running Ubuntu 24.04 LTS with at least 4 vCPU, 8 GB of RAM and 40 GB of disk, for example a CubePath VPS. This server becomes the Rancher management cluster (Rancher calls it the `local` cluster) and should not run other workloads. - A non-root user with `sudo` privileges. - A domain name with an `A` record for the Rancher hostname (this guide uses `rancher.your_domain`) pointing to `your_server_ip`. Let's Encrypt must be able to reach it on port 80. - An email address for Let's Encrypt expiry notices. - Optionally, a second Kubernetes cluster to import in Step 7. > Note: Rancher can also run as a single Docker container, but that method is meant only for short-lived testing and cannot be migrated to a highly available setup. The Helm installation used here is the supported path. ## Step 1 - Configuring the firewall Rancher needs HTTP for the Let's Encrypt challenge, HTTPS for the UI and for agents of downstream clusters, and the Kubernetes API port for your own `kubectl` access. Allow the traffic K3s needs between its pods as well: ```bash sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow from your_admin_ip to any port 6443 proto tcp sudo ufw allow from 10.42.0.0/16 to any sudo ufw allow from 10.43.0.0/16 to any sudo ufw enable ``` Replace `your_admin_ip` with the IP you manage the server from. The two `10.x` rules cover the default K3s pod and service networks. Check the rules: ```bash sudo ufw status ``` ```output Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere 80/tcp ALLOW Anywhere 443/tcp ALLOW Anywhere 6443/tcp ALLOW 203.0.113.50 ... ``` ## Step 2 - Installing K3s with a supported Kubernetes version Each Rancher release supports a specific range of Kubernetes versions, and the Helm chart refuses to install on a newer, unsupported one. Open the Rancher support matrix for the current Rancher release at `https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/`, find the highest supported Kubernetes minor version, and pin K3s to that channel. Download the K3s install script and review it: ```bash curl -sfL https://get.k3s.io -o k3s-install.sh less k3s-install.sh ``` Install K3s from the channel you selected. This example uses `v1.33`; replace it with the version from the matrix: ```bash sudo INSTALL_K3S_CHANNEL=v1.33 sh k3s-install.sh ``` Set up `kubectl` for your user: ```bash mkdir -p ~/.kube sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config sudo chown "$USER":"$USER" ~/.kube/config chmod 600 ~/.kube/config echo 'export KUBECONFIG=$HOME/.kube/config' >> ~/.bashrc source ~/.bashrc ``` Verify the node: ```bash kubectl get nodes ``` ```output NAME STATUS ROLES AGE VERSION rancher-01 Ready control-plane,master 60s v1.33.x+k3s1 ``` K3s ships the Traefik ingress controller, which Rancher will use to serve its UI on ports 80 and 443. ## Step 3 - Installing Helm Install Helm from the snap store and confirm it can reach the cluster: ```bash sudo snap install helm --classic helm version --short helm list -A ``` `helm list -A` should print a table with the Traefik releases K3s installed, and no connection errors. ## Step 4 - Installing cert-manager Rancher uses cert-manager to request and renew its Let's Encrypt certificate. Add the Jetstack repository and install cert-manager together with its CustomResourceDefinitions: ```bash 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=true ``` Wait until its three pods are running: ```bash kubectl -n cert-manager get pods ``` ```output NAME READY STATUS RESTARTS AGE cert-manager-xxxxxxxxxx-xxxxx 1/1 Running 0 50s cert-manager-cainjector-xxxxxxxxxx-xxxxx 1/1 Running 0 50s cert-manager-webhook-xxxxxxxxxx-xxxxx 1/1 Running 0 50s ``` > Important: Do not continue until the webhook pod is `Running`. If Rancher is installed while the webhook is still starting, the certificate resources can fail to be created. ## Step 5 - Installing Rancher Add the Rancher stable chart repository and create the namespace Rancher expects: ```bash helm repo add rancher-stable https://releases.rancher.com/server-charts/stable helm repo update kubectl create namespace cattle-system ``` Install Rancher. Replace `rancher.your_domain` and `your_email`: ```bash helm install rancher rancher-stable/rancher \ --namespace cattle-system \ --set hostname=rancher.your_domain \ --set replicas=1 \ --set ingress.tls.source=letsEncrypt \ --set letsEncrypt.email=your_email \ --set letsEncrypt.ingress.class=traefik ``` - `hostname` must match the DNS record; downstream cluster agents will connect to this name. - `replicas=1` fits a single-node management cluster. The default of 3 is meant for three nodes. - `ingress.tls.source=letsEncrypt` makes Rancher create a cert-manager Issuer and request a certificate, solving the HTTP-01 challenge through Traefik. Wait for the deployment to finish. The first start takes a few minutes: ```bash kubectl -n cattle-system rollout status deploy/rancher ``` ```output Waiting for deployment "rancher" rollout to finish: 0 of 1 updated replicas are available... deployment "rancher" successfully rolled out ``` Check that the certificate was issued: ```bash kubectl -n cattle-system get certificate ``` ```output NAME READY SECRET AGE tls-rancher-ingress True tls-rancher-ingress 3m ``` If `READY` stays `False`, see the Troubleshooting section before continuing. ## Step 6 - Logging in for the first time Rancher generates a random bootstrap password on first install. Print it: ```bash kubectl -n cattle-system get secret bootstrap-secret \ -o go-template='{{.data.bootstrapPassword|base64decode}}{{"\n"}}' ``` Open `https://rancher.your_domain` in your browser. The certificate should be valid, with no warning. Paste the bootstrap password, then: 1. Choose a strong password for the `admin` user and store it in your password manager. 2. Confirm the **Server URL** is `https://rancher.your_domain`. Every downstream cluster agent uses this URL, so it must be reachable from those clusters. 3. Accept the terms and continue. The home page lists one cluster, `local`, which is the K3s cluster running Rancher. Click it to browse its nodes, workloads and events. > Tip: Under **Users & Authentication** you can connect Rancher to GitHub, Azure AD, OpenLDAP, Okta or another identity provider, so your team logs in with their existing accounts instead of local users. ## Step 7 - Importing an existing cluster Importing lets Rancher manage a cluster you already run (for example a K3s, MicroK8s or kubeadm cluster). Rancher deploys an agent into it that connects back to the Rancher server over HTTPS, so the imported cluster only needs outbound access to `rancher.your_domain` on port 443. In the Rancher UI: 1. Open **Cluster Management** from the main menu. 2. Click **Import Existing**, then **Generic**. 3. Enter a **Cluster Name**, for example `staging`, and click **Create**. Rancher shows a registration command with a unique token. Copy it and run it against the cluster you want to import, using a kubeconfig with admin rights on that cluster (not on the Rancher server). It looks like this: ```bash kubectl apply -f https://rancher.your_domain/v3/import/abcd1234efgh5678.yaml ``` ```output clusterrole.rbac.authorization.k8s.io/proxy-clusterrole-kubeapiserver created clusterrolebinding.rbac.authorization.k8s.io/proxy-role-binding-kubernetes-master created namespace/cattle-system created serviceaccount/cattle created ... deployment.apps/cattle-cluster-agent created ``` On the imported cluster, check that the agent is running: ```bash kubectl -n cattle-system get pods ``` ```output NAME READY STATUS RESTARTS AGE cattle-cluster-agent-xxxxxxxxxx-xxxxx 1/1 Running 0 90s ``` After a minute or two, the cluster changes to **Active** in **Cluster Management**. You can now open it from Rancher, browse its workloads, use the built-in `kubectl` shell and assign cluster or project roles to users. ## Troubleshooting **The Helm install fails with a Kubernetes version error.** The K3s version is newer than the Rancher release supports. Reinstall K3s from a supported channel (Step 2), or use a newer Rancher release if one supports your version. **The certificate stays `READY False`.** Inspect the chain with `kubectl -n cattle-system describe certificate tls-rancher-ingress` and `kubectl -n cattle-system get challenges`. The usual causes are a DNS record that does not point to the server yet or port 80 blocked by a firewall. Let's Encrypt must reach `http://rancher.your_domain/.well-known/acme-challenge/` from the Internet. **The browser shows `404 page not found` from Traefik.** The Rancher Ingress was not created or its host does not match the URL. Check with `kubectl -n cattle-system get ingress`. **An imported cluster stays in `Pending`.** Read the agent logs on that cluster with `kubectl -n cattle-system logs deploy/cattle-cluster-agent`. The agent must resolve `rancher.your_domain` and reach it on port 443. ## Conclusion You installed Rancher on a K3s cluster with Helm, secured it with a Let's Encrypt certificate managed by cert-manager, completed the first login and imported an existing cluster. Next, connect an external identity provider for your team, provision new RKE2 or K3s clusters on your servers from **Cluster Management**, and, for production, move Rancher to a three-node K3s or RKE2 cluster with `replicas=3` and regular etcd backups.