Command Execution Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Command Execution Engine manages the execution of system commands and containerized operations within the Infrahub toolset. It interfaces with external command-line interfaces (CLIs) such as docker and kubectl to interact with Infrahub deployments in both Docker Compose and Kubernetes environments. The engine serves as the core execution layer for backup, restore, diagnostic collection, and task management operations.
This system relies on a shell-out architecture rather than native client libraries to maintain cross-platform compatibility and simplify authentication handling. It supports synchronous command execution, streaming output for real-time feedback, and timeout-bounded operations to prevent stalls during diagnostic collection on degraded instances.
Sources: AGENTS.md, specs/archive/003-collect-tool/plan.md, specs/archive/003-collect-tool/research.md
Core Architecture
The engine uses the CommandExecutor struct to handle system command calls. This component abstracts the underlying environment, allowing the application logic to issue commands without concern for whether the target is a local process, a Docker container, or a Kubernetes pod.
System Flow
The following diagram illustrates the flow from a CLI request through the execution engine to the target environment.
The Command Execution Engine acts as a bridge between high-level application logic and environment-specific CLIs.
Sources: AGENTS.md, specs/archive/003-collect-tool/research.md:R1
Execution Primitives
The engine provides several methods for running commands, categorized by their interaction with process I/O and lifecycle management.
Synchronous Execution
The runCommand primitive executes a command and waits for it to complete. It captures both standard output (stdout) and standard error (stderr) to provide full context for logs or error reporting.
Sources: specs/archive/003-collect-tool/tasks.md:T010
Streaming Output
For operations involving large data transfers—such as log collection or database dumps—the engine uses runCommandPipe. This method streams output directly to a writer (e.g., a file on disk) to avoid excessive memory consumption.
Sources: specs/archive/003-collect-tool/research.md:R3, specs/archive/003-collect-tool/opsmill-implement-report.md
Time-Bounded Execution
To prevent diagnostic tasks from hanging on degraded systems, the engine implements exec.CommandContext variants. These variants enforce timeouts on individual collector subprocesses.
Sources: specs/archive/003-collect-tool/research.md:R2
| Feature | Description | File Context |
|---|---|---|
| Timeout Bounds | Default 60s for exec/status dumps; 5m for logs/transfers. | research.md:R2 |
| Combined Pipe | Merges stdout and stderr for complete service logging. | opsmill-implement-report.md |
| Shell-out | Reuses host-installed docker and kubectl binaries. | research.md:R1 |
Environment Backends
The execution engine adapts its behavior based on the detected EnvironmentBackend. Each backend translates generic requests into specific CLI arguments.
Docker Compose Backend
The Docker backend targets containers using docker compose commands. It targets specific projects using the --project flag and identifies containers by their service names.
Sources: AGENTS.md, specs/archive/003-collect-tool/research.md:R3
Kubernetes Backend
The Kubernetes backend utilizes kubectl for all operations. It handles pod discovery, replica enumeration, and execution within containers. It supports namespace isolation via the --k8s-namespace flag.
Sources: AGENTS.md, specs/archive/003-collect-tool/research.md:R1
Execution Logic for Backends
This sequence shows how the engine resolves service identities before executing commands through the external CLI.
Sources: specs/archive/003-collect-tool/plan.md, specs/archive/003-collect-tool/research.md:R3
Script Execution Engine
In addition to direct binary execution, the project includes a ScriptExecutor for running embedded Python scripts. This is primarily used for complex task management operations involving the Prefect API.
- Embedded Scripts: Python scripts are stored using Go's
embedpackage. - Container Execution: Scripts are injected into and executed within the application containers (e.g.,
infrahub-server,task-manager) to ensure they have the necessary environment and connectivity. - Read-Only Collection: During diagnostic runs, these scripts fetch work pools, queues, and recent flow runs without modifying the workload state.
Sources: AGENTS.md, src/internal/app/app.go, specs/archive/003-collect-tool/research.md:R8-R9
Error Handling and Safety
The Command Execution Engine prioritizes operational safety, particularly during troubleshooting bundle collection.
- Read-Only Enforcement: The engine is configured to prevent lifecycle mutations (stopping, starting, or scaling) during diagnostic runs.
- Non-Fatal Failures: Individual command failures are caught and recorded in a manifest (e.g.,
bundle_information.json) rather than causing the entire application to exit. - Secret Masking: The engine routes specific command outputs (like
envdumps or RedisCONFIG GET) through a masking function to redact passwords and tokens before they are saved to disk.
Sources: specs/archive/003-collect-tool/plan.md, specs/archive/003-collect-tool/research.md:R2, R5
Conclusion
The Command Execution Engine provides a robust, shell-based execution layer for Infrahub operations. By abstracting environment-specific details behind the CommandExecutor and EnvironmentBackend interfaces, it enables consistent backup and diagnostic capabilities across Docker and Kubernetes deployments. The addition of timeout-bounded execution and streaming pipes ensures the system remains reliable even when interacting with degraded or high-volume data environments.