Skip to content

Installing a single node RKE2 Kubernetes distribution

Introduction

In homelab environment it's nice to have a host which can run containerized apps. For running containers on such host you can use Docker, Podman or Kubernetes. In this post I will show how to install RKE2 Kubernetes distribution.

OS used: Debian 12
Software used: RKE2 1.30.10

Source

RKE2 installation

Typically, two parts of RKE2 are installed on separate virtual machines to form Kubernetes cluster:

  • Server Node
  • Agent (Worker) Node

In this post only server node will be installed for a single node RKE2 deployment. Server node can run containers in the same way as Agent node.

In the beginning create new virtual machine for example using tutorial Fast initialization of Debian VM using Ansible.

RKE2 storage requirements

Resize your RKE2 virtual machine disk to have enough free space for images, containers and few extra GB for Etcd snapshots that RKE2 makes by default. RKE2 biggest files are stored in path /var/lib/rancher/rke2/.

IP address

Kubernetes can stop working if you change IP address of a node so set static IP.

Firewall rules

If you have firewall enabled in Debian 12 and it's nftables disable it, because RKE2 creates its own firewall rules (such as forwarding traffic between containers) and don't work correctly with other rules. That is because kube-proxy (developed by upstream Kubernetes project) which manage firewall and NAT rules used by RKE2 is based on iptables. In this situation it will use iptables in nftables mode, which means only iptables features can be used and this causes problems.

Leave only these lines in nftables config file to disable your rules:

$ sudo vim /etc/nftables.conf
/etc/nftables.conf
#!/usr/sbin/nft -f

flush ruleset

Reload firewall rules with command:

$ sudo systemctl restart nftables.service

In order to see firewall ruleset use command:

$ sudo nft list ruleset

Tip

If you want your single node RKE2 instance protected with firewall enable firewall for virtual machine in Proxmox. Then open following ports using firewall:

  • TCP 22 - SSH access to virtual machine
  • TCP 443 - HTTPS for web applications running in containers. To run many applications on one port Ingress Controller will be used and it acts as reverse proxy allowing many applications to be accessible on one port, but under different URLs.

Server Node installation

Run the server node installation script:

$ sudo sh -c 'curl -sfL https://get.rke2.io | sh -'

sudo sh -c <command> - run many commands with one sudo, here we have 2 commands - curl and after | sh

Enable and start rke2-server service:

$ sudo systemctl enable rke2-server.service && \
  sudo systemctl start rke2-server.service

Note

Server node takes some time to start (2 - 5 min) so be patient.

Kubectl utility

kubectl utility is installed with RKE2 but to use it you need root privileges. If you want to be able to run kubectl as user do as follows:

  • Create new group rke2 and add your user to that group:
$ sudo groupadd rke2 && \
  sudo usermod -aG rke2 <user-name>

  • Login again to be in this new group.

  • Add group read and own permission to file /etc/rancher/rke2/rke2.yaml. It must be done using RKE2 config file, because with normal change of file permission RKE2 will return those permissions to default 600:

$ sudo vim /etc/rancher/rke2/config.yaml
/etc/rancher/rke2/config.yaml
write-kubeconfig-mode: "0640"
write-kubeconfig-group: "rke2"

  • Restart rke2-server service:
$ sudo systemctl restart rke2-server.service
  • For kubectl utility to work correctly for your user enter following commands to export environment variables:
$ echo -e "\n# RKE2 environment variables" >> ~/.bashrc && \
  echo "export PATH=$PATH:/var/lib/rancher/rke2/bin" >> ~/.bashrc && \
  echo "export KUBECONFIG=/etc/rancher/rke2/rke2.yaml" >> ~/.bashrc

echo -e - enable interpretation of backslash escapes

  • Login again to enable kubectl for your user.

Enable autocompletion for kubectl

To enable bash autocompletion for kubectl (when using Tab key) run command:

$ echo 'source <(kubectl completion bash)' >>~/.bashrc

Login again or run following command to enable bash autocompletion in current session:

$ source ~/.bashrc

Test installation

Test if installation was completed by running commands:

$ kubectl get node -o wide
$ kubectl get all -A -o wide

Upgrade RKE2

To upgrade RKE2 to new version re-run installation script using the same flags as when it was installed, in this case it will be:

$ sudo sh -c 'curl -sfL https://get.rke2.io | sh -'

Appendix - Agent Node installation

If you want to add agent node to your cluster run commands below on new virtual machine.

Run agent node installation script:

$ sudo sh -c 'curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -'

Configure agent node by creating config file:

$ sudo vim /etc/rancher/rke2/config.yaml
/etc/rancher/rke2/config.yaml
server: https://<server>:9345
token: <token from server node>

<server> - server node ip address or domain name
<token from server node> - get token value from server node by using command cat /var/lib/rancher/rke2/server/node-token

Enable and start rke2-agent service:

$ sudo systemctl enable rke2-agent.service && \
  sudo systemctl start rke2-agent.service

On Server Node open following ports if you are using firewall:

  • TCP 6443 - Kubernetes API
  • TCP 9345 - RKE2 supervisor API

Complete list of ports used by RKE2 is covered in RKE2 official documentation - Requirements: Networking.