Skip to content

Cluster node template🔗︎

The node template section of the cluster configuration defines the properties of all nodes in the cluster. This includes the properties of the operating system (OS), DNS, and the virtual machine user.

Configuration🔗︎

Virtual machine user🔗︎

v2.0.0   Default: k8s

The user property defines the name of the user created on each virtual machine. This user is used to access the virtual machines during cluster configuration. If you omit the user property, a user named k8s is created on all virtual machines. You can also use this user later to access each virtual machine via SSH.

cluster:
  nodeTemplate:
    user: kubitect

Operating system (OS)🔗︎

OS distribution🔗︎

v2.1.0   Default: ubuntu22

The operating system for virtual machines can be specified in the node template. By default, the Ubuntu distribution is installed on all virtual machines.

You can select a desired distribution by setting the os.distro property.

cluster:
  nodeTemplate:
    os:
      distro: debian12 # (1)!
  1. By default, ubuntu22 is used.

The available operating system distribution presets are:

  • ubuntu20 - Latest Ubuntu 20.04 (Focal) release.
  • ubuntu22 - Latest Ubuntu 22.04 (Jammy) release. (default)
  • debian11 - Latest Debian 11 (Bullseye) release.
  • debian12 - Latest Debian 12 (Bookworm) release.
  • centos9 - Latest CentOS Stream 9 release.
  • rocky9 - Latest Rocky 9 release.

Important

Rocky Linux and CentOS Stream both require the x86-64-v2 instruction set to run. If the CPU mode property is not set to host-passthrough, host-model, or maximum, the virtual machine may not be able to boot properly.

Known issues

CentOS Stream images already include the qemu-guest-agent package, which reports IP addresses of the virtual machines before they are leased from a DHCP server. This can cause issues during infrastructure provisioning if the virtual machines are not configured with static IP addresses.

Where are images downloaded from?

Images are sourced from the official cloud image repository for the corresponding Linux distribution.

OS source🔗︎

v2.1.0

If the presets do not meet your needs, you can use a custom Ubuntu or Debian image by specifying the image source. The source of an image can be either a local path on your system or a URL pointing to the image download.

cluster:
  nodeTemplate:
    os:
      distro: ubuntu20
      source: https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img

Network interface🔗︎

v2.1.0

Generally, this setting does not have to be set, as Kubitect will correctly evaluate the network interface name to be used on each virtual machine.

If you want to instruct Kubitect to use a specific network interface on the virtual machine, you can set its name using the os.networkInterface property.

cluster:
  nodeTemplate:
    os:
      networkInterface: ens3

Custom DNS list🔗︎

v2.1.0

The configuration of Domain Name Servers (DNS) in the node template allows for customizing the DNS resolution of all virtual machines in the cluster. By default, the DNS list contains only the network gateway.

To add custom DNS servers, specify them using the dns property in the node template.

cluster:
  nodeTemplate:
    dns: # (1)!
      - 1.1.1.1
      - 1.0.0.1
  1. IP addresses 1.1.1.1 and 1.0.0.1 represent CloudFlare's primary and secondary public DNS resolvers, respectively.

CPU mode🔗︎

v2.2.0   Default: custom

The cpuMode property in the node template can be used to configure a guest CPU to closely resemble the host CPU.

cluster:
  nodeTemplate:
    cpuMode: host-passthrough

Currently, there are several CPU modes available:

  • custom (default)
  • host-model
  • host-passthrough
  • maximum

In short, the host-model mode uses the same CPU model as the host, while the host-passthrough mode provides full CPU feature set to the guest virtual machine, but may impact its live migration. The maximum mode selects the CPU with the most available features. For a more detailed explanation of the available CPU modes and their usage, please refer to the libvirt documentation.

Tip

The host-model and host-passthrough modes makes sense only when a virtual machine can run directly on the host CPUs (e.g. virtual machines of type kvm). The actual host CPU is irrelevant for virtual machines with emulated virtual CPUs (e.g. virtul machines of type qemu).

Update on boot🔗︎

v2.2.0   Default: true

By default, Kubitect updates all virtual machine packages on boot. To disable this behavior, set updateOnBoot to false.

cluster:
  nodeTemplate:
    updateOnBoot: false

SSH options🔗︎

Custom SSH certificate🔗︎

v2.0.0

Kubitect automatically generates SSH certificates before deploying the cluster to ensure secure communication between nodes. The generated certificates can be found in the config/.ssh/ directory inside the cluster directory.

If you prefer to use a custom SSH certificate, you can specify the local path to the private key. Note that the public key must also be present in the same directory with the .pub suffix.

cluster:
  nodeTemplate:
    ssh:
      privateKeyPath: "~/.ssh/id_rsa_test"

Important

SSH certificates must be passwordless, otherwise Kubespray will fail to configure the cluster.

Adding nodes to the known hosts🔗︎

v2.0.0   Default: false

Kubitect allows you to add all created virtual machines to SSH known hosts and remove them once the cluster is destroyed. To enable this behavior, set the addToKnownHosts property to true.

cluster:
  nodeTemplate:
    ssh:
      addToKnownHosts: true