Skip to content

Single node with K3S

Run kolab with all components on a single host.

This deployment consists of a single vm, and all workloads are executed in k3s.

K3s will use the embedded sqlite store for this deployment.

This is the simplest deployment mode and suitable if the workload load fits on a single system, and downtime for maintenance or failure is acceptable.

Storage

Local disk storage is consumed via the local-path-provisioner storage provider.

Failure modes

There is no redundancy. Some durability guarantees can be achieved by using RAID disks.

Deployment method

The deployment is managed by:

  • Ansible playbooks (configured via inventory.yaml) to manage the VM.
  • A helm chart (configured via values.yaml) to manage the kolab deployment running on k3s.

The following systems are assumed:

  • Control host: A workstation with access to the hypervisor is used to manage the environment.
  • Hypervisor: A hypervisor to run the Kolab VM

The ansible playbooks are executed from the control host. It is required that passwordless ssh logins are configured (for the user executing the ansible scripts), from the control host to the hypervisor for the virtual machine setup.

  • First an inventory.yaml file must be created to describe the deployment.
  • An initial run of the ansible playbook will provision the vms on the hypervisors, setup k3s, and deploy kolab on k3s.
  • An initial values.yaml will be generated from a template next to the inventory file.

Going forward the inventory.yaml and values.yaml files should be added to version control. Changes to the environment can be applied by either executing the full ansible script, or by only redeploying the helm chart (configured via values.yaml)

Setup Instructions

Please also see About Kolab on Kubernetes Deployments

Executed from the control host.

  • Create a directory where you intend to manage the kolab installation from
  • Download the latest release here: https://mirror.apheleia-it.ch/pub/kolab-kubernetes-latest.tar.gz
  • Extract the tarball.tar xf kolab-kubernetes-latest.tar.gz
  • Copy deployments/k3s-single-node/inventory.example.yaml to inventory.yaml
  • Adjust the new inventory.yaml, by default it will deploy everything on localhost
  • Run the ansible provisioning process: ansible-playbook -v -i inventory.yaml -D deployments/k3s-single-node/ansible/playbook.yaml
  • Navigate to the configured url (if dns is already, prepared, otherwise via /etc/hosts entry)
  • Login with the admin@YOURDOMAIN user
  • Future changes can be applied via: ./kolabctl apply

Installing on a pre-existing vm (bypass vm provisioning)

It is possible to either manually provision a Virtual Machine or connect to an existing system to install Kolab. Please note that the ansible scripts assume the environment as prepared by the kvm ansible role (as part of https://mirror.apheleia-it.ch/pub/kolab-kubernetes-latest.tar.gz).

As the base image for manual installation, the following image is recommended: https://mirror.apheleia-it.ch/pub/kolab-minimal-0.1.qcow2 (default login root/kolab)

Once the VM is available, follow the above instructions with the following adjustments:

  • When adjusting the new inventory.yaml:
    • Disable vm provisioning by setting provision_vm: false
    • Set the ip to connect to your vm (only necessary if the hostname is not resolved to the correct ip on the control host):
      • Set ansible_host: ip of your vm

Updating

To update the VM image run the same ansible script as for installing Kolab:

ansible-playbook -v -i inventory.yaml -D deployments/k3s-single-node/ansible/playbook.yaml

Please note that this will still respect pinned image versions in values.yaml, so you will have to update those manually.

Backup & Restore

One approach is to just snapshot the entire VM, which will include all user data.

To back-up only the data parts of the VM:

  • k3s database: /var/lib/rancher/k3s/server/db/
  • k3s token: /var/lib/rancher/k3s/server/token
  • application payloads: /var/lib/rancher/k3s/storage/

Please note that consistency of the snapshot can only be guaranteed by stopping all workloads first via: k3s-killall.sh

To restore:

  • Either restore a VM or install one per installation guide
  • Make sure k3s and all workloads are stopped by executing: k3s-killall.sh
  • Restore the above backed-up directories
  • Start k3s again: systemctl start k3s