Quickstart Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the necessary steps to install, configure, and operate the Infrahub toolset for backup, task management, and diagnostic collection. The project comprises three Go-based binaries: infrahub-backup, infrahub-taskmanager, and infrahub-collect. These tools share common internal application logic but expose specialized commands for different operational tasks.
Sources: AGENTS.md:7-14, AGENTS.md:120-130
Installation and Building
The project uses a Makefile to manage the build process for all three binaries. You can build the tools for your local architecture or cross-compile them for multiple platforms.
Building Locally
- Run
make buildto generate the binaries in thebin/directory. - Run
make installto build and install all three binaries to your$GOPATH/bin.
Multi-Arch Docker Build
The project supports multi-arch Docker images (amd64 and arm64) using Docker Buildx.
- Build for the current platform:
make docker-build - Build for both architectures:
make docker-build-multi - Build and push to a registry:
make docker-push
Sources: AGENTS.md:18-24, specs/001-k8s-helm-backup/plan.md:78-85
Backup Operations
The infrahub-backup tool manages data persistence for Infrahub instances. It supports local filesystem storage, S3-compatible object storage, and the Plakar backup engine.
Creating a Backup
You create a backup using the create command. By default, this creates a tar.gz archive containing Neo4j and PostgreSQL database dumps along with a metadata.json file.
infrahub-backup create --s3-upload --s3-bucket my-backups
Automatic Retention
To prevent storage exhaustion, you can apply retention policies during the backup creation process.
--retention-days: Keep backups for a specific number of days.--retention-count: Keep a specific number of recent backups.
The system always preserves the newest backup regardless of the policy.
Sources: AGENTS.md:144-150, specs/004-backup-retention-policy/plan.md:9-15, specs/004-backup-retention-policy/tasks.md:104-110
Restoring the Latest Backup
You can restore the most recent backup without specifying a filename by using the --latest flag. This works for both local storage and S3 storage.
# Restore latest from local storage
infrahub-backup restore --latest
# Restore latest from S3
infrahub-backup restore --latest --s3
Sources: specs/005-restore-latest-backup/tasks.md:38-45, specs/005-restore-latest-backup/tasks.md:100-105
Kubernetes Deployment via Helm
Infrahub Backup supports deployment as a subchart within the main Infrahub Helm chart. This allows for automated scheduled backups (CronJobs) or manual one-shot backups (Jobs) within a Kubernetes cluster.
Backup Workflow in Kubernetes
The following diagram illustrates the workflow for a scheduled backup to S3 within a Kubernetes environment.
The backup job interacts with the Infrahub database services, archives the data, and uploads it to external storage before cleaning up old archives.
Sources: specs/001-k8s-helm-backup/plan.md:140-160, specs/001-k8s-helm-backup/tasks.md:65-75
Configuration Options
Configuration can be managed via command-line flags or environment variables prefixed with INFRAHUB_.
| Option | Environment Variable | Description |
|---|---|---|
--s3-bucket | INFRAHUB_S3_BUCKET | The S3 bucket for backup storage |
--s3-region | INFRAHUB_S3_REGION | The AWS/S3 region |
--retention-days | INFRAHUB_RETENTION_DAYS | Number of days to keep backups |
--retention-count | INFRAHUB_RETENTION_COUNT | Number of backups to keep |
Sources: specs/001-k8s-helm-backup/plan.md:43-50, specs/004-backup-retention-policy/tasks.md:104-106
Diagnostic Collection
The infrahub-collect tool gathers troubleshooting bundles (read-only diagnostics) for support purposes.
- Run
infrahub-collect createto start the collection. - The tool stages logs, metrics, and diagnostics from all Infrahub services.
- It produces a single
tar.gzbundle containing abundle_information.jsonmanifest. - Sensitive information like passwords and keys are automatically masked in the output.
Sources: AGENTS.md:158-166, specs/archive/003-collect-tool/tasks.md:65-75
This toolset ensures that Infrahub instances remain maintainable through standardized backup, restore, and diagnostic procedures across both Docker Compose and Kubernetes environments.