Configuration reference
Complete reference for configuring the Infrahub Ops CLI tools through environment variables and runtime flags.
Configuration methods
Tools can be configured through these methods, applied in precedence order:
- Command-line flags (highest priority)
- Environment variables
- Default values (lowest priority)
Environment variables
Core configuration
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_BACKUP_DIR | Directory for storing backup files | ./infrahub_backups | /data/backups |
INFRAHUB_OUTPUT_DIR | Directory for storing troubleshooting bundles | ./infrahub_bundles | /data/bundles |
INFRAHUB_LOG_FORMAT | Output format for logs | text | json |
Retention configuration
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_RETENTION_DAYS | Keep backups newer than N days (N >= 1, unset to disable) | unset | 30 |
INFRAHUB_RETENTION_COUNT | Keep the N most recent backups (N >= 1, unset to disable) | unset | 60 |
Both rules combine as a union, and the most recent backup at each location always survives. A value that is not a whole number of at least 1 — including an explicit 0 — is a validation error that aborts the run rather than disabling the rule; a variable that is present but empty counts as unset. See Manage backup retention.
Docker compose configuration
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_PROJECT | Docker Compose project name | Auto-detect | infrahub-prod |
Database configuration
Neo4j
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_DB_DATABASE | Neo4j database name | neo4j | infrahub |
INFRAHUB_DB_USERNAME | Neo4j username | neo4j | admin |
INFRAHUB_DB_PASSWORD | Neo4j password | admin | SecurePass123 |
Task manager PostgreSQL
| Variable | Description | Default | Example |
|---|---|---|---|
PREFECT_API_DATABASE_CONNECTION_URL | PostgreSQL connection string | Auto-detect | postgresql://user:pass@localhost/prefect |
External database configuration
These apply on Kubernetes when a database resolves as external — running outside the cluster rather than as a deployment container. For a deployment whose databases are all internal they are inert, so no existing configuration needs to change. See Prepare an external database for backup and restore.
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_NEO4J_ADDRESS | Override the Neo4j host list as host[:port][,host[:port]...] | Discovered from the deployment | neo4j-a.example.internal,neo4j-b.example.internal |
INFRAHUB_NEO4J_BACKUP_PORT | Port the Neo4j backup service listens on. Not the client port | 6362 | 6362 |
INFRAHUB_POSTGRES_ADDRESS | Override the PostgreSQL endpoint as host[:port] | Discovered from the deployment | pg.example.internal:5432 |
INFRAHUB_ALLOW_EXTERNAL_RESTORE | Authorize a destructive restore into a database the deployment does not manage | false | true |
INFRAHUB_EXTERNAL_DB_INSECURE_TLS | Do not protect connections to an external database server | false | true |
INFRAHUB_EXTERNAL_DB_TIMEOUT | Bound on any single operation against an external database. Needs a unit | 2h | 4h |
INFRAHUB_EXTERNAL_DB_SCRATCH_SIZE | Scratch space for the transient backup workload | Derived from the database size | 200Gi |
INFRAHUB_EXTERNAL_DB_IMAGE_PULL_SECRETS | Comma-separated secrets in the deployment namespace holding registry credentials for the infrahub-backup image the transient workload runs | unset | my-registry-credentials |
INFRAHUB_EXTERNAL_DB_SERVICE_ACCOUNT | Service account the transient workload runs under | unset | backup-runner |
INFRAHUB_EXTERNAL_DB_NODE_SELECTOR | Comma-separated key=value node labels the transient workload must be scheduled onto | unset | workload=maintenance |
INFRAHUB_EXTERNAL_DB_TOLERATIONS | Comma-separated taints the transient workload tolerates, as key=value:Effect, key:Effect or a bare key | unset | maintenance=true:NoSchedule |
INFRAHUB_EXTERNAL_DB_PRIORITY_CLASS | PriorityClass the transient workload is admitted under | unset | backup-priority |
There is deliberately no environment variable for the transient workload's image.
--external-db-image is the only flag in these tools with no environment equivalent: the tool can
create workloads in your namespace, so an image settable from ambient environment would turn that
permission into a way to run arbitrary code there. The placement
variables above are bound, because they say where a pod may run and which credentials fetch its
image, never what it runs.
INFRAHUB_EXTERNAL_DB_TIMEOUT needs a unit — 4h, 90m, 1h30m. A bare number is refused and
the bound is left unchanged, rather than being read as nanoseconds. Values below 30 seconds are
raised to that floor.
Settings read from the deployment
infrahub-backup reads these out of the Infrahub components still running in the namespace to
discover an external endpoint. You do not set them for the tool — they are Infrahub's own settings,
listed here so you can see where a reported endpoint came from.
| Variable | Used for |
|---|---|
INFRAHUB_DB_ADDRESS | Neo4j host list, as comma-separated host[:port] |
INFRAHUB_DB_PORT | Neo4j client port. Not the backup port |
INFRAHUB_DB_PROTOCOL | bolt or neo4j |
INFRAHUB_DB_TLS_ENABLED | Whether the deployment encrypts its own database connections |
INFRAHUB_DB_TLS_INSECURE | Whether the deployment verifies its own database certificate. Does not confer --external-db-insecure-tls |
INFRAHUB_DB_TLS_CA_FILE | Certificate authority the tool carries into the transient workload |
PREFECT_API_DATABASE_CONNECTION_URL | PostgreSQL host, port, database, user, password and sslrootcert |
Collect configuration
| Variable | Description | Default | Example |
|---|---|---|---|
INFRAHUB_BENCHMARK_IMAGE | Container image used by the opt-in --benchmark run | registry.opsmill.io/opsmill/bench | registry.example.com/opsmill/bench |
INFRAHUB_TRACES_TEMPO_TOKEN | Token of the trace backend given with --traces-tempo-url, sent as a bearer token; never written to the bundle or the output | unset | glc_... |
INFRAHUB_TRACES_API_TOKEN | Infrahub API token with the super_admin permission, used only to read the trace sampling ratio; never written to the bundle or the output | unset | 06438eb2-... |
Command-line flag reference
Global flags
| Flag | Environment Override | Description |
|---|---|---|
--backup-dir | INFRAHUB_BACKUP_DIR | Set backup directory |
--project | INFRAHUB_PROJECT | Target specific Docker Compose project |
--log-format | INFRAHUB_LOG_FORMAT | Set log output format |
Backup command flags
| Flag | Description |
|---|---|
--force | Force backup creation even if tasks are running |
--neo4jmetadata | Neo4j metadata to include (all, none, users, roles) |
--retention-days | Prune backups older than N days after a successful backup |
--retention-count | Keep only the N most recent backups after a successful backup |
External database flags
Available on both create and restore, and inert unless a database resolves as external. Every
one has an environment override except --external-db-image.
| Flag | Environment Override | Description |
|---|---|---|
--neo4j-address | INFRAHUB_NEO4J_ADDRESS | Override the Neo4j host list as host[:port][,host[:port]...] |
--neo4j-backup-port | INFRAHUB_NEO4J_BACKUP_PORT | Port the Neo4j backup service listens on, default 6362. Not the client port |
--postgres-address | INFRAHUB_POSTGRES_ADDRESS | Override the PostgreSQL endpoint as host[:port] |
--allow-external-restore | INFRAHUB_ALLOW_EXTERNAL_RESTORE | Authorize a destructive restore into a database the deployment does not manage |
--external-db-insecure-tls | INFRAHUB_EXTERNAL_DB_INSECURE_TLS | Skip certificate verification, and accept a channel with no encryption where the deployment records TLS as disabled |
--external-db-timeout | INFRAHUB_EXTERNAL_DB_TIMEOUT | Bound on any single operation against an external database, default 2h |
--external-db-scratch-size | INFRAHUB_EXTERNAL_DB_SCRATCH_SIZE | Scratch space for the transient backup workload, such as 200Gi |
--external-db-image | none, by design | Image the transient workload runs for both databases. Default registry.opsmill.io/opsmill/infrahub-backup:<version>, the version of the binary you run. A build that is not a release has no default and requires this flag |
--external-db-image-pull-secrets | INFRAHUB_EXTERNAL_DB_IMAGE_PULL_SECRETS | Secrets in the deployment namespace holding registry credentials for the infrahub-backup image |
--external-db-service-account | INFRAHUB_EXTERNAL_DB_SERVICE_ACCOUNT | Service account the transient workload runs under. It mounts no service-account token |
--external-db-node-selector | INFRAHUB_EXTERNAL_DB_NODE_SELECTOR | Node labels the transient workload must be scheduled onto |
--external-db-tolerations | INFRAHUB_EXTERNAL_DB_TOLERATIONS | Taints the transient workload tolerates |
--external-db-priority-class | INFRAHUB_EXTERNAL_DB_PRIORITY_CLASS | PriorityClass the transient workload is admitted under |
External restore authorization
Restoring into a database the deployment does not manage overwrites data in a system Infrahub does not own, so it carries its own authorization, separate from every other gate:
--forcedoes not confer it.--forceskips the running-tasks consistency check and nothing else.- Enabling scheduled restore does not confer it.
- For an unattended restore, set
INFRAHUB_ALLOW_EXTERNAL_RESTORE=truein the schedule's configuration. The flag form exists for interactive use, and the tool reports which of the two channels supplied the authorization. - A value that is not a boolean leaves external restore unauthorized, with a warning.
Without it, an external restore exits non-zero and the database is untouched.
There is no TLS policy flag. --external-db-insecure-tls is the only opt-out from verifying an
external database server, and --external-db-tls-policy does not exist — an earlier plan named it,
but the channel it would have configured takes no policy name.
Collect command flags
| Flag | Environment Override | Description |
|---|---|---|
--log-lines | INFRAHUB_LOG_LINES | Maximum log lines collected per container (default 100000) |
--include-backup | INFRAHUB_INCLUDE_BACKUP | Also create a backup during collection |
--include-queries | INFRAHUB_INCLUDE_QUERIES | Include database query logs in the bundle |
--benchmark | INFRAHUB_BENCHMARK | Run the OpsMill benchmark and include its results |
--include-traces | INFRAHUB_INCLUDE_TRACES | Include the traces of slow requests from Tempo |
--traces-since | INFRAHUB_TRACES_SINCE | Period before now to read traces from (default 2h) |
--traces-start | INFRAHUB_TRACES_START | Start of an absolute traces window, in RFC 3339 |
--traces-end | INFRAHUB_TRACES_END | End of an absolute traces window, in RFC 3339 |
--traces-min-duration | INFRAHUB_TRACES_MIN_DURATION | Shortest trace duration kept (default 1s) |
--traces-max-size | INFRAHUB_TRACES_MAX_SIZE | Size limit of the traces, in megabytes (default 100) |
--traces-tempo-url | INFRAHUB_TRACES_TEMPO_URL | Tempo-compatible backend to read instead of the deployment's Tempo |
Auto-detection behavior
When you set --project (INFRAHUB_PROJECT) or --k8s-namespace (INFRAHUB_K8S_NAMESPACE), the
command acts only on that deployment. If it cannot reach it, the command fails and does not look for
another deployment on the same host. If you set both, the command tries the Kubernetes namespace
first and then the Docker Compose project, and fails only when it reaches neither.
Docker Compose project detection
Order of detection:
--projectflagINFRAHUB_PROJECTenvironment variable- Search for running Infrahub containers
Detection command:
docker compose ls --filter "name=*infrahub*"
Kubernetes pod detection
For each service, the tool tries these label selectors in order and uses the first one that returns pods:
infrahub/service=<service>. The Infrahub Helm chart and the Infrahub high availability deployment example set this label on every component.- For the
databaseservice only,helm.neo4j.com/pod_category=neo4j-instance, which the Neo4j Helm chart sets on every Neo4j server pod. app.kubernetes.io/component=<service>, thenapp=<service>, thencomponent=<service>.
If no selector returns pods, the tool uses the pods whose name contains the service name.
Other software in the namespace can set the labels in step 3 to the same values. For example, CloudNativePG labels its PostgreSQL pods app.kubernetes.io/component=database, the same value as the Neo4j service name. Set infrahub/service on the pods of every Infrahub service, so the tool finds them in step 1.
When several pods match and the tool needs one, it uses the pod labelled cnpg.io/instanceRole=primary or role=primary, and otherwise the first pod.
Database credential detection
For Docker Compose deployments:
# Neo4j credentials from environment
docker compose exec database printenv NEO4J_AUTH
# PostgreSQL credentials from environment
docker compose exec task-manager-db printenv POSTGRES_PASSWORD
Troubleshooting configuration
Debug configuration loading
View effective configuration:
infrahub-backup --help
Test configuration
Validate configuration without running operations:
infrahub-backup environment detect
Common issues
Cannot detect environment
# Check Docker
docker compose ls
docker ps
# Check for Infrahub containers
docker ps --filter "name=infrahub"
Authentication failures
# Verify credentials are set
env | grep INFRAHUB
env | grep PREFECT
# Test database connectivity
docker compose exec database cypher-shell -u neo4j
Examples
Minimal configuration
For basic Docker Compose setup:
export INFRAHUB_BACKUP_DIR=/backups
infrahub-backup create
Production configuration
#!/bin/bash
# production-backup.sh
export INFRAHUB_LOG_FORMAT=json
export INFRAHUB_PROJECT=infrahub-production
export INFRAHUB_BACKUP_DIR=/data/backups/infrahub
export INFRAHUB_DB_PASSWORD="${NEO4J_PASSWORD}"
infrahub-backup create --neo4jmetadata=all