Quick Start
This guide will help you quickly launch a cluster with default options.
New to Kubernetes? The official Kubernetes docs already have some great tutorials outlining the basics here.
Prerequisites
-
Make sure your environment fulfills the requirements. If NetworkManager is installed and enabled on your hosts, ensure that it is configured to ignore CNI-managed interfaces.
-
If the host kernel supports AppArmor, the AppArmor tools (usually available via the
apparmor-parser
package) must also be present prior to installing RKE2. -
The RKE2 installation process must be run as the root user or through
sudo
.
Server Node Installation
RKE2 provides an installation script that is a convenient way to install it as a service on systemd based systems. This script is available at https://get.rke2.io. To install RKE2 using this method do the following:
1. Run the installer
curl -sfL https://get.rke2.io | sh -
This will install the rke2-server
service and the rke2
binary onto your machine. Due to its nature, It will fail unless it runs as the root user or through sudo
.
2. Enable the rke2-server service
systemctl enable rke2-server.service
3. Start the service
systemctl start rke2-server.service
4. Follow the logs, if you like
journalctl -u rke2-server -f
After running this installation:
- The
rke2-server
service will be installed. Therke2-server
service will be configured to automatically restart after node reboots or if the process crashes or is killed. - Additional utilities will be installed at
/var/lib/rancher/rke2/bin/
. They include:kubectl
,crictl
, andctr
. Note that these are not on your path by default. - Two cleanup scripts,
rke2-killall.sh
andrke2-uninstall.sh
, will be installed to the path at:/usr/local/bin
for regular file systems/opt/rke2/bin
for read-only and brtfs file systemsINSTALL_RKE2_TAR_PREFIX/bin
ifINSTALL_RKE2_TAR_PREFIX
is set
- A kubeconfig file will be written to
/etc/rancher/rke2/rke2.yaml
. - A token that can be used to register other server or agent nodes will be created at
/var/lib/rancher/rke2/server/node-token
If you are adding additional server nodes, you must have an odd number in total. An odd number is needed to maintain quorum. See the High Availability documentation for more details.
Linux Agent (Worker) Node Installation
The steps on this section requires root level access or sudo
to work.
1. Run the installer
curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -
This will install the rke2-agent
service and the rke2
binary onto your machine. Due to its nature, It will fail unless it runs as the root user or through sudo
.
2. Enable the rke2-agent service
systemctl enable rke2-agent.service
3. Configure the rke2-agent service
mkdir -p /etc/rancher/rke2/
vim /etc/rancher/rke2/config.yaml
Content for config.yaml:
server: https://<server>:9345
token: <token from server node>
The rke2 server
process listens on port 9345
for new nodes to register. The Kubernetes API is still served on port 6443
, as normal.
4. Start the service
systemctl start rke2-agent.service
Follow the logs, if you like
journalctl -u rke2-agent -f
Note: Each machine must have a unique hostname. If your machines do not have unique hostnames, set the node-name
parameter in the config.yaml
file and provide a value with a valid and unique hostname for each node.
To read more about the config.yaml file, see the Install Options documentation.
Windows Agent (Worker) Node Installation
Windows Support works with Calico or Flannel as the CNI for the RKE2 cluster
0. Prepare the Windows Agent Node
Note The Windows Server Containers feature needs to be enabled for the RKE2 agent to work.
Open a new Powershell window with Administrator privileges
powershell -Command "Start-Process PowerShell -Verb RunAs"
In the new Powershell window, run the following command to install the containers feature.
Enable-WindowsOptionalFeature -Online -FeatureName containers –All
This will require a reboot for the Containers
feature to properly function.
1. Download the Install Script
Invoke-WebRequest -Uri https://raw.githubusercontent.com/rancher/rke2/master/install.ps1 -Outfile install.ps1
This script will download the rke2.exe
Windows binary onto your machine.
2. Configure the rke2-agent for Windows
New-Item -Type Directory c:/etc/rancher/rke2 -Force
Set-Content -Path c:/etc/rancher/rke2/config.yaml -Value @"
server: https://<server>:9345
token: <token from server node>
"@
To read more about the config.yaml file, see the Install Options documentation.
3. Configure PATH
$env:PATH+=";c:\var\lib\rancher\rke2\bin;c:\usr\local\bin"
[Environment]::SetEnvironmentVariable(
"Path",
[Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::Machine) + ";c:\var\lib\rancher\rke2\bin;c:\usr\local\bin",
[EnvironmentVariableTarget]::Machine)
4. Run the Installer
./install.ps1
5. Start the Windows RKE2 Service
rke2.exe agent service --add
Note: Each machine must have a unique hostname.
Don't forget to start the RKE2 service with:
Start-Service rke2
If you would prefer to use CLI parameters only instead, run the binary with the desired parameters.
rke2.exe agent --token <> --server <>