Kubernetes (K3s) Edge Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The swimctl project leverages a Kubernetes-based edge architecture, specifically utilizing K3s on Raspberry Pi hardware to automate swimming pool controls. This architecture integrates containerized workloads with physical hardware interfaces, such as I2C, to bridge the gap between high-level automation logic (Node-RED) and low-level sensor/actuator hardware.
The system is designed for local reliability and ease of deployment using k3sup and Helm. It utilizes specialized device management to expose hardware peripherals to the container orchestration layer and incorporates mDNS for local network service discovery.
Sources: README.md:1-40, values.yml:1-15
Hardware Integration and Device Management
A critical component of this edge architecture is the ability of containerized applications to access physical hardware on the Raspberry Pi host. The project employs the Smarter Device Manager to manage and expose I2C interfaces as Kubernetes resources.
I2C Resource Allocation
The architecture defines specific I2C devices (i2c-1, i2c-20, i2c-21) as allocatable resources. These are requested by the application containers to ensure exclusive access to the hardware bus required for pool control operations.
Sources: values.yml:8-16, configMaps.yaml:8-10
Smarter Device Manager
The smarter-device-manager runs as a DaemonSet within the device-manager namespace. It monitors the host's /dev and /sys directories to identify and expose hardware devices to the Kubelet.
Sources: smarter-device-manager.yaml:1-60, 00-namespaces.yaml:1-6
The following diagram illustrates how host hardware is mapped into the Kubernetes ecosystem:
Description: The flow of hardware device registration and consumption within the cluster.
Sources: smarter-device-manager.yaml:45-70, values.yml:8-15, configMaps.yaml:7-10
Workload Automation and State Management
The primary workload is a Node-RED instance that executes the "swimctl" logic. This workload is managed through a Helm chart and features automated lifecycle management for flow configurations.
Flow Lifecycle and Git Integration
An initContainer is used to synchronize automation flows from a remote GitHub repository (swimctl-flows). This ensures that the edge device always starts with the latest version of the control logic. Additionally, a post-commit hook is automatically configured within the container to dispatch updates back to GitHub when local changes are made.
Sources: values.yml:79-119
| Component | Role | Configuration Source |
|---|---|---|
| Node-RED | Execution Engine | ghcr.io/bgshacklett/swimctl |
| initContainer | Flow Synchronizer | alpine/git |
| Settings | Configuration | node-red-settings ConfigMap |
| Projects | Project Metadata | node-red-projects-settings ConfigMap |
| Sources: values.yml:1-5, values.yml:79-85, configMaps.yaml:13-39 |
Networking and Connectivity
The architecture uses an Ingress controller to expose the swimctl.local hostname. To support local discovery without a central DNS server, an external-mdns service is deployed.
Description: Sequence of service discovery and request routing via mDNS and Ingress.
Sources: external-mdns.yaml:1-60, values.yml:68-75
Security and System Configuration
Deploying K3s on a Raspberry Pi for edge automation requires specific host-level and cluster-level security configurations.
Host Preparation
Before K3s installation, the Raspberry Pi must be configured to enable memory cgroups and the I2C interface via raspi-config.
Sources: README.md:10-23
Pod Security and Permissions
The Node-RED pod runs with specific Security Contexts to allow it to interact with the I2C hardware group (GID 994).
Sources: values.yml:18-24
| Parameter | Value | Purpose |
|---|---|---|
runAsUser | 1000 | Standard non-root user |
supplementalGroups | [994] | Access to host I2C devices |
deploymentStrategy | Recreate | Prevents concurrent hardware access during updates |
| Sources: values.yml:18-28 |
Secret Management
Sensitive information, including GitHub tokens and MQTT passwords, is managed via Kubernetes Secrets created during the installation process. These are injected into the application environment via valueFrom references.
Sources: README.md:46-53, values.yml:42-65
Conclusion
The Kubernetes (K3s) Edge Architecture for swimctl provides a robust, version-controlled, and hardware-aware platform for pool automation. By combining Smarter Device Manager for I2C access, Node-RED for logic execution, and mDNS for local discovery, the system achieves a "cloud-native" approach to local hardware control.
Sources: README.md:1-5, values.yml:1-15, external-mdns.yaml:1-5