Restoring Backups
Relevant source files
The following files were used as context for generating this wiki page:
Restoring backups in Infrahub is the process of recovering Neo4j and PostgreSQL databases along with associated artifacts from stored archives. The system supports manual restoration of specific files and automated restoration of the most recent backup from local or S3-compatible storage.
Sources: AGENTS.md, specs/005-restore-latest-backup/spec.md:144-147
Restore Mechanisms
The project provides two primary methods for initiating a restore: naming a specific archive file or using the --latest flag to automatically select the newest available backup. The restoration process validates metadata, handles version compatibility, and manages container states to ensure data integrity.
Sources: AGENTS.md, specs/005-restore-latest-backup/spec.md:144-147
Manual Restore
Users specify a path to a .tar.gz archive. For S3-compatible storage, the system accepts the s3://bucket/key URI format. The tool downloads the archive, validates its contents against a metadata.json file, and executes the restoration logic.
Sources: specs/001-k8s-helm-backup/plan.md, specs/005-restore-latest-backup/spec.md:52-53
Latest Backup Restore
The restore --latest command automatically identifies the most recent backup within a storage pool. It ranks archives based on filename-embedded timestamps, using a name-descending tiebreak to resolve identical timestamps.
Sources: specs/005-restore-latest-backup/spec.md:113-115, src/internal/app/restore_latest.go:15-18
The diagram shows the logic flow for selecting between manual path restoration and automated latest archive resolution.
Sources: specs/005-restore-latest-backup/spec.md:104-129, src/internal/app/restore_latest.go:15-35
Component Architecture
The restoration logic is split between the CLI entry point and the core application logic to maintain a shared-core architecture.
| Component | Responsibility | Relevant Files |
|---|---|---|
| Cobra CLI | Registers flags (--latest, --s3), validates mutually exclusive arguments, and handles user feedback. | src/cmd/infrahub-backup/main.go |
| Orchestrator | RestoreLatestBackup manages the high-level flow, including fail-fast gates for encrypted backups. | src/internal/app/restore_latest.go |
| Selection Core | resolveLatestBackup performs the ranking of archives in a given storageLocation. | src/internal/app/restore_latest.go |
| Execution Core | RestoreBackup performs the actual data restoration, container management, and checksum verification. | src/internal/app/backup.go |
Sources: specs/005-restore-latest-backup/plan.md, specs/005-restore-latest-backup/opsmill-implement-report.md:Chunk 2
Restore Process Flow
When a restore is initiated, the system follows a specific sequence to ensure operational safety.
- Validation: The system ensures
--latestand positional arguments are not used together. - Selection: If
--latestis set, the system lists the storage pool (Local or S3) and identifies the newest archive. - Fail-Fast Security: If the newest archive is encrypted and no
--decrypt-keyis provided, the process terminates immediately before any destructive actions occur. - Staging (S3 only): The system downloads the S3 object to a collision-proof temporary path (
restore-latest-*.download) to prevent overwriting existing local backups. - Execution: The system stops relevant Infrahub containers, restores database dumps, and restarts the containers.
Sources: specs/005-restore-latest-backup/spec.md:118-121, specs/005-restore-latest-backup/opsmill-implement-report.md:Chunk 3, src/internal/app/restore_latest.go:100-110
Sequence diagram illustrating the remote restoration flow using the --latest flag with S3 storage.
Sources: specs/005-restore-latest-backup/opsmill-implement-report.md:Chunk 2 & 3, src/internal/app/restore_latest.go:88-100
Configuration and Flags
Restore operations are configured via CLI flags that control the source and behavior of the process.
| Flag | Type | Description |
|---|---|---|
--latest | Boolean | Automatically selects and restores the newest backup archive in the pool. |
--s3 | Boolean | Directs the system to use the S3 storage pool instead of local storage. |
--decrypt-key | String | Path to the key used for decrypting encrypted .enc archives. |
--exclude-taskmanager | Boolean | Skips the restoration of the Task Manager (PostgreSQL) database. |
--migrate-format | Boolean | Applies format migrations during the restoration process. |
--force | Boolean | Bypasses certain safety checks during restoration. |
Sources: specs/005-restore-latest-backup/spec.md:104-129, specs/005-restore-latest-backup/plan.md
Kubernetes Restoration
In Kubernetes environments, restoration is typically handled via a Job. The infrahub-backup container uses a ServiceAccount with RBAC permissions to interact with pods and manage application states.
- Role Permissions: Includes
listandgetfor pods, andcreateforpods/execto run database commands inside application containers. - Environment Variables: Uses
INFRAHUB_K8S_NAMESPACEfor service discovery and S3 variables (e.g.,INFRAHUB_S3_BUCKET) for remote artifact retrieval.
Sources: specs/001-k8s-helm-backup/spec.md:95-103, specs/001-k8s-helm-backup/plan.md:Phase 2
Summary
Restoring backups provides critical disaster recovery and environment synchronization capabilities for Infrahub. By utilizing the --latest flag, operators and automated systems can restore the most recent state from either local or S3 storage without manual filename tracking. The system enforces strict validation and fail-fast gates to protect data integrity and ensure operational safety.