Installing Rancher on k3s with Helm Charts
Technology shifted with Containerization nowadays. Almost all modern workloads running over Kubernetes(K8S) based containers. In this article, I targeted installation of Rancher software on a k3s cluster by using Helm charts.
K3s is one of the best and popular Kubernetes based container solution that provides native K8s services, and a group of popular and mature tools like Traefik (Ingress), Flannel (CNI), Klipper (Load Balancer) and Helm (Tons of stuff!). K3s is a CNCF (Cloud Native Computing Foundation) certified software.
Rancher is a total software solution that supported by Suse, centralized K8s clusters management, manage security and authentication in a single Dashboard, thus DevOps and Infrastructure teams completely control their containerized workloads. Rancher is also a CNCF certified software. Rancher identifies itself by these words:
Rancher is a complete software stack for teams adopting containers. It addresses the operational and security challenges of managing multiple Kubernetes clusters across any infrastructure, while providing DevOps teams with integrated tools for running containerized workloads
Rancher also a loved sofware by DevOps Engineers, SRE’s and Infra’ Engineers due to its clean and simple interface.
Helm is a tool for managing Kubernetes packages (software, services) called charts. Helm is CNCF certifies software. Helm can do the following:
- Create new charts from scratch,
- Package charts into chart archive (tgz) files,
- Interact with chart repositories where charts are stored,
- Install and uninstall charts into an existing Kubernetes cluster,
- Manage the release cycle of charts that have been installed with Helm.
Installing K3s
Most essential and vital part of our setup is installing K3s.I preferred K3s over other Kubernetes distributions because of its completeness and simplicity. Also, K3s is lightweight distribution, its binary size lower than 60 MB, compatible and optimized for ARM architecture alongside AMD/x64 platforms. You can run it as a single node and transform in a complex production grade cluster easily.
First of all, obviously you need a Linux based operating system that running on either virtual or bare metal server. I preferred an Ubuntu 22.04 LTS Gen-2 as DS2v3 Azure VM. K3s supports a lot of different linux distros, therefore I recommend you check the documentation before installation.
You can install the latest version just by running the following code. If you want to install an earlier version, please check the documentation
curl -sfL https://get.k3s.io | sh -
You should check k3s cluster state, by running
sudo k3s kubectl get node
As you see, installing and start to using a Kubernetes cluster is as easy as eating a piece of cake. Like you see in the Screenshot2 above, k3s includes its own kubectl binary by prefixing k3s command, like sudo k3s kubectl bla bla.
You can still (and you will) download and use official kubectl binary from internet or anywhere else. I’ll show you that in the next part.
Installing Rancher
Rancher part is more complex compared to k3s installation, because of additional tools and component requirements.
Requirements
1- Kubectl
2- Helm
3- cert-manager
Start with kubectl. Even we have a kubectl binary which provided with k3s installation, we will not use it because of the embedded kubectl binary needs to prefix “sudo k3s”, “Helm” will not be aware of the kubectl binary, and out commands will not work. For this reason, we should use the official binary from the Kubernetes web site. To get the official copy, click to Install Tools | Kubernetes link.
You can copy the following code to your k3s node(s)
# Download the latest kubectl binary
curl -LO https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl# Validate package (optional, but recomended) :
curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256) kubectl" | sha256sum --check
# If everything is ok, you'll get
# kubectl: OK
# else
# kubectl: FAILED
# sha256sum: WARNING: 1 computed checksum did NOT match
After we validate our kubectl binary, its is time to install it on our 3s node:
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectlNote:
If you do not have root access on the target system, you can still install kubectl to the ~/.local/bin directory:
chmod +x kubectl
mkdir -p ~/.local/bin
mv ./kubectl ~/.local/bin/kubectl
# and then append (or prepend) ~/.local/bin to $PATHTo test out kubectl if it is works or not, run :
kubectl version –clientThe output should be like this:
If you’re getting a similar error like below, this is because of related to location of kubeconfig file is not in your profile folder, it is placed in /etc/rancher/k3s/k3s.yaml
In this case, run the following commands in your shell:
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
sudo chmod 755 /etc/rancher/k3s/k3s.yamlYour problem will be fly away :)
After installation of kubectl part, we have completed the first part of requirements. Then we can continue to installation of the “Helm” software. As I mentioned above, there is a Helm installation that comes with K3s setup process. Like kubectl, you need to add “sudo k3s” prefix in order to run embedded Helm. We can't proceed with embedded and prefixed tools, else our commands will not work. So, we need to install Helm separately.
There are tons of methods to install Helm. Because of I have an Ubuntu machine, I can install Helm with snap package manager. You can find your appropriate method regarding your distribution and preferences.
sudo snap install helm --classicYou see a message after like this :
Add rancher-stable Helm repo. You can prefer development or other repos too. I preferred stable repo for this article :
helm repo add rancher-stable https://releases.rancher.com/server-charts/stableCreate a namespace in kubernetes for the Rancher :
kubectl create namespace cattle-system
# You should see a similar message :
namespace/cattle-system createdCert-manager is another and one of the most important and complex requirements for our installation process. cert-manager enables Rancher to create a “Self-signed” certificate, using “Let’s Encrypt” certificate or allows you to “use your own” certificates. Installation of Rancher requires this component and Installation method varies belong your cert-manager configuration.
Here you can see the differences across methods :
a. Rancher-generated TLS certificate: In this case, you will need to install cert-manager into the cluster. Rancher utilizes cert-manager to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. cert-manager is then responsible for managing that certificate.
b. Let’s Encrypt: The Let’s Encrypt option also uses cert-manager. However, in this case, cert-manager is combined with a special Issuer for Let’s Encrypt that performs all actions (including request and validation) necessary for getting a Let’s Encrypt issued cert. This configuration uses HTTP validation (HTTP-01), so the load balancer must have a public DNS record and be accessible from the internet.
Bring your own certificate: This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name tls.crt and tls.key. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
W e will continue using Let’s encrypt certificate configuration. For production grade Rancher installation, you should choose Bring your own certificate option.
Before proceeding, you must install cert-manager like below :
# Installing Custom resource definitions, just run
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
# You should see a similar output like below :
customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/issuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/orders.acme.cert-manager.io createdNote: According to current stable Rancher, K8s and K3s versions, I chose v1.11.0. You may read my article after a long time or new versions can released. You may need to change v1.11.0 to another version number, else your CRD’s couldn’t be defined in K8s cluster properly, or you may get stupid errors.
Let’s continue after this little note. Now time to create a namespace in K8s cluster for cert-manager :
kubectl create namespace cert-manager
# Expected output be like
namespace/cert-manager createdWe also need a little component named Jetstack. It is required by cert-manager. We add it via Helm, again..
helm repo add jetstack https://charts.jetstack.io
# Output would be like:
"jetstack" has been added to your repositoriesWe already added Rancher and Jetstack repos. We should update repos in order to work without problem. To update Helm repos, run :
helm repo update
# Output would be similar below:
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "jetstack" chart repository
...Successfully got an update from the "rancher-stable" chart repository
Update Complete. ⎈Happy Helming!⎈Now it time to install cert-manager
helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v1.11.01You will see a Helm output like:
NAME: cert-manager
LAST DEPLOYED: Wed Jul 19 12:19:30 2023
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
cert-manager v1.11.0 has been deployed successfully!
In order to begin issuing certificates, you will need to set up a ClusterIssuer
or Issuer resource (for example, by creating a 'letsencrypt-staging' issuer).
More information on the different types of issuers and how to configure them
can be found in our documentation:
https://cert-manager.io/docs/configuration/
For information on how to configure cert-manager to automatically provision
Certificates for Ingress resources, take a look at the `ingress-shim`
documentation:
https://cert-manager.io/docs/usage/ingress/To ensure our cert-manager is installed properly, we can check it via following command:
kubectl get pods --namespace cert-manager
NAME READY STATUS RESTARTS AGE
cert-manager-cainjector-744bb89575-kws7x 1/1 Running 0 2m1s
cert-manager-6d6769565c-k4xsf 1/1 Running 0 2m1s
cert-manager-webhook-759d6dcbf7-lwpbr 1/1 Running 0 2m1sRancher Installation
Until now, everything that we did for the install the Rancher’s prerequisites. And we completed all the required steps to start our main setup process. As I metioned again and again, Rancher will be installed via Helm charts. Here you can find a sample helm command to install your Rancher software :
helm install rancher rancher-stable/rancher \
--namespace cattle-system \
--set hostname=rancher.kolukisa.org \
--set bootstrapPassword=admin \
--set ingress.tls.source=letsEncrypt \
--set letsEncrypt.email=mail@kolukisa.org \
--set letsEncrypt.ingress.class=nginxI will explain parameters:
a. helm install rancher rancher-stable/rancher : Main command, it defines the installation name as rancher, software that will be installed as rancher-stable and repo as rancher.
b. --namespace cattle-system : This is namespace in K8s cluster that Rancher’s will be installed.
c. --set bootstrapPassword=admin : You set a temporary bootstrap password for the initialization of Rancher setup. You can modify it but don’t forget to save in a secure place, at least temporarily.
d. — set ingress.tls.source=letsEncrypt : In this step, you choose letsEncrypt as tls source.
e. — set letsEncrypt.email=mail@kolukisa.org : You include an e-mail address to your SSL certificate by entering this variable.
f. — set letsEncrypt.ingress.class=nginx : Defines the ingress class for “letsEncrypt” as nginx. You can leave it as above unless you have to change.
g. — set hostname=rancher.kolukisa.org : DNS record of Rancher. You must define this record before or after Rancher installation. But after installed the record must exist to perform some post installation steps.
You must point your K8s host(s) public ip address or your Loadbalancer’s ip address if your K8s nodes placed behind a firewall.
After running the command above, your Rancher installation should be done. But you can encounter a nasty error like these:
Error: INSTALLATION FAILED: chart requires kubeVersion: < 1.27.0–0 which is incompatible with Kubernetes v1.27.3+k3s1
This is because If you have the latest K8sversion, and the current version of your Rancher’s Helm chart is incompatible with your Kubernetes version you would get the above error message.
Don’t lose your motivation! I have a solution for you. It just takes your extra 10 minutes.
Solution
Solution is simply downgrade your K8s version to a lower version that is compatible with the Helm chart.
The error message indicates the kubernetes version must be lower than v1.27.0–0. The highest version of kubernetes version k3s before v1.27.0.0 is v1.26.9. You can browse or reach the version from the following link
Go to Releases · k3s-io/k3s (github.com)
You can get the kubernetes v.1.26.9 from here :
Release v1.26.6+k3s1 · k3s-io/k3s (github.com)
a. Download the required version binary to your k3s node
wget https://github.com/k3s-io/k3s/releases/download/v1.26.6%2Bk3s1/k3sa. Copy the binary to the k3s binary location
sudo cp k3s /usr/local/bin/k3sb. Restart k3s
sudo systemctl restart k3sc. Check the version of the kubernetes binary :
kubectl get nodes
NAME STATUS ROLES AGE VERSION
k3s01 Ready control-plane,master 23h v1.26.6+k3s1Now try again to install Rancher
helm install rancher rancher-stable/rancher --namespace cattle-system --set hostname=rancher.kolukisa.org --set bootstrapPassword=admin --set ingress.tls.source=letsEncrypt --set letsEncrypt.email=mail@kolukisa.org --set letsEncrypt.ingress.class=nginxYour output would be like those:
NAME: rancher
LAST DEPLOYED: Wed Jul 19 13:08:56 2023
NAMESPACE: cattle-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Rancher Server has been installed.
NOTE: Rancher may take several minutes to fully initialize. Please standby while Certificates are being issued, Containers are started and the Ingress rule comes up.
Check out our docs at https://rancher.com/docs/
If you provided your own bootstrap password during installation, browse to https://rancher.kolukisa.org to get started.
If this is the first time you installed Rancher, get started by running this command and clicking the URL it generates:
```
echo https://rancher.kolukisa.org/dashboard/?setup=$(kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}')
```
To get just the bootstrap password on its own, run:
```
kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}{{ "\n" }}'
```
Happy Containering!If you forgot your bootstrap password, you can run
kubectl get secret - namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}{{ "\n" }}'Command, as mentioned in earlier output. It will be used to start our Rancher dashboard, and it is the temporary password for the Rancher.
Run the following command (it is already placed in the rancher installation output!) to get your dashboard initialization url
echo https://rancher.kolukisa.org/dashboard/?setup=$(kubectl get secret - namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}')https://rancher.kolukisa.org/dashboard/?setup=admin
Just browse the address (Assuming your DNS record exist and works + you allowed https port in your firewall to access TCP 443 for accesing the k3s node) with your browser.
Until now everyhing is OK, You can use the preconfigured complex password for dashboard access, or define a new complex password for the Rancher UI. Accept Eula and start your Rancher journey. Rancher would meet you with green trees and meadows with additional cluster info :)
In this article I tell you how to install Rancher on a K3s cluster with Helm charts. Rancher can be installed by many ways on different platforms. You can find more on the following link, Installing/Upgrading Rancher | Rancher .
Thank you for reading or listening my article, I hope it is beneficial for you. You can always write down if you encounter error related this setup.
Have a nice day!
Özgür Kolukısa
