K3sSleipnir - Deploying K3s based Platforms

Named after the workhorse SSCV Sleipnir. The name itself is from Norse mythology.

A Python based helper to setup a K3s based clusters using declarative configuration.

Configuration is done via YAML file(s) that describe your desired end-state of your homelab k3s cluster.

Features:

• Support for installing a k3s single node cluster on a remote server
• Support for installing a k3s multi node cluster on a remote servers
• Sensitive data (secrets) can be pulled from AWS Secrets Manager
• The YAML format follows a similar format to standard Kubernetes YAML files and should therefore be very familiar
• Several clusters can be defined in the same configuration file - ideal to test scenarios with multiple running clusters
• Support for cloning Git repositories to reference additional files/manifests
• Combine one or more cluster configuration for kubectl into a single file. Can also merge configuration with an existing file.
• Execute additional commands post cluster provisioning.

Future work:

• Should there be interest, more public cloud providers and services can be supported for secrets management and DNS
• Potentially support declarative definitions of public cloud based virtual machines on which to install and run k3s

Minimum Requirements

Assuming each server conforms to the official k3s requirements, also take note of the following:

• Each server must have an SSH server running
• Each server must have some basic packages installed, including:
  • sudo (with visudo)
  • curl
  • podman or docker to execute scripts post installation (also on the system running the homelab command)

For convenience, it is highly recommended to use SSH keys for password less authentication.

Assuming each server has a user called k3s, add the following to the sudoers file:

k3s ALL=(ALL) NOPASSWD: /usr/local/bin/k3s-uninstall.sh
k3s ALL=(ALL) NOPASSWD: /tmp/k3s_install.sh
k3s ALL=(ALL) NOPASSWD: /tmp/web-forward-into-k3s.sh
k3s ALL=(ALL) NOPASSWD: /usr/local/bin/k3s-agent-uninstall.sh

Executing commands on the remote servers requires an SSH private key available on the system that will run the utility.

Installing the Provisioning script

Install using PIP

It is highly recommended to use a Python virtual environment.

For installation using pip, run:

pip install k3ssleipnir

For usage instructions, run:

homelab --help

Usage from Cloning this Repository

Clone the repository and change into the project root.

Run the following:

# Use a Python virtual environment
python3 -m venv venv
. venv/bin/activate
pip3 install --upgrade -r requirements.txt

# Run the tool
cd src
python3 -m homelab.homelabctl --help

# Create a convenient alias:
export SRC="${PWD}"
alias homelab="cd ${SRC} && python3 -m k3ssleipnir.homelabctl "

Quick Start

At it's most basic, a cluster needs at least one server in order to deploy K3s on a single node.

The most minimal configuration is therefore something like the following which will install K3s as a single node cluster on the defined server:

---
apiVersion: v1
kind: Server
metadata:
  name: my-server
spec:
  address: 10.0.0.1
  credentials:
    credentialsType: private-key
    value: /path/to/private-key
    username: k3s
---
apiVersion: v1
kind: K3sCluster
metadata:
  name: my-cluster
spec:
  tasks:
    - cleanupPreviousClusterDeployment
    - installK3s
  servers:
    - serverName: my-server
  kubectlConfiguration:
    targetKubeConfig: /home/user/homelab_clusters.yaml

Each time the command homelab apply -f /home/user/my-homelab.yaml is run, any existing deployment of K3s on my-server will be removed and a new installation will be done.

As a final step, the configuration file /home/user/homelab_clusters.yaml will created, if it does not yet exist. If the file does exist and contains a previous definition of the deployment, the configuration will be updated. If the file exists with configurations of other clusters, the configuration of the new cluster will be added or updated, depending if it already exists or not.

See the examples/ directory for some additional examples.