Environment Detection
Relevant source files
The following files were used as context for generating this wiki page:
Environment Detection identifies the underlying container orchestration platform where Infrahub resides. The system differentiates between Docker Compose and Kubernetes to ensure that backup, restore, and troubleshooting operations use the correct CLI tools and service discovery mechanisms.
All three project binaries—infrahub-backup, infrahub-taskmanager, and infrahub-collect—share this core logic to target Infrahub services like Neo4j, PostgreSQL, and RabbitMQ regardless of the deployment backend.
Sources: AGENTS.md:12-16, specs/archive/003-collect-tool/spec.md:67-69
Architecture and Backend Seams
The environment detection system relies on the InfrahubOps controller and a CommandExecutor that shells out to native CLIs (docker or kubectl) rather than using software development kits (SDKs).
Sources: AGENTS.md:71-77, specs/archive/003-collect-tool/research.md:7-12
Detection Logic Flow
The system probes for environment-specific characteristics to determine which EnvironmentBackend to initialize. It evaluates Kubernetes markers first, followed by Docker Compose project availability.
The diagram shows the sequential probing logic used to identify the deployment environment.
Sources: specs/archive/003-collect-tool/plan.md:32-35, specs/archive/003-collect-tool/research.md:7-12
Environment Backends
The system implements specific logic for two primary backends. Each backend satisfies a shared interface that allows higher-level tools to enumerate replicas, stream logs, and execute commands without knowing the underlying orchestration details.
Sources: specs/archive/003-collect-tool/tasks.md:46-50
Kubernetes Backend
The Kubernetes backend targets deployments managed by the official Helm chart. It identifies services using pod labels and namespace context.
- Service Discovery: Uses
kubectl get pod -o jsonpathto resolve pod names and container statuses. - Replica Enumeration: Tracks individual containers within pods, including
restartCountfor health monitoring. - Log Streaming: Executes
kubectl logswith optional--previousflags for containers that have restarted.
Sources: specs/archive/003-collect-tool/tasks.md:65-72, specs/archive/003-collect-tool/research.md:33-40
Docker Backend
The Docker backend interacts with local or remote Docker engines via the docker CLI. It focuses on project-level isolation.
- Project Targeting: Uses the
--projectflag orCOMPOSE_PROJECT_NAMEenvironment variable. - Service Discovery: Executes
docker compose psto list containers associated with specific Infrahub services. - Metrics: Gathers resource data via
docker stats --no-stream.
Sources: specs/archive/003-collect-tool/tasks.md:95-103, specs/archive/003-collect-tool/research.md:44-48
Configuration and CLI Surface
Environment detection is controlled through shared global flags and environment variables. These parameters allow users to override automatic detection or specify exact targets.
| Flag | Environment Variable | Backend | Description |
|---|---|---|---|
--project | INFRAHUB_PROJECT | Docker | Specifies the Docker Compose project name. |
--k8s-namespace | INFRAHUB_K8S_NAMESPACE | Kubernetes | Specifies the namespace where Infrahub is deployed. |
--log-format | INFRAHUB_LOG_FORMAT | Both | Controls the output format of detection logs (e.g., text, json). |
Sources: AGENTS.md:88-92, specs/archive/003-collect-tool/tasks.md:104-106, specs/archive/003-collect-tool/spec.md:67-69
Shared Environment Commands
Every binary includes built-in commands for manual environment verification:
environment detect: Triggers the detection logic and prints the identified backend.environment list: Lists discoverable services, replicas, and pods within the detected environment.
Sources: AGENTS.md:90-92, specs/archive/003-collect-tool/spec.md:120-125
Technical Implementation Details
The core implementation utilizes exec.CommandContext to ensure all shell-outs to environment CLIs are time-bounded. This prevents a hung container or unresponsive API from stalling the environment detection process.
Sources: specs/archive/003-collect-tool/research.md:15-22
- Command Execution:
src/internal/app/command_executor.goprovides the abstraction for running shell commands. - Backend Seam:
src/internal/app/collect.godefines thecollectBackendinterface used to bridge generic collection logic with environment-specific implementations.
Sources: specs/archive/003-collect-tool/tasks.md:52-57, specs/archive/003-collect-tool/opsmill-implement-report.md:20-22
Environment detection is critical for the "Shared-Core" architecture, ensuring that specialized tools for backup or collection remain platform-agnostic while leveraging native orchestration capabilities.
Sources: AGENTS.md:66-70, specs/archive/003-collect-tool/plan.md:16-20