Over 10 years we help companies reach their financial and branding goals. Engitech is a values-driven technology agency dedicated.

Gallery

Contacts

411 University St, Seattle, USA

+1 -800-456-478-23

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:

📘 K3s Installation Wiki


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

(cert-manager)


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-stable for 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 443 reachable from downstream clusters.
  • [ ] Keep port 80 reachable 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)

Leave a comment

Your email address will not be published. Required fields are marked *