Installing K3s with K3sup
Relevant source files
The following files were used as context for generating this wiki page:
The swimctl project utilizes K3s as its container orchestration platform to manage swimming pool automation components. The installation process leverages k3sup (pronounced "ketchup") to automate the deployment of K3s onto hardware such as a Raspberry Pi. This approach ensures a lightweight Kubernetes environment suitable for edge computing and IoT device management.
The installation workflow involves preparing the target hardware, executing the K3s bootstrap via k3sup, and subsequently configuring the cluster with necessary secrets and specialized device managers. This infrastructure supports various services including Node-RED for logic flows and specialized device drivers for I2C communication.
Sources: README.md:1-25, values.yml:1-10
Hardware Preparation
Before installing K3s, the target Raspberry Pi must be configured to support containerized workloads and the specific hardware interfaces required by swimctl.
Cgroups and I2C Configuration
K3s requires memory cgroups to be enabled in the Linux kernel for proper resource limiting. Additionally, since the project interacts with hardware sensors, I2C must be enabled on the host system.
- Cgroups: The
/boot/firmware/cmdline.txtfile is modified to includecgroup_memory=1andcgroup_enable=memory. - I2C: The
raspi-configutility is used to enable the I2C interface.
Sources: README.md:8-22
The diagram shows the sequential steps required to prepare a Raspberry Pi host before K3s installation.
Sources: README.md:8-22
K3s Installation via k3sup
K3s is installed from a remote workstation using the k3sup tool. This process establishes an SSH connection to the Pi and automates the K3s binary installation and cluster initialization.
Execution Command
The installation uses the following parameters:
- Host: The IP or hostname of the Raspberry Pi.
- User: Default user
pi. - Merge: Merges the new cluster configuration into the local
~/.kube/config.
k3sup install \
--host "${hostname}" \
--user pi \
--context "${hostname}" \
--merge \
--local-path ~/.kube/config
Sources: README.md:28-39
Post-Installation Configuration
Once the cluster is running, several foundational components must be configured to support the swimctl application.
Kubernetes Secrets
The application requires sensitive credentials for GitHub and MQTT communications. These are stored as generic Kubernetes secrets.
| Secret Key | Description | Derived From |
|---|---|---|
gh_token | GitHub Personal Access Token | ${GH_TOKEN} |
gh_owner | GitHub Repository Owner | ${GH_REPO_OWNER} |
gh_repo_name | GitHub Repository Name | ${GH_REPO_NAME} |
mqtt_password | Password for MQTT broker | ${MQTT_PASSWORD} |
Sources: README.md:42-49, values.yml:40-70
Namespace and Device Management
The project uses dedicated namespaces and device managers to handle hardware access.
- Namespaces: A
device-managernamespace is created for hardware-related services. - Smarter Device Manager: A DaemonSet that exposes host I2C devices (
/dev/i2c-*) to containers. It uses a ConfigMap to define device matching patterns (e.g.,^i2c-[0-9]+$). - External mDNS: A deployment in the
kube-systemnamespace that allows service discovery via mDNS for ingresses and services.
Sources: 00-namespaces.yaml:1-6, smarter-device-manager.yaml:1-30, configMaps.yaml:1-9, external-mdns.yaml:1-15
Data Flow for Hardware Access
This diagram illustrates how the Smarter Device Manager facilitates hardware access for the application pods.
Sources: smarter-device-manager.yaml:37-65, values.yml:10-20
Application Deployment
After the infrastructure is ready, the swimctl application is deployed using Helm and static manifests.
Static Manifests and Helm Charts
- Static Manifests: Applied using
kubectl apply -f ., which includes configurations forexternal-mdns,configMaps, anddevice-manager. - Node-RED: Deployed via Helm using an OCI chart from
ghcr.io/schwarzit/charts/node-red.
Node-RED Configuration
The Node-RED deployment is heavily customized via values.yml:
- Resources: Specifically requests I2C devices managed by the Smarter Device Manager (
i2c-1,i2c-20,i2c-21). - Security: Runs as UID/GID 1000 and requires membership in the I2C group (GID 994).
- Initialization: An init container clones the
swimctl-flowsrepository and sets up apost-commithook to trigger GitHub Actions for flow updates.
Sources: README.md:52-65, values.yml:13-30, values.yml:85-115, configMaps.yaml:12-40
Summary
Installing K3s with k3sup for the swimctl project provides a robust, containerized environment for pool automation. By combining k3sup for rapid deployment, smarter-device-manager for hardware interfacing, and external-mdns for local discovery, the system achieves a balance between standard Kubernetes orchestration and specialized IoT requirements.
Sources: README.md:1-65