Skip to main content

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:

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Default values (lowest priority)

Environment variables​

Core configuration​

VariableDescriptionDefaultExample
INFRAHUB_BACKUP_DIRDirectory for storing backup files./infrahub_backups/data/backups
INFRAHUB_OUTPUT_DIRDirectory for storing troubleshooting bundles./infrahub_bundles/data/bundles
INFRAHUB_LOG_FORMATOutput format for logstextjson

Retention configuration​

VariableDescriptionDefaultExample
INFRAHUB_RETENTION_DAYSKeep backups newer than N days (N >= 1, unset to disable)unset30
INFRAHUB_RETENTION_COUNTKeep the N most recent backups (N >= 1, unset to disable)unset60

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​

VariableDescriptionDefaultExample
INFRAHUB_PROJECTDocker Compose project nameAuto-detectinfrahub-prod

Database configuration​

Neo4j​

VariableDescriptionDefaultExample
INFRAHUB_DB_DATABASENeo4j database nameneo4jinfrahub
INFRAHUB_DB_USERNAMENeo4j usernameneo4jadmin
INFRAHUB_DB_PASSWORDNeo4j passwordadminSecurePass123

Task manager PostgreSQL​

VariableDescriptionDefaultExample
PREFECT_API_DATABASE_CONNECTION_URLPostgreSQL connection stringAuto-detectpostgresql://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.

VariableDescriptionDefaultExample
INFRAHUB_NEO4J_ADDRESSOverride the Neo4j host list as host[:port][,host[:port]...]Discovered from the deploymentneo4j-a.example.internal,neo4j-b.example.internal
INFRAHUB_NEO4J_BACKUP_PORTPort the Neo4j backup service listens on. Not the client port63626362
INFRAHUB_POSTGRES_ADDRESSOverride the PostgreSQL endpoint as host[:port]Discovered from the deploymentpg.example.internal:5432
INFRAHUB_ALLOW_EXTERNAL_RESTOREAuthorize a destructive restore into a database the deployment does not managefalsetrue
INFRAHUB_EXTERNAL_DB_INSECURE_TLSDo not protect connections to an external database serverfalsetrue
INFRAHUB_EXTERNAL_DB_TIMEOUTBound on any single operation against an external database. Needs a unit2h4h
INFRAHUB_EXTERNAL_DB_SCRATCH_SIZEScratch space for the transient backup workloadDerived from the database size200Gi
INFRAHUB_EXTERNAL_DB_IMAGE_PULL_SECRETSComma-separated secrets in the deployment namespace holding registry credentials for the infrahub-backup image the transient workload runsunsetmy-registry-credentials
INFRAHUB_EXTERNAL_DB_SERVICE_ACCOUNTService account the transient workload runs underunsetbackup-runner
INFRAHUB_EXTERNAL_DB_NODE_SELECTORComma-separated key=value node labels the transient workload must be scheduled ontounsetworkload=maintenance
INFRAHUB_EXTERNAL_DB_TOLERATIONSComma-separated taints the transient workload tolerates, as key=value:Effect, key:Effect or a bare keyunsetmaintenance=true:NoSchedule
INFRAHUB_EXTERNAL_DB_PRIORITY_CLASSPriorityClass the transient workload is admitted underunsetbackup-priority
warning

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.

VariableUsed for
INFRAHUB_DB_ADDRESSNeo4j host list, as comma-separated host[:port]
INFRAHUB_DB_PORTNeo4j client port. Not the backup port
INFRAHUB_DB_PROTOCOLbolt or neo4j
INFRAHUB_DB_TLS_ENABLEDWhether the deployment encrypts its own database connections
INFRAHUB_DB_TLS_INSECUREWhether the deployment verifies its own database certificate. Does not confer --external-db-insecure-tls
INFRAHUB_DB_TLS_CA_FILECertificate authority the tool carries into the transient workload
PREFECT_API_DATABASE_CONNECTION_URLPostgreSQL host, port, database, user, password and sslrootcert

Collect configuration​

VariableDescriptionDefaultExample
INFRAHUB_BENCHMARK_IMAGEContainer image used by the opt-in --benchmark runregistry.opsmill.io/opsmill/benchregistry.example.com/opsmill/bench
INFRAHUB_TRACES_TEMPO_TOKENToken of the trace backend given with --traces-tempo-url, sent as a bearer token; never written to the bundle or the outputunsetglc_...
INFRAHUB_TRACES_API_TOKENInfrahub API token with the super_admin permission, used only to read the trace sampling ratio; never written to the bundle or the outputunset06438eb2-...

