Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The infrahub-ops-cli project provides a Go-based toolset for managing Infrahub instances through specialized CLI binaries. It utilizes a split-binary, shared-core architecture where distinct entry points share common internal application logic for operations like backup, restore, task management, and diagnostic collection.
The system supports both Docker Compose and Kubernetes environments. It interacts with deployment backends by shelling out to docker and kubectl CLIs through a unified command executor rather than using native SDKs or client libraries.
Sources: AGENTS.md:7-14, specs/archive/003-collect-tool/plan.md:14-18, dev/README.md:11-13
Core Binary Components
The project builds three specialized binaries from separate entry points in src/cmd/. Each binary leverages the InfrahubOps struct in src/internal/app to perform its specific tasks.
| Binary | Primary Responsibility | Key Commands |
|---|---|---|
infrahub-backup | Data persistence and recovery | create, restore, environment detect |
infrahub-taskmanager | Prefect task manager maintenance | flush flow-runs, flush stale-runs |
infrahub-collect | Troubleshooting diagnostic collection | create (bundle), environment detect |
Sources: AGENTS.md:46-75, specs/archive/003-collect-tool/plan.md:11-14
Shared Logic Structure
The architecture centralizes logic within src/internal/app/ to ensure consistency across binaries. The InfrahubOps struct acts as the main application controller, managing environment detection and command execution.
This diagram illustrates how specialized CLI tools interface with a shared internal application layer to manage various deployment backends and storage.
Sources: AGENTS.md:77-88, specs/004-backup-retention-policy/plan.md:28-32
Storage and Data Flow
The system manages data across local filesystems, S3-compatible object storage, and Plakar repositories. Backups are generated as tar.gz archives containing database dumps (Neo4j and PostgreSQL) and a metadata.json file.
Backup and Restore Flow
- Environment Detection: The tool identifies if Infrahub is running in Docker or Kubernetes.
- Database Dumps: It executes dump commands (e.g.,
neo4j-admin database dumpandpg_dump) via the deployment backend. - Archiving: It packages dumps and metadata into a compressed archive.
- Storage: It saves the archive to the local
BackupDiror uploads it to S3 if configured. - Retention: After a successful backup, it applies the retention policy to prune old archives based on age or count.
Sources: AGENTS.md:89-93, specs/001-k8s-helm-backup/plan.md:16-20, specs/004-backup-retention-policy/plan.md:11-14
Storage Backend Support
| Backend | Implementation Details |
|---|---|
| Local FS | Stores archives in a configurable directory (default ./infrahub_backups). |
| S3 | Uses minio-go/v7 or AWS SDK v2 for bucket operations. |
| Plakar | Uses the kloset library for content-addressable, deduplicated snapshots. |
Sources: specs/001-k8s-helm-backup/plan.md:22-26, specs/004-backup-retention-policy/plan.md:18-22
Collector Framework
The infrahub-collect tool implements a non-fatal, timeout-bounded collector framework. Each collector runs independently to gather logs, diagnostics, and metrics without affecting the workload lifecycle.
The sequence shows the troubleshooting bundle collection process, highlighting the secret masking step and the non-fatal nature of individual collectors.
Sources: specs/archive/003-collect-tool/plan.md:11-13, specs/archive/003-collect-tool/tasks.md:43-62, dev/README.md:14-20
Retention and Selection Logic
The architecture includes a pure selection function for managing backup lifecycles. It applies a union of age-based and count-based rules while enforcing an unconditional "keep-newest" floor to prevent deleting all backups.
Selection Rules
- Max Age: Removes backups older than N days.
- Max Count: Keeps only the N most recent backups.
- Keep-Newest Floor: The single most recent backup is never prunable, regardless of rules.
- Selection Isolation: Each storage location (Local vs. S3) is evaluated independently.
Sources: specs/004-backup-retention-policy/plan.md:11-15, specs/004-backup-retention-policy/tasks.md:24-33
Deployment Architectures
Docker Compose
All tools assume Infrahub is deployed with standard service names like database (Neo4j), task-manager-db (PostgreSQL), and infrahub-server. Operations target specific projects using the --project flag.
Sources: AGENTS.md:111-118
Kubernetes
The system supports Kubernetes through a Helm subchart that manages CronJobs for backups and Jobs for restores. The KubernetesBackend uses kubectl to discover pods and execute commands within containers.
Sources: specs/001-k8s-helm-backup/plan.md:92-120, specs/archive/003-collect-tool/plan.md:58-62
Technical Summary
The infrahub-ops-cli architecture prioritizes operational safety and tool portability. By utilizing a shared internal core and shelling out to standard platform CLIs, the project maintains environment parity and minimizes native library dependencies. The split-binary approach allows for focused tool functionality while reusing complex logic for database interactions, storage management, and data retention.