Docker & Kubernetes Deployment
Relevant source files
The following files were used as context for generating this wiki page:
- docker-compose.yml
- development/k8s/infrahub-values.yaml
- AGENTS.md
- dev/specs/infp-566-dynamic-versions/plan.md
- dev/specs/infp-566-dynamic-versions/tasks.md
- dev/specs/infp-566-dynamic-versions/contracts/ci-workflows.md
- dev/guidelines/repository-organization.md
- dev/specs/infp-409-artifact-regen-triggers/plan.md
Infrahub uses containerization to manage infrastructure data across development, testing, and production environments. The project provides Docker configurations for local orchestration and Helm charts for Kubernetes deployments. These systems integrate with a CI/CD pipeline that automates image building, version propagation, and artifact management.
The deployment architecture focuses on service isolation, using Docker Compose for local stacks and Helm for scalable Kubernetes clusters. Version control is synchronized across these platforms via Git tags, ensuring that the infrahub-server, task-worker, and associated components maintain consistent versioning during releases.
Sources: AGENTS.md:1-10, dev/specs/infp-566-dynamic-versions/plan.md:12-25
Container Architecture and Build System
Infrahub utilizes BuildKit to optimize the Docker build process. The system uses a specific Dockerfile strategy to handle dynamic versioning without polluting final production images with build-time artifacts like the .git directory.
BuildKit and Image Optimization
The development/Dockerfile uses BuildKit bind mounts to access Git metadata during the build phase. This allows the hatch-vcs resolver to determine the package version from Git tags without requiring the .git directory to be copied permanently into the image.
The diagram shows how BuildKit bind mounts allow the version resolver to access Git history while the final image remains clean of Git metadata.
Sources: dev/specs/infp-566-dynamic-versions/tasks.md:126-135, dev/specs/infp-566-dynamic-versions/plan.md:55-60
Docker Component Summary
| Component | Description | Configuration File |
|---|---|---|
infrahub-server | The primary FastAPI/GraphQL backend server. | development/Dockerfile |
task-worker | Prefect-based worker for background tasks. | docker-compose.yml |
infrahub-testcontainers | Specialized containers for component and E2E testing. | python_testcontainers/pyproject.toml |
server-lb | Load balancer for API and UI traffic. | AGENTS.md:75-77 |
Sources: AGENTS.md:12-20, dev/specs/infp-566-dynamic-versions/tasks.md:52-55
Local Orchestration with Docker Compose
Infrahub provides a shared task runner to manage Docker Compose operations. You use invoke commands to build and run the local stack, which handles environment variables and service profiles automatically.
Automated Task Execution
Invoke tasks under tasks/*.py build Docker commands using helpers like get_compose_cmd. These helpers select the required profiles and ensure standard output formatting (e.g., --ansi never).
- Build command:
uv run invoke dev.build - Service Constants: Components are referenced via shared constants such as
SERVICE_WORKER_NAME. - Environment management: The system uses
get_env_varsto inject necessary credentials and configuration into the Compose execution context.
Sources: AGENTS.md:92-95, AGENTS.md:189-195
Kubernetes Deployment via Helm
Infrahub manages Kubernetes deployments using Helm charts. The deployment process involves updating chart metadata and managing dependencies for different product tiers, such as Infrahub Enterprise.
Helm Chart Lifecycle
The release process uses the update_helm_chart Invoke task to synchronize versions. This task performs the following actions:
- Updates the
appVersionin the chart metadata. - Bumps the
versionfield of the chart. - Updates the
prefectTaginvalues.yaml. - Synchronizes dependencies for
infrahub-enterprise.
Sources: dev/specs/infp-566-dynamic-versions/tasks.md:91-95
Kubernetes Configuration Parameters
| Parameter | Purpose | Location |
|---|---|---|
appVersion | Defines the version of the Infrahub application image. | Chart.yaml |
prefectTag | Specifies the image tag for task workers. | infrahub-values.yaml |
fetch-depth | Required for CI to resolve versions from tags during deployment. | .github/workflows/ |
Sources: dev/specs/infp-566-dynamic-versions/tasks.md:92-95, dev/specs/infp-566-dynamic-versions/contracts/ci-workflows.md:5-15
CI/CD and Version Propagation
Infrahub implements a tag-driven deployment flow. When you push a Git tag (matching infrahub-v*), the CI system triggers artifact generation and propagates version updates to deployment manifests.
The sequence diagram illustrates how a single Git tag push orchestrates the entire container and Kubernetes deployment update cycle.
Sources: dev/specs/infp-566-dynamic-versions/contracts/ci-workflows.md:38-50, dev/specs/infp-566-dynamic-versions/tasks.md:104-118
Propagation Guards
To prevent invalid deployments, the CI pipeline includes several automated guards:
- Main-line Check: Propagation only occurs if the tag commit is an ancestor of the
stablebranch. - Version Match Guard: The workflow fails if the resolved internal metadata version does not match the pushed Git tag.
- Fallback Guard: The system prevents publishing if the version resolves to a default fallback (e.g.,
0.0.0.dev0), indicating a failure to read Git metadata.
Sources: dev/specs/infp-566-dynamic-versions/contracts/ci-workflows.md:25-36, dev/specs/infp-566-dynamic-versions/tasks.md:213-220
Testing in Containerized Environments
Infrahub relies on testcontainers for component and end-to-end (E2E) testing. This ensures that tests run against the same service definitions used in production.
- Test Execution: Run
uv run pytestto initiate tests that spawn transient Docker containers. - Manual Debugging: You can freeze a test session using the
--pdbflag. This leaves the containerized stack (API server, database, worker) alive for manual inspection via standard Docker commands. - Service Discovery: During tests, you can find the local port of the API server using:
docker compose -p $PROJECT port infrahub-server-lb 8000
Sources: AGENTS.md:58-65, AGENTS.md:73-77
Infrahub's Docker and Kubernetes deployment strategy ensures that environment configuration remains synchronized with the source code through automated CI/CD triggers and dynamic versioning. By isolating build-time metadata via BuildKit and using Helm for structured Kubernetes releases, the project maintains a clean, versioned, and scalable infrastructure stack.
Sources: dev/specs/infp-566-dynamic-versions/plan.md:12-25, dev/guidelines/repository-organization.md:105-110