Rancherd bootstraps a node with Kubernetes (k3s/rke2) and Rancher such that all future management of Kubernetes and Rancher can be done from Kubernetes. Rancherd will only run once per node. Once the system has been fully bootstrapped it will not run again. It is intended that the primary use of Rancherd is to be ran from cloud-init or a similar system.
To create a three node cluster run the following on servers named server1
,
server2
, and server3
.
On server1
mkdir -p /etc/rancher/rancherd
cat > /etc/rancher/rancherd/config.yaml << EOF
role: cluster-init
token: somethingrandom
EOF
curl -fL https://raw.githubusercontent.com/rancher/rancherd/master/install.sh | sh -
On server2
mkdir -p /etc/rancher/rancherd
cat > /etc/rancher/rancherd/config.yaml << EOF
role: server
server: https://server1:8443
token: somethingrandom
EOF
curl -fL https://raw.githubusercontent.com/rancher/rancherd/master/install.sh | sh -
On server3
mkdir -p /etc/rancher/rancherd
cat > /etc/rancher/rancherd/config.yaml << EOF
role: server
server: https://server1:8443
token: somethingrandom
EOF
curl -fL https://raw.githubusercontent.com/rancher/rancherd/master/install.sh | sh -
The primary way of running Rancherd is intended to be done from cloud-init.
Add to your cloud-init the following for a single node cluster. All
configuration that would be found in the rancherd config.yaml should
be embedded in the rancherd
key in the cloud-config.
#cloud-config
rancherd:
role: cluster-init
runcmd:
- curl -fL https://raw.githubusercontent.com/rancher/rancherd/master/install.sh | sh -
rancherd
binary can be downloaded from https://github.com/rancher/rancherd/releases/latest
and manually ran.
The below command will download rancherd
binary and setup a systemd unit and run it.
curl -sfL https://https://raw.githubusercontent.com/rancher/rancherd/master/install.sh | sh -
Creating a cluster always starts with one node initializing the cluster, by
assigning the cluster-init
role and then other nodes joining to the cluster.
The new cluster will have a token generated for it or you can manually
assign a unique string. The token for an existing cluster can be determined
by running rancherd get-token
.
Nodes can be joined to the cluster as the role server
to add more control
plane nodes or as the role agent
to add more worker nodes. To join a node
you must have the Rancher server URL (which is by default running on port
8443
) and the token.
Rancherd will bootstrap a node with one of the following roles
- cluster-init: Every cluster must start with one node that has the cluster-init role.
- server: Joins the cluster as a new control-plane,etcd,worker node
- agent: Joins the cluster as a worker only node.
It can be quite cumbersome to automate bringing up a clustered system that requires one bootstrap node. Also there are more considerations around load balancing and replacing nodes in a proper production setup. Rancherd support server discovery based on https://github.com/hashicorp/go-discover.
When using server discovery the cluster-init
role is not used, only server
and agent
. The server
URL is also dropped in place of using the discovery
key. The discovery
configuration will be used to dynamically determine what
is the server URL and if the current node should act as the cluster-init
node.
Example
role: server
discovery:
params:
# Corresponds to go-discover provider name
provider: "mdns"
# All other key/values are parameters corresponding to what
# the go-discover provider is expecting
service: "rancher-server"
# If this is a new cluster it will wait until 3 server are
# available and they all agree on the same cluster-init node
expectedServers: 3
# How long servers are remembered for. It is useful for providers
# that are not consistent in their responses, like mdns.
serverCacheDuration: 1m
More information on how to use the discovery is in the config examples.
Configuration for rancherd goes in /etc/rancher/rancherd/config.yaml
. A full
example configuration with documentation is available in
config-example.yaml.
Minimal configuration
# /etc/rancher/rancherd/config.yaml
# role: Valid values cluster-init, server, agent
role: cluster-init
# token: A shared secret known by all clusters in the system
token: somethingrandom
# server: The server URL to join a cluster to. By default port 8443.
# Only valid for roles server and agent, not cluster-init
server: https://example.com:8443
The kubernetesVersion
and rancherVersion
accept channel names instead of explict versions.
Valid kubernetesVersion
channels are as follows:
Channel Name | Description |
---|---|
stable | k3s stable (default value of kubernetesVersion) |
latest | k3s latest |
testing | k3s test |
stable:k3s | Same as stable channel |
latest:k3s | Same as latest channel |
testing:k3s | Same as testing channel |
stable:rke2 | rke2 stable |
latest:rke2 | rke2 latest |
testing:rke2 | rke2 testing |
v1.21 | Latest k3s v1.21 release. The applies to any Kubernetes minor version |
v1.21:rke2 | Latest rke2 v1.21 release. The applies to any Kubernetes minor version |
Valid rancherVersions
channels are as follows:
Channel Name | Description |
---|---|
stable | stable helm repo (default value of rancherVersion) |
latest | latest helm repo |
By default Rancher is installed with the following values.yaml. You can override
any of these settings with the rancherValues
setting in the rancherd config.yaml
# Multi-Cluster Management is disabled by default, change to multi-cluster-management=true to enable
features: multi-cluster-management=false
# The Rancher UI will run on the host port 8443 by default. Set to 0 to disable
# and instead use ingress.enabled=true to route traffic through ingress
hostPort: 8443
# Accessing ingress is disabled by default.
ingress:
enabled: false
# Don't create a default admin password
noDefaultAdmin: true
# The negative value means it will up to that many replicas if there are
# at least that many nodes available. For example, if you have 2 nodes and
# `replicas` is `-3` then 2 replicas will run. Once you add a third node
# a then 3 replicas will run
replicas: -3
# External TLS is assumed
tls: external
A full reference of all parameters in the values.yaml is available in the Rancher repo.
The Rancher UI is running by default on port :8443
. There is no default
admin
user password set. You must run rancherd reset-admin
once to
get an admin
password to login.
By default Multi Cluster Managmement is disables in Rancher. To enable set the following in the rancherd config.yaml
rancherValues:
features: multi-cluster-management=true
rancherd itself doesn't need to be upgraded. It is only ran once per node and then after that provides no value. What you do need to upgrade after the fact is Rancher and Kubernetes.
Rancher is installed as a helm chart following the standard procedure. You can upgrade Rancher with the standard procedure documented at https://rancher.com/docs/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/.
To upgrade Kubernetes you will use Rancher to orchestrate the upgrade. This is a matter of changing
the Kubernetes version on the fleet-local/local
Cluster
in the provisioning.cattle.io/v1
apiVersion. For example
kubectl edit clusters.provisioning.cattle.io -n fleet-local local
apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
name: local
namespace: fleet-local
spec:
# Change to new valid k8s version
kubernetesVersion: v1.21.4+k3s1
You can also use the rancherd upgrade
command on a server
node to automatically do the
above procedure.