Command-line flag reference​

Global flags​

FlagEnvironment OverrideDescription
--backup-dirINFRAHUB_BACKUP_DIRSet backup directory
--projectINFRAHUB_PROJECTTarget specific Docker Compose project
--log-formatINFRAHUB_LOG_FORMATSet log output format

Backup command flags​

FlagDescription
--forceForce backup creation even if tasks are running
--neo4jmetadataNeo4j metadata to include (all, none, users, roles)
--retention-daysPrune backups older than N days after a successful backup
--retention-countKeep 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.

FlagEnvironment OverrideDescription
--neo4j-addressINFRAHUB_NEO4J_ADDRESSOverride the Neo4j host list as host[:port][,host[:port]...]
--neo4j-backup-portINFRAHUB_NEO4J_BACKUP_PORTPort the Neo4j backup service listens on, default 6362. Not the client port
--postgres-addressINFRAHUB_POSTGRES_ADDRESSOverride the PostgreSQL endpoint as host[:port]
--allow-external-restoreINFRAHUB_ALLOW_EXTERNAL_RESTOREAuthorize a destructive restore into a database the deployment does not manage
--external-db-insecure-tlsINFRAHUB_EXTERNAL_DB_INSECURE_TLSSkip certificate verification, and accept a channel with no encryption where the deployment records TLS as disabled
--external-db-timeoutINFRAHUB_EXTERNAL_DB_TIMEOUTBound on any single operation against an external database, default 2h
--external-db-scratch-sizeINFRAHUB_EXTERNAL_DB_SCRATCH_SIZEScratch space for the transient backup workload, such as 200Gi
--external-db-imagenone, by designImage 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-secretsINFRAHUB_EXTERNAL_DB_IMAGE_PULL_SECRETSSecrets in the deployment namespace holding registry credentials for the infrahub-backup image
--external-db-service-accountINFRAHUB_EXTERNAL_DB_SERVICE_ACCOUNTService account the transient workload runs under. It mounts no service-account token
--external-db-node-selectorINFRAHUB_EXTERNAL_DB_NODE_SELECTORNode labels the transient workload must be scheduled onto
--external-db-tolerationsINFRAHUB_EXTERNAL_DB_TOLERATIONSTaints the transient workload tolerates
--external-db-priority-classINFRAHUB_EXTERNAL_DB_PRIORITY_CLASSPriorityClass 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:

  • --force does not confer it. --force skips the running-tasks consistency check and nothing else.
  • Enabling scheduled restore does not confer it.
  • For an unattended restore, set INFRAHUB_ALLOW_EXTERNAL_RESTORE=true in 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​

FlagEnvironment OverrideDescription
--log-linesINFRAHUB_LOG_LINESMaximum log lines collected per container (default 100000)
--include-backupINFRAHUB_INCLUDE_BACKUPAlso create a backup during collection
--include-queriesINFRAHUB_INCLUDE_QUERIESInclude database query logs in the bundle
--benchmarkINFRAHUB_BENCHMARKRun the OpsMill benchmark and include its results
--include-tracesINFRAHUB_INCLUDE_TRACESInclude the traces of slow requests from Tempo
--traces-sinceINFRAHUB_TRACES_SINCEPeriod before now to read traces from (default 2h)
--traces-startINFRAHUB_TRACES_STARTStart of an absolute traces window, in RFC 3339
--traces-endINFRAHUB_TRACES_ENDEnd of an absolute traces window, in RFC 3339
--traces-min-durationINFRAHUB_TRACES_MIN_DURATIONShortest trace duration kept (default 1s)
--traces-max-sizeINFRAHUB_TRACES_MAX_SIZESize limit of the traces, in megabytes (default 100)
--traces-tempo-urlINFRAHUB_TRACES_TEMPO_URLTempo-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:

  1. --project flag
  2. INFRAHUB_PROJECT environment variable
  3. 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:

  1. infrahub/service=<service>. The Infrahub Helm chart and the Infrahub high availability deployment example set this label on every component.
  2. For the database service only, helm.neo4j.com/pod_category=neo4j-instance, which the Neo4j Helm chart sets on every Neo4j server pod.
  3. app.kubernetes.io/component=<service>, then app=<service>, then component=<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