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.

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:

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:

sudo ufw status

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:

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:

sudo INSTALL_K3S_CHANNEL=v1.33 sh k3s-install.sh

Set up kubectl for your user:

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:

kubectl get nodes

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:

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:

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:

kubectl -n cert-manager get pods

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

Step 5 - Installing Rancher

Add the Rancher stable chart repository and create the namespace Rancher expects:

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:

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:

kubectl -n cattle-system rollout status deploy/rancher

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:

kubectl -n cattle-system get certificate

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:

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.

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:

kubectl apply -f https://rancher.your_domain/v3/import/abcd1234efgh5678.yaml

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:

kubectl -n cattle-system get pods

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.