Backup & Disaster Recovery
Relevant source files
The following files were used as context for generating this wiki page:
The Backup & Disaster Recovery strategy for swimctl focuses on a decentralized, "configuration-as-code" approach. Instead of traditional monolithic database backups, the system relies on GitHub as the primary source of truth for both its operational logic (Node-RED flows) and its infrastructure definitions (Kubernetes manifests).
This architecture ensures that in the event of hardware failure, such as a corrupted SD card on a Raspberry Pi, the entire system can be reconstituted from remote repositories. The recovery process involves re-provisioning the host, re-installing the k3s cluster, and utilizing init containers to pull the latest logic from version control.
Sources: README.md:1-55, values.yml:85-131
Flow Persistence and Synchronization
Node-RED logic is treated as a Git project rather than local transient data. The system is configured to enable Node-RED projects, allowing flows to be managed via Git. A critical component of the disaster recovery strategy is the automated synchronization between the running instance and a remote GitHub repository.
Initialization and Recovery Flow
When the Node-RED pod starts, an init container named clone-repo executes. This container is responsible for ensuring the environment matches the desired state stored in the swimctl-flows repository. It clears existing data and performs a fresh clone of the specified branch.
The diagram above illustrates the sequence used to recover application state during a cold start or after a disaster.
Sources: values.yml:45-51, values.yml:85-115
Continuous Backup via GitHub Dispatch
To prevent data loss during active development within the Node-RED editor, the system implements an automated backup mechanism via a Git post-commit hook. When a user commits changes in Node-RED, the hook triggers a GitHub Actions workflow in the remote repository.
| Component | Function | Configuration Source |
|---|---|---|
GIT_REPO | Remote source for flow logic | values.yml:91 |
GIT_VERSION | Target branch (default: main) | values.yml:94 |
post-commit hook | Triggers remote GitHub Action on local commit | values.yml:117-130 |
apply-patch.yml | GitHub Action that receives the local changes | values.yml:123 |
Sources: values.yml:91-130
Infrastructure Restoration
The physical and orchestration layers are restored using standardized manifests and the k3sup tool. Disaster recovery for the cluster itself involves three main stages:
1. Host Preparation
The Raspberry Pi must be reconfigured for hardware-level requirements, specifically cgroups for Kubernetes memory management and I2C for peripheral communication.
Sources: README.md:5-18
2. Cluster Re-provisioning
K3s is installed using k3sup, which allows for rapid re-installation and merging of the local kubeconfig, facilitating immediate access to the recovered node.
Sources: README.md:21-32
3. Secret and State Restoration
Because secrets are not stored in the public repository for security reasons, they must be manually recreated during recovery. These secrets contain the credentials necessary for the init containers to interact with GitHub and for the application to connect to MQTT.
| Secret Key | Purpose |
|---|---|
gh_token | Authentication for cloning and dispatching patches |
gh_owner | GitHub username/organization |
gh_repo_name | Target repository for logic storage |
mqtt_password | Credentials for the messaging bus |
Sources: README.md:35-43, values.yml:53-80
Configuration Management
System settings are persisted in Kubernetes ConfigMaps, ensuring that environment-specific configurations like I2C device mappings and Node-RED project settings are restored alongside the application.
This diagram shows how ConfigMaps provide the necessary environment state for system components upon restoration.
Sources: configMaps.yaml:1-50, smarter-device-manager.yaml:70-73
Summary
The swimctl project utilizes a Git-centric backup and disaster recovery model. By externalizing application logic to GitHub and defining infrastructure via Kubernetes manifests, the system achieves a resilient state where the local hardware is effectively stateless. Recovery is achieved through a combination of manual cluster provisioning and automated container initialization that synchronizes the local environment with remote source control.