In this tutorial, we’ll walk through the process of setting up Rancher on a K3s cluster. We’ll cover prerequisites like setting up an Ingress Controller, configuring a Domain Name, enabling SSL with Let’s Encrypt, and editing the agent-tls-mode before registering your existing cluster to Rancher.
Prerequisites
- A K3s cluster running (either on a local machine or in a cloud environment).
- kubectl installed and configured to interact with the K3s cluster.
- A domain name that you can point to your K3s server (e.g., rancher.example.com).
- Access to the internet for downloading Rancher and obtaining SSL certificates (via Let’s Encrypt).
Step 1: Install K3s
If you don’t already have K3s installed, you can install it with the following command on your master node:
| curl -sfL https://get.k3s.io | sh – |
Verify the installation by checking the node status:
| kubectl get nodes |
You should see your K3s node listed.
Step 2: Set Up Ingress Controller
Rancher requires an Ingress controller to handle external traffic. We will use Traefik, which is the default Ingress controller in K3s.
To ensure Traefik is installed, run:
| kubectl get pods -n kube-system | grep traefik |
You should see a traefik pod running. If it’s not running, you can install it manually using Helm (optional).
Step 3: Configure Domain for Rancher
Now, you need to configure your DNS to point to your K3s node’s IP address. You will need a domain name (e.g., rancher.example.com).
Create a DNS A record pointing to the IP address of your K3s server.
Example:
arduino
| rancher.example.com -> <Your-K3s-Server-IP> |
Step 4: Install Rancher
To install Rancher using Helm, first add the Rancher chart repository:
| helm repo add rancher-latest https://releases.rancher.com/server-charts/latest helm repo update |
Now, install Rancher on your cluster. Ensure that Traefik is enabled and that you’re installing Rancher in the cattle-system namespace.
| kubectl create namespace cattle-system |
| helm install rancher rancher-latest/rancher \ –namespace cattle-system \ –set hostname=rancher.example.com \ –set replicas=1 |
This will install Rancher and expose it on your domain (rancher.example.com).
Step 5: Set Up SSL with Let’s Encrypt
To ensure secure communication, we’ll set up SSL using Let’s Encrypt for automatic SSL certificate management.
- Create a certificate for Rancher by editing the Helm values to include Let’s Encrypt settings:
| helm upgrade rancher rancher-latest/rancher \ –namespace cattle-system \ –set hostname=rancher.example.com \ –set replicas=1 \ –set ingress.tls=true \ –set ingress.extraAnnotations.”cert-manager\.io/cluster-issuer”=”letsencrypt-prod” |
- Install Cert-Manager (if you haven’t already) to handle SSL certificates with Let’s Encrypt:
| kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.11.0/cert-manager.yaml |
- Create a ClusterIssuer for Let’s Encrypt:
Create a ClusterIssuer for Let’s Encrypt to automatically issue certificates:
| apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: lets-encrypt-prod spec: acme: email: your-email@example.com server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: name: lets-encrypt-prod solvers: – http01: ingress: class: traefik |
Apply the configuration:
| kubectl apply -f lets-encrypt-prod-clusterissuer.yaml |
This will enable automatic SSL certification via Let’s Encrypt.
Step 6: Edit agent-tls-mode Before Registering the Cluster
Now that Rancher is installed and accessible via your domain, you need to configure the agent-tls-mode to allow the K3s cluster to register with Rancher.
Before registering your existing cluster to Rancher, you’ll need to edit the agent-tls-mode setting. By default, Rancher uses strict TLS mode, but you may need to change it to system-store for K3s clusters.
Patch the agent-tls-mode setting:
Run the following kubectl command to change the setting from strict to system-store:
| kubectl patch setting agent-tls-mode -n cattle-system –type merge -p ‘{“value”: “system-store”}’ |
Verify the Change:
Confirm that the change has been applied successfully by checking the setting:
| kubectl get setting agent-tls-mode -n cattle-system -o yaml |
- You should now see the value set to system-store.
Step 7: Register the Existing Cluster to Rancher
- Access the Rancher UI by navigating to https://rancher.example.com in your browser.
- Log in with the credentials you set up during installation.
- Once logged in, click on “Add Cluster” and follow the instructions for registering your K3s cluster. You will need to run a registration command on your K3s cluster.
Rancher will generate a command to run on the K3s cluster for registration. Copy and run this command on your K3s node:
| curl -sfL https://get.rancher.io | sh – |
After the registration process is complete, your K3s cluster will be managed via Rancher!
Port-Forwarding:
For testing or development purposes, you can use port-forwarding to access Rancher without exposing it externally:
| kubectl port-forward svc/rancher -n cattle-system 8080:80 |
- Then you can access Rancher locally via http://localhost:8080. However, this is not recommended for production environments as it limits external access.
If you want to access and log in to Rancher using a public domain, you will need to:
- Set Up a Public Domain: You should have a domain (e.g., rancher.example.com) that points to your Rancher server.
- Expose Rancher Using Ingress: Use an Ingress controller to route the public domain traffic to Rancher running in your K3s cluster.
- Set Up SSL/TLS for Security: It’s important to secure your Rancher UI with SSL (HTTPS) to ensure data privacy and security.
Here’s a step-by-step guide on how to configure Rancher to be accessed via a public domain.
Step-by-Step Tutorial for Exposing Rancher via a Public Domain
Step 1: Prepare Your Public Domain
- If you don’t already have one, purchase a domain name (e.g., rancher.example.com) from a domain registrar.
- Point the domain to the IP address of your K3s cluster. If you have a load balancer or public IP, make sure the domain points to it.
- Update your DNS settings (via your domain registrar) to create an A record that points to the IP address of your K3s node or LoadBalancer.
Step 2: Set Up an Ingress Controller
K3s comes with Traefik as the default Ingress controller, but you can install any Ingress controller of your choice.
If you’re using Traefik, it should be installed by default in K3s.
To expose Rancher using Traefik, ensure the Ingress resource for Rancher is correctly set.
Create an Ingress Resource for Rancher:
Create a file called rancher-ingress.yaml with the following content:
| apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: rancher namespace: cattle-system annotations: cert-manager.io/cluster-issuer: “letsencrypt-prod” # Optional, if using Let’s Encrypt spec: rules: – host: rancher.example.com # Replace with your domain http: paths: – path: / pathType: Prefix backend: service: name: rancher port: name: https tls: – hosts: – rancher.example.com secretName: rancher-tls |
Apply this file with:
| kubectl apply -f rancher-ingress.yaml |
- This configures an Ingress to route traffic to Rancher and sets up TLS (SSL) for secure access.
Step 3: Set Up SSL/TLS (HTTPS)
To secure Rancher with HTTPS, you need to configure an SSL certificate for your domain. You can use Let’s Encrypt for free SSL certificates.
Install cert-manager:
| kubectl create namespace cert-manager kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.9.0/cert-manager.yaml |
- Create a ClusterIssuer for Let’s Encrypt: Create a file called letsencrypt-clusterissuer.yaml:
| apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-prod spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: your-email@example.com # Replace with your email privateKeySecretRef: name: letsencrypt-prod solvers: – http01: ingress: class: traefik |
Apply it with:
| kubectl apply -f letsencrypt-clusterissuer.yaml |
- Create the TLS Secret for Rancher: Cert-manager will automatically create a secret for Rancher’s domain using the Let’s Encrypt certificate.
The rancher-ingress.yaml file above already points to the secret rancher-tls, which cert-manager will create once the certificate is issued.
If you set up cert-manager and the ClusterIssuer correctly, Rancher will automatically obtain and apply an SSL certificate from Let’s Encrypt for your public domain.
Step 4: Access Rancher via Your Public Domain
Once the Ingress resource is set up and the SSL certificate is issued (it may take a few minutes), you should be able to access Rancher via your public domain:
- Open a browser and navigate to https://rancher.example.com (replace with your actual domain).
- Log in to the Rancher UI using the default admin password or credentials you set.
Important Notes:
- DNS Propagation: It may take some time for your DNS records to propagate after updating them with your registrar.
- SSL Certificates: If you’re not using Let’s Encrypt or cert-manager, you can manually create and upload an SSL certificate for your domain.
- Firewall & Security: Ensure your firewall rules allow external traffic to the required ports (80 for HTTP, 443 for HTTPS) and that your K3s nodes are correctly exposed.
Conclusion
By following these steps, you’ve successfully installed Rancher on a K3s cluster, set up Ingress, configured your domain, enabled SSL with Let’s Encrypt, and edited the agent-tls-mode for secure registration. Your K3s cluster is now ready to be managed by Rancher!
