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.

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 is a tool to convert compose files to Helm Charts.

Each [command] and subcommand has got an "help" and "--help" flag to show more information.

Usage:
  katenary [command]

Examples:
  katenary convert -c docker-compose.yml -o ./charts

Available Commands:
  completion        Generates completion scripts
  convert           Converts a docker-compose file to a Helm Chart
  hash-composefiles Print the hash of the composefiles
  help              Help about any command
  help-labels       Print the labels help for all or a specific label
  version           Print the version number of Katenary

Flags:
  -h, --help      help for katenary
  -v, --version   version 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, see examples below

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.v3/ingress: |-
                hostname: myapp.example.com
                port: 80
            # make adaptations, DB_HOST environment is actually the service name
            # to hit (note the yaml style, start with "|")
            katenary.v3/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.v3/ports: |-
                - 3306
            # these variables are secrets
            katenary.v3/secrets: |-
                - MARIADB_ROOT_PASSWORD
                - MARIADB_PASSWORD

Labels

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

To get more information about a label, use `katenary help-label <name_without_prefix>
e.g. katenary help-label dependencies

katenary.v3/configmap-files:	list of strings		Add files to the configmap.
katenary.v3/cronjob:		object			Create a cronjob from the service.
katenary.v3/dependencies:	list of objects		Add Helm dependencies to the service.
katenary.v3/description:	string			Description of the service
katenary.v3/env-from:		list of strings		Add environment variables from antoher service.
katenary.v3/health-check:	object			Health check to be added to the deployment.
katenary.v3/ignore:		bool			Ignore the service
katenary.v3/ingress:		object			Ingress rules to be added to the service.
katenary.v3/main-app:		bool			Mark the service as the main app.
katenary.v3/map-env:		object			Map env vars from the service to the deployment.
katenary.v3/ports:		list of uint32		Ports to be added to the service.
katenary.v3/same-pod:		string			Move the same-pod deployment to the target deployment.
katenary.v3/secrets:		list of string		Env vars to be set as secrets.
katenary.v3/values:		list of string or map	Environment variables to be added to the values.yaml

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".