Get a Docker Compose file for free in your project, built from the Helm charts you already maintain. Composer turns those charts into a local development environment and keeps your Compose file in sync as your charts change. Add the GitHub Action to automatically generate and commit updated output, or run Composer locally to get started.
Table of contents
Requires Python 3.13+ and Poetry 2.1+. Chart rendering requires Helm 4 with the chart's dependencies already built. Docker Compose is needed to inspect or run the output.
From a checkout of this repository:
poetry install
poetry run composer --helpPoetry creates the environment in .venv/. Compilation runs locally without a
Kubernetes cluster.
Generate a starting configuration from your chart:
poetry run composer --chart ./path/to/chart --output compose.yamlFor an application runtime, use a profile to select services, publish ports, configure local builds and map operator-managed resources to standalone containers:
poetry run composer --chart ./path/to/chart \
--profile compose.profile.yaml --output compose.yaml
docker compose -f compose.yaml configThe usage guide includes a profile example, values overrides, already-rendered manifests and the complete CLI reference. Review the generated configuration before starting it with Docker Compose. Kubernetes controllers, scheduling and autoscaling require explicit runtime choices; their behavior is not reproduced by translating containers.
Native GitOps ordering translates Argo CD phases and sync waves, Application ownership, and Flux Kustomization/HelmRelease dependencies into Compose startup gates.
flowchart LR
Chart[Helm chart and values] --> Helm[Helm rendering]
Helm --> Inputs[Resources and coalesced values]
Manifests[Kubernetes manifests] --> Inputs
Inputs --> AST[Kubernetes and Compose ASTs]
AST --> Compile[Service compilation]
Profile[Runtime profile] --> Compile
Compile --> Validate[Schema and dependency validation]
Validate --> Compose[compose.yaml and mounted files]
Validate --> Compare[Optional drift check and JSON report]
Profiles select a resource and container, inherit its configuration, then apply local overrides. Bindings can read rendered resource fields, container fields or Helm values. Validation catches missing or ambiguous selections, invalid configuration and broken startup dependencies. Source charts remain unchanged during compilation.
See runtime profiles for selection and override rules, and compiler internals for implementation details.
Get a Docker Compose file for free with the GitHub Action.
The reusable Action watches helm/ by default and commits changed Compose output back
to your branch. Its watch directory is configurable, and it also supports drift checks.
After installing Composer and preparing your chart dependencies, check that committed Compose output still agrees with its chart and profile:
poetry run composer --chart ./path/to/chart \
--profile compose.profile.yaml --output compose.yaml --check--check leaves files untouched and exits with 1 for drift or 2 for invalid input.
A matching configuration returns 0. Use --compare to check an independent reference
and --report to save compilation provenance; see comparison and reports.
The reusable helm-composer pre-commit hook regenerates
Compose when chart inputs change. See hook setup for
configuration and handling generated changes.
This repository's CircleCI workflow runs linting, strict typing, docstring validation and compiler tests with real Helm fixtures.
| Location | Responsibility |
|---|---|
pkg/composer/ |
CLI, profile resolution and compilation. |
pkg/composer/ast/ |
Kubernetes and Compose models and conversion utilities. |
pkg/composer/schemas/ |
Bundled runtime profile and Compose JSON Schemas. |
tests/ |
Compiler unit tests and real Helm rendering tests. |
.circleci/config.yml |
Portable compiler verification workflow. |
.pre-commit-hooks.yaml |
Reusable Compose generation hook. |
docs/ |
Usage, profile reference and contributor documentation. |
poetry run python -m unittest discover -s testsSee development for the full checks, pre-commit setup, package builds, compiler internals and optional application integration tests.