Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
infrahub-ops-cli is a Go-based toolset designed for the management, maintenance, and diagnostics of Infrahub instances. The project provides specialized command-line interface (CLI) tools that share a common internal logic to handle operations across different deployment environments, including Docker Compose and Kubernetes.
Sources: AGENTS.md:7-13, specs/archive/003-collect-tool/plan.md:7-12
The project architecture utilizes a split-binary design, providing three primary tools: infrahub-backup for data protection, infrahub-taskmanager for maintenance of task execution environments, and infrahub-collect for generating troubleshooting bundles.
Sources: AGENTS.md:7-13, specs/archive/003-collect-tool/plan.md:7-12
Core Binaries
The project builds three distinct binaries from a shared codebase to provide focused functionality for operators.
| Binary | Primary Purpose | Key Operations |
|---|---|---|
infrahub-backup | Data protection and environment detection | Create/restore backups, environment list/detect |
infrahub-taskmanager | Prefect maintenance operations | Flush flow runs, cancel stale runs |
infrahub-collect | Read-only diagnostic bundle collection | Log gathering, metrics, diagnostics, masking |
Sources: AGENTS.md:15-21, AGENTS.md:120-136
Shared Architecture and Logic
All three tools share core application logic located in src/internal/app. The InfrahubOps controller serves as the central orchestrator for Docker project discovery, Kubernetes pod detection, and command execution.
Sources: AGENTS.md:138-145, specs/archive/003-collect-tool/plan.md:10-14
The following diagram illustrates how the specialized CLI entry points interact with the shared internal core logic:
The diagram shows the split-binary architecture where multiple commands utilize a unified internal application controller.
Sources: AGENTS.md:120-150, specs/archive/003-collect-tool/plan.md:10-14
System Capabilities
Backup and Restore
The system performs consistent backups of the Infrahub data stack, specifically targeting Neo4j (database) and PostgreSQL (task-manager-db). Backups are generated as tar.gz archives containing database dumps and a metadata.json file. The tools support local filesystem storage and S3-compatible object storage.
Sources: AGENTS.md:147-152, specs/001-k8s-helm-backup/plan.md:20-25, specs/001-k8s-helm-backup/spec.md:95-98
Troubleshooting Bundle Collection
The infrahub-collect tool gathers diagnostic information without altering the state of the Infrahub instance. It collects:
- Per-replica service logs (including previous container logs in Kubernetes).
- Infrastructure diagnostics for Redis (cache), RabbitMQ (message-queue), and Neo4j.
- Container resource metrics (e.g.,
docker statsorkubectl top). - Masked configuration and environment variables to protect secrets.
Sources: AGENTS.md:162-172, specs/archive/003-collect-tool/plan.md:7-12
Retention Policies
The project implements backup retention rules to manage storage consumption. Operators can define policies based on the maximum age of backups (in days) or the maximum number of backups to keep. These rules are applied automatically after a successful backup or manually via a prune command.
Sources: specs/004-backup-retention-policy/plan.md:7-12, specs/004-backup-retention-policy/plan.md:46-50
Deployment Environments
The tools detect and adapt to the deployment environment, supporting two primary backends:
- Docker Compose: Operations target specific projects using the
--projectflag. The tool interacts with thedockerCLI to manage services likeinfrahub-server,database, andcache. - Kubernetes: Support is provided via Helm charts. The tools interact with
kubectlto perform operations within a specific namespace. A dedicated subchart,infrahub-backup, enables scheduled backups viaCronJoband manual operations viaJobresources.
Sources: AGENTS.md:143-145, AGENTS.md:188-195, specs/001-k8s-helm-backup/plan.md:14-18, specs/001-k8s-helm-backup/spec.md:90-93
Environment detection enables the tools to switch between Docker Compose and Kubernetes CLI commands.
Sources: AGENTS.md:138-145, specs/archive/003-collect-tool/plan.md:10-14, specs/001-k8s-helm-backup/spec.md:140-145
Technical Standards
The project follows a set of Architectural Decision Records (ADRs) to ensure consistency:
- Shell-out Strategy: The tools use
dockerandkubectlCLIs instead of internal client libraries to reduce complexity. - Read-Only Diagnostics: Collection operations never mutate the workload lifecycle or stop containers.
- Secret Masking: Sensitive keys (e.g.,
password,secret,token,key) are masked at a single choke-point in the diagnostic flow. - Self-Contained Binaries: Tools are built as static Go binaries (
CGO_ENABLED=0) for cross-platform compatibility.
Sources: dev/README.md:14-25, specs/archive/003-collect-tool/plan.md:18-22, specs/archive/003-collect-tool/plan.md:37-41
Conclusion
infrahub-ops-cli provides a robust operational framework for Infrahub, covering the full lifecycle of data protection, maintenance, and troubleshooting. By centralizing logic into a shared core and exposing targeted CLI tools, the project ensures consistent behavior across Docker and Kubernetes deployments while maintaining operational safety and data integrity.