Secrets Management
Relevant source files
The following files were used as context for generating this wiki page:
Secrets Management in the swimctl project provides a secure mechanism for handling sensitive configuration data required for swimming pool automation. This system primarily facilitates the integration between the local Kubernetes cluster (k3s running on Raspberry Pi) and external services such as GitHub and MQTT brokers. By leveraging Kubernetes Secrets, the project ensures that authentication tokens and passwords are not hardcoded in the deployment manifests or version-controlled files.
The scope of secrets management covers the provisioning of a generic secret named swimctl, which is then consumed by the primary application deployment—a Node-RED instance—via environment variables. These secrets are critical for the automated synchronization of flows from GitHub and the communication with local or remote MQTT messaging systems.
Secret Provisioning and Lifecycle
Secrets are managed outside of the static YAML manifests to prevent sensitive data exposure in the repository. The project utilizes the kubectl CLI to create a generic secret named swimctl.
Secret Creation
The administrator is responsible for executing a manual command to populate the cluster with the necessary credentials. This process captures GitHub repository details and automation passwords.
kubectl --context "${hostname}" create secret generic swimctl \
--from-literal=gh_token="${GH_TOKEN}" \
--from-literal=gh_owner="${GH_REPO_OWNER}" \
--from-literal=gh_repo_name="${GH_REPO_NAME}" \
--from-literal=mqtt_password="${MQTT_PASSWORD}"
Sources: README.md:38-44
Data Flow Diagram
The following diagram illustrates how secrets flow from the manual creation step into the running application pod.
The diagram shows the transition of sensitive data from the user to the Kubernetes Secret store and its subsequent injection into the application lifecycle. Sources: README.md:38-44, values.yml:33-66
Secret Consumption and Usage
The swimctl deployment consumes these secrets primarily through the values.yml configuration, mapping secret keys to specific environment variables within the application pods.
Environment Variable Mapping
The application maps four specific keys from the swimctl secret to environment variables used for GitHub automation and MQTT connectivity.
| Environment Variable | Secret Key | Description |
|---|---|---|
GITHUB_TOKEN_FLOWS | gh_token | Personal access token for GitHub API authentication. |
GITHUB_OWNER_FLOWS | gh_owner | The owner/organization of the flows repository. |
GITHUB_REPO_NAME_FLOWS | gh_repo_name | The name of the GitHub repository containing flows. |
MQTT_PASSWORD | mqtt_password | Password for the MQTT broker authentication. |
Sources: values.yml:41-66
Git Post-Commit Automation
One of the most critical uses of these secrets is within the initContainers. A post-commit hook is dynamically generated to trigger GitHub Actions when changes occur. The GITHUB_TOKEN_FLOWS is specifically used to authorize a POST request to the GitHub Repository Dispatches API.
url="https://api.github.com/repos/$GITHUB_OWNER_FLOWS/$GITHUB_REPO_NAME_FLOWS/actions/workflows/apply-patch.yml/dispatches"
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: Bearer $GITHUB_TOKEN_FLOWS" \
"$url" \
-d "{\"ref\":\"main\", \"inputs\": {\"patchContent\": \"$patch_content\"}}"
Sources: values.yml:115-121
Security Context and Permissions
While secrets handle data confidentiality, the project also implements security contexts to manage access at the process and filesystem levels.
Pod Security Configuration
The application runs under a specific non-root UID and GID to limit the impact of potential vulnerabilities.
- User/Group ID: 1000 (values.yml:23-24)
- FSGroup: 1000 for volume permissions (values.yml:25)
- Supplemental Groups: Group
994is added to provide the container with access to I2C hardware devices (values.yml:26-28)
RBAC and Service Accounts
For internal cluster operations, the external-mdns component utilizes a dedicated ServiceAccount and ClusterRole to interact with Kubernetes APIs.
Sources: external-mdns.yaml:1-35
Summary
Secrets Management in swimctl is centered on the manual provisioning of a single swimctl Kubernetes Secret. This secret acts as the central repository for credentials that enable secure GitHub integration and MQTT communication. By decoupling these credentials from the Helm charts and manifests, the architecture maintains a secure posture while facilitating automated CI/CD-like workflows for Node-RED flows on edge devices.
Sources: README.md, values.yml, configMaps.yaml, external-mdns.yaml, smarter-device-manager.yaml, 00-namespaces.yaml