🚀 Unleash Productivity with Katenary! 🚀

Tired of manual conversions? Katenary harnesses the labels from your "compose" file to craft complete Helm Charts effortlessly, saving you time and energy.

🛠️ Simple automated CLI: Katenary handles the grunt work, generating everything needed for seamless service binding and Helm Chart creation.

💡 Effortless Efficiency: You only need to add labels when it's necessary to precise things. Then call katenary convert and let the magic happen.

What ?

Katenary is a tool to help to transform compose (docker compose, podman compose, nerdctl compose, ...) files to a working Helm Chart for Kubernetes.

Today, it's partially developed in collaboration with Klee Group. Note that Katenary is and will stay an open source and free (as freedom) project. We are convinced that the best way to make it better is to share it with the community.

The main developer is Patrice FERLET.

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)

Or, 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 recommend adding 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

# experimental
# 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
  schema            Print the schema of the katenary file
  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.

Example of a possible docker-compose.yaml file:

services:
  webapp:
    image: php:7-apache
    environment:
      # note that "database" is a "compose" service name
      # so we need to adapt it with the map-env label
      DB_HOST: database
      # a pitty to repeat this values, isn't it?
      # so, let's change them with "values-from" label
      DB_USER: foo
      DB_PASSWORD: bar
    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
      katenary.v3/map-env: |-
        # make adaptations, DB_HOST environment is actually the service name
        DB_HOST: '{{ .Release.Name }}-database'
      katenary.v3/values-from: |-
        # get the values from the "database" service
        # this will use the databas secret, see below
        DB_USER: databse.MARIADB_USER
        DB_PASSWORD: database.MARIADB_PASSWORD

    database:
      image: mariadb:10
      env_file:
        # this valuse will be added in 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/exchange-volumes:	list of objects		Add exchange volumes (empty directory on the node) to share data
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
katenary.v3/values-from:	map[string]string	Add values from another service.

Katenary.yaml file and schema validation

Instead of using labels inside the docker-compose file, you can use a katenary.yaml file to define the labels. This file is simpler to read and maintain, but you need to keep it up-to-date with the docker-compose file.

For example, instead of using this:

services:
  web:
    image: nginx:latest
    katenary.v3/ingress: |-
      hostname: myapp.example.com
      port: 80

You can remove the labels, and use a kanetary.yaml file:

web:
  ingress:
    hostname: myapp.example.com
    port: 80

To validate the katenary.yaml file, you can use the JSON schema using the "master" raw content:

https://raw.githubusercontent.com/metal3d/katenary/refs/heads/master/katenary.json

It's easy to configure in LazyVim, using nvim-lspconfig, create a Lua file in your plugins directory, or apply the settings as the example below:

-- yaml.lua

return {
  {
    "neovim/nvim-lspconfig",
    opts = {
      servers = {
        yamlls = {
          settings = {
            yaml = {
              schemas = {
                ["https://raw.githubusercontent.com/metal3d/katenary/master/katenary.json"] = "katenary.yaml",
              },
            },
          },
        },
      },
    },
  },
}

Use this address to validate the katenary.yaml file in VSCode:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/metal3d/katenary/master/katenary.json": "katenary.yaml"
  }
}

You can, of course, replace the master with a specific tag or branch.

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 stretched link from docker-compose to helm chart.