WARNING

The version of the "master" branch, v2.x, will no longer be supported once the "develop" branch (v3.x) is merged. Version 3.x brings a large number of modifications and fixes, such as support for static files, improved generation of the values.yaml file, better support for dependencies, etc. If you'd like to help speed up development of version 3, please refer to the "develop" branch.

Warning! Katenary will be soon go to release v3. This is a full rewrite of the tool, using official go-compose and kubernetes libraries to generate object. The current state of the source code started to be unmaintainable and too complex to fix. I decided to revise and recreate the tool. This will change some commands and the labels to use.

The current v2 version will be frozen to the current state.

No panic, the v3 detects the v2 syntax and will not break your helm chart.

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

Important Note: Katenary is a tool to help to build 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

Install

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.

You can of course get the binary with go install -u github.com/metal3d/katenary/cmd/katenary/... but the main branch is continuously updated. It's preferable to use releases.

You can use this commands on Linux:

sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install.sh)

Else... Build yourself

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

If that goes wrong, you can use your local Go compiler:

make build GO=local

# To force OS or architecture
make build GO=local GOOS=linux GOARCH=arm64

Then place the katenary binary file inside your PATH.

Tips

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 <(katenary 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...)

Usage

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 -c docker-compose.yml
    katenary convert -c docker-compose.yml -o ./charts

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

Usage:
  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
  upgrade     Upgrade katenary to the latest version if available
  version     Display version

Flags:
  -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 on service (using the first port)
• env_file list will create a configMap object per environemnt file (⚠ to-do: 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 an ingress
  • katenary.io/mapenv: |: allow mapping environment to something else than the given value in the compose file

Exemple of a possible docker-compose.yaml file:

version: "3"
services:
    webapp:
        image: php:7-apache
        environment:
            # note that "database" is a service name
            DB_HOST: database
        expose:
            - 80
        depends_on:
            # this will create a init container waiting for 3306 port
            # because it's the "exposed" port
            - database
        labels:
            # expose the port 80 as an ingress
            katenary.io/ingress: 80
            # make adaptations, DB_HOST environment is actually the service name
            # to hit (note the yaml style, start with "|")
            katenary.io/mapenv: |
              DB_HOST: {{ .Release.Name }}-database
    database:
        image: mariadb:10
        env_file:
            # this will create a configMap
            - my_env.env
        environment:
            MARIADB_USER: foo
            MARIADB_ROOT_PASSWORD: foobar
            MARIADB_PASSWORD: bar
        labels:
            # no need to declare this port in docker-compose
            # but katenary will need it
            katenary.io/ports: 3306
            # these variables are secrets
            katenary.io/secret-vars: MARIADB_ROOT_PASSWORD, MARIADB_PASSWORD

Labels

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

# Labels
katenary.io/ignore               : ignore the container, it will not yied any object in the helm chart (bool)
katenary.io/secret-vars          : secret variables to push on a secret file (coma separated)
katenary.io/secret-envfiles      : set the given file names as a secret instead of configmap (coma separated)
katenary.io/mapenv               : map environment variable to a template string (yaml style, object)
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/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 (string)
katenary.io/volume-from          : specifies that the volumes to be mounted from the given service (yaml style)
katenary.io/empty-dirs           : specifies that the given volume names should be "emptyDir" instead of
                                   persistentVolumeClaim (coma separated)
katenary.io/crontabs             : specifies a cronjobs to create (yaml style, array) - this will create a
                                   cronjob, a service account, a role and a rolebinding to start the command with "kubectl"
                                   The form is the following:
                                   - command: the command to run
                                     schedule: the schedule to run the command (e.g. "@daily" or "*/1 * * * *")
                                     image: the image to use for the command (default to "bitnami/kubectl")
                                     allPods: true if you want to run the command on all pods (default to false)
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://[ignored][:port][/path] to specify an http healthcheck
                                     -> tcp://[ignored]: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 boat and the anchor.

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