Skip to main content
Version: Stable

Cluster reference

A Cluster definition includes a kubernetesVersion and a list of machinePools to deploy the cluster to.

For how to select a kubernetesVersion please check our Kubernetes Versions page.

A machinePool is a bundle of configuration with a ObjectReference so the cluster is deployed to those machinePools with the proper roles (etcd, control-plane, worker) with a quantity (how many nodes to deploy from this pool) and some extra configurations (rolling update config, max unhealthy nodes, etc...).

Example
kind: Cluster
apiVersion: provisioning.cattle.io/v1
metadata:
name: ...
namespace: ...
spec:
rkeConfig:
machinePools:
- name: ...
controlPlaneRole: ...
etcdRole: ...
workerRole: ...
quantity: ...
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: ...
- name: ...
controlPlaneRole: ...
etcdRole: ...
workerRole: ...
quantity: ...
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: ...

It's also possible to disable cluster components via the Cluster object in spec.rkeConfig.machineGlobalConfig, for example:

Service Disabling Example
kind: Cluster
apiVersion: provisioning.cattle.io/v1
metadata:
name: ...
namespace: ...
spec:
rkeConfig:
machinePools:
- name: ...
controlPlaneRole: ...
etcdRole: ...
workerRole: ...
quantity: ...
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: ...
machineGlobalConfig:
disable:
- servicelb
- ...

rkeConfig.machinePools

A list of machinePools. A minimum of 1 machinePools is required for the cluster to be deployed to.

machinePools Spec Reference

KeyTypeDefault valueDescription
controlPlaneRoleboolfalseSet machines in this pool as control-plane
etcdRoleboolfalseSet machines in this pool as etcd
workerRoleboolfalseSet machines in this pool as worker
namestringnilName for this pool
quantityintnilNumber of machines to deploy from this pool
unhealthyNodeTimeoutintnilTimeout for unhealthy node health checks
machineConfigRefintObjectReferenceReference to an object used to know what nodes are part of this pool

A minimum of quantity set to one is required for this pool to be used. Basically translates to how many nodes from this pool are going to be setup for this cluster.

Example
kind: Cluster
apiVersion: provisioning.cattle.io/v1
metadata:
name: cluster-example
namespace: example-default
spec:
rkeConfig:
machinePools:
- name: examplePool
controlPlaneRole: true
etcdRole: true
workerRole: false
quantity: 3
unhealthyNodeTimeout: 0s
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: exampleSelector

machineConfigRef Spec Reference

A machineConfigRef is a generic k8s ObjectReference which usually contain a kind name and apiVersion to point to a different object.

In Elemental, we set this to a MachineInventorySelectorTemplate. This allows us to point to more than one object by using the selector.

Example

The example below creates a cluster that uses 2 different machinePool's to set different nodes to control-plane and workers nodes, based on 2 different MachineInventorySelectorTemplate that select their nodes based on a MachineInventory label (location)

warning

The labels for the example are manual set labels, they are not set by Elemental automatically..

For automatic labels generated by Elemental please check the SMBIOS page.

Example of a cluster with more than one machinePool
kind: Cluster
apiVersion: provisioning.cattle.io/v1
metadata:
name: cluster-machinepools
namespace: fleet-default
spec:
rkeConfig:
machinePools:
- name: controlPlanePool
controlPlaneRole: true
etcdRole: true
workerRole: false
quantity: 3
unhealthyNodeTimeout: 0s
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: selectorControlPlanes
- name: workersPool
controlPlaneRole: false
etcdRole: false
workerRole: true
quantity: 1
unhealthyNodeTimeout: 0s
machineConfigRef:
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
name: selectorWorkers
kubernetesVersion: v1.23.7+k3s1
---
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
metadata:
name: selectorControlPlanes
namespace: fleet-default
spec:
template:
spec:
selector:
matchLabels:
location: server-room-1
---
apiVersion: elemental.cattle.io/v1beta1
kind: MachineInventorySelectorTemplate
metadata:
name: selectorWorkers
namespace: fleet-default
spec:
template:
spec:
selector:
matchLabels:
location: server-room-2