k3ssleipnir 0.10.0

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

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.

[!NOTE] There are some limitations in the declarative approach but these will be discussed in the remainder of the guide.

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

[!IMPORTANT] Keep in mind this is a personal project that I am just happy to share. Therefore, please use issues for support (for now) and keep in mind that the current codebase was hacked together in a couple of days, so it is not optimized, neither pretty... you have been warned :-)

Minimum Requirements

[!IMPORTANT] Python version 3.12 or higher is required. Mac OS has a default version lower than this which my cause the error ModuleNotFoundError: No module named 'exceptiongroup' (see issue 21). On Mac, use a tool like homebrew to install the latest version of Python.

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.

[!IMPORTANT] You may need to test the functioning of your sudo configuration first to ensure everything is working as expected. A common problem is that the rules may be overridden by commands after this customization, and a common fix is to ensure that these configuration additions are added right at the end of the configuration file.

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

[!NOTE] To receive notification of new releases, subscribe to to RSS Notifications

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

[!NOTE] The full specification is documented in the SPEC.md file.

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.