Pool Automation Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Swimctl is a swimming pool automation controller system deployed on a Kubernetes (k3s) cluster, typically running on Raspberry Pi hardware. The system leverages Node-RED to manage automation logic through "flows," which are synchronized with external Git repositories to ensure version control and continuous deployment of pool management logic.
The automation architecture integrates hardware-level device management for I2C peripherals with high-level workflow orchestration. It uses a combination of Kubernetes ConfigMaps, Secrets, and specialized device managers to expose physical hardware to the Node-RED environment, allowing for complex automation tasks such as chemical monitoring or pump control.
Sources: README.md:1-5, values.yml:1-10
Project Orchestration and Synchronization
The core of the pool automation logic resides in a Node-RED project titled swimctl-flows. This project is managed as a Git repository, allowing for seamless updates and versioning of the automation logic.
Automated Flow Synchronization
Upon container initialization, an initContainer clones the workflow repository from GitHub. It also configures a post-commit hook that automatically triggers a GitHub Actions workflow whenever changes are committed within the Node-RED environment. This ensures that the physical controller and the remote repository remain in sync.
The synchronization mechanism utilizes environment variables for authentication and target identification, sourced from Kubernetes secrets.
Sources: values.yml:45-55, values.yml:110-150
Git Synchronization Parameters
| Parameter | Environment Variable | Source Secret Key | Description |
|---|---|---|---|
| GitHub Token | GITHUB_TOKEN_FLOWS | gh_token | Personal access token for API authentication |
| Repository Owner | GITHUB_OWNER_FLOWS | gh_owner | The GitHub user or organization owning the flows |
| Repository Name | GITHUB_REPO_NAME_FLOWS | gh_repo_name | The specific repository containing the flows |
| Active Project | NODE_RED_ACTIVE_PROJECT | N/A | Hardcoded to swimctl-flows |
Sources: values.yml:58-85, configMaps.yaml:37-45
Hardware Integration and Device Management
For automation workflows to interact with physical pool hardware (e.g., sensors or relays), the system utilizes smarter-device-manager to expose I2C buses to the Kubernetes pods.
I2C Resource Allocation
The automation environment requests specific I2C devices as resources. These devices are mapped from the host Raspberry Pi into the container filesystem.
The following resources are explicitly defined in the deployment configuration:
smarter-devices/i2c-1smarter-devices/i2c-20smarter-devices/i2c-21
Sources: values.yml:12-25, smarter-device-manager.yaml:1-20, configMaps.yaml:1-10
Security and Permissions
To allow the Node-RED process to interact with hardware, the pod runs with specific security contexts. It utilizes a supplemental group ID (994) to grant the user permissions to access the I2C group on the host.
Sources: values.yml:28-38
Network Services and Discovery
Automation workflows are accessible via local network addresses through an mDNS (Multicast DNS) implementation. This allows the controller to be reached at swimctl.local without a static IP or central DNS server.
The external-mdns service monitors Kubernetes Ingress resources and services to broadcast their hostnames on the local network.
Sources: values.yml:88-95, external-mdns.yaml:45-70
Configuration Management
The system uses Kubernetes ConfigMaps to inject Node-RED settings and project configurations. This allows the behavior of the automation engine to be modified without rebuilding the container image.
Node-RED Settings Injection
A custom settings.js is merged with default Node-RED settings to enable the projects feature and set the active project to swimctl-flows.
Sources: configMaps.yaml:15-30
Project Configuration
The project's metadata, including credential handling, is defined in a JSON configuration mounted as a volume.
{
"projects": {
"swimctl-flows": {
"credentialSecret": false
}
},
"activeProject": "swimctl-flows"
}
Sources: configMaps.yaml:35-45, values.yml:102-108
Summary
The Pool Automation Workflows in swimctl provide a robust framework for managing pool hardware via Node-RED. By integrating I2C device management directly into the Kubernetes orchestration layer and implementing a Git-based synchronization strategy, the system ensures that automation logic is both hardware-aware and version-controlled. Local discovery via mDNS ensures that the automation interface remains accessible in typical residential network environments.