Katenary is a tool to help transforming docker-compose files to a working Helm Chart for Kubernetes.

Important Note Katenary is a tool to help building Helm Chart from a docker-compose file, but docker-compose doesn’t propose as many features as what can do Kubernetes. So, we strongly recommend to use Katenary as a “bootstrap” tool and then to manually enhance the generated helm chart.

This project is partially made at Smile

Smile Logo


You can download the binaries from the Release section. Copy the binary and rename it to katenary. Place the binary inside your PATH. You should now be able to call the katenary command.

If you’ve got podman or docker, you can build katenary by using:

make build

You can then install it with:

make install

It will use the default PREFIX (~/.local/) to install the binary in the bin subdirectory. You can force the PREFIX value at install time, but maybe you need to use “sudo”:

sudo make install PREFIX=/usr/local


We strongly recommand to add the “completion” call to you SHELL using the common bashrc, or whatever the profile file you use.

E.g. :

# bash in ~/.bashrc file
source <(katenary completion bash)
# if the documentation breaks a bit your completion:
source <(katenary completion bash --no-description)

# zsh in ~/.zshrc
source <(helm completion zsh)

# fish in ~/.config/fish/config.fish
katenary completion fish | source

# powershell (as we don't provide any support on Windows yet, please avoid this...)


Katenary aims to be a tool to convert docker-compose files to Helm Charts. 
It will create deployments, services, volumes, secrets, and ingress resources.
But it will also create initContainers based on depend_on, healthcheck, and other features.
It's not magical, sometimes you'll need to fix the generated charts.
The general way to use it is to call one of these commands:

    katenary convert
    katenary convert -f docker-compose.yml
    katenary convert -f docker-compose.yml -o ./charts

In case of, check the help of each command using:
    katenary <command> --help
    "katenary help <command>"

  katenary [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  convert     Convert docker-compose to helm chart
  help        Help about any command
  show-labels Show labels of a resource
  version     Display version

  -h, --help   help for katenary

Use "katenary [command] --help" for more information about a command.

Katenary will try to find a docker-compose.yaml or docker-compose.yml file inside the current directory. It will check *the existence of the chart directory to create a new Helm Chart inside a named subdirectory. Katenary will ask you if you want to delete it before recreating.

It creates a subdirectory inside chart that is named with the appname option (default is MyApp)

To respect the ability to install the same application in the same namespace, Katenary will create “variable” names like {{ .Release.Name }}-servicename. So, you will need to use some labels inside your docker-compose file to help katenary to build a correct helm chart.

What can be interpreted by Katenary:

  • Services with “image” section (cannot work with “build” section)
  • Named Volumes are transformed to persistent volume claims – note that local volume will break the transformation to Helm Chart because there is (for now) no way to make it working (see below for resolution)
  • if ports and/or expose section, katenary will create Services and bind the port to the corresponding container port
  • depends_on will add init containers to wait for the depending service (using the first port)
  • env_file list will create a configMap object per environemnt file (⚠ todo: the “to-service” label doesn’t work with configMap for now)
  • some labels can help to bind values, for example:
    • katenary.io/ingress: 80 will expose the port 80 in a ingress
    • katenary.io/env-to-service: VARNAME will convert the value to a variable {{ .Release.Name }}-VARNAME – it’s usefull when you want to pass the name of a service as a variable (think about the service name for mysql to pass to a container that wants to connect to this)

Exemple of a possible docker-compose.yaml file:

version: "3"
        image: php:7-apache
            # note that "database" is a service name
            DB_HOST: database
            - 80
            # this will create a init container waiting for 3306 port
            # because it's the "exposed" port
            - database
            # explain to katenary that "DB_HOST" value is variable (using release name)
            katenary.io/env-to-service: DB_HOST
            # expose the port 80 as an ingress
            katenary.io/ingress: 80
        image: mariadb:10
            # this will create a configMap
            - my_env.env
            MARIADB_ROOT_PASSWORD: foobar
            # no need to declare this port in docker-compose
            # but katenary will need it
            katenary.io/ports: 3306


These labels could be found by katenary show-labels, and can be placed as “labels” inside your docker-compose file:

katenary.io/secret-envfiles      : set the given file names as a secret instead of configmap
katenary.io/ports                : set the ports to expose as a service (coma separated)
katenary.io/ingress              : set the port to expose in an ingress (coma separated)
katenary.io/env-to-service       : specifies that the environment variable points on a service name (coma separated)
katenary.io/configmap-volumes    : specifies that the volumes points on a configmap (coma separated)
katenary.io/same-pod             : specifies that the pod should be deployed in the same pod than the given service name
katenary.io/empty-dirs           : specifies that the given volume names should be "emptyDir" instead of persistentVolumeClaim (coma separated)
katenary.io/healthcheck          : specifies that the container should be monitored by a healthcheck, **it overrides the docker-compose healthcheck**. 
                                   You can use these form of label values:
                                   - "http://[not used address][:port][/path]" to specify an http healthcheck
                                   - "tcp://[not used address]:port" to specify a tcp healthcheck
                                   - other string is condidered as a "command" healthcheck

What a name…

Katenary is the stylized name of the project that comes from the “catenary” word.

A catenary is a curve formed by a wire, rope, or chain hanging freely from two points that are not in the same vertical line. For example, the anchor chain between a bot and the anchor.

This “curved link” represents what we try to do, the project is a “streched link from docker-compose to helm chart”.


View Github