[](https://katenary.readthedocs.io/latest/?badge=latest)
[](https://goreportcard.com/report/github.com/Katenary/katenary)
[](https://github.com/Katenary/katenary/releases)
[](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
[](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
[](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
[](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
π 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](https://www.kleegroup.com). 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](https://github.com/metal3d).
## Install
You can download the binaries from the [Release](https://github.com/Katenary/katenary/releases) 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/Katenary/katenary/cmd/katenary/...` but the `main` branch
is continuously updated. It's preferable to use releases.
You can use this commands on Linux:
```bash
sh <(curl -sSL https://raw.githubusercontent.com/Katenary/katenary/master/install.sh)
```
## Or, build yourself
If you've got `podman` or `docker`, you can build `katenary` by using:
```bash
make build
```
You can then install it with:
```bash
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":
```bash
sudo make install PREFIX=/usr/local
```
If that goes wrong, you can use your local Go compiler:
```bash
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
# 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
```text
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:
```yaml
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
# make adaptations, DB_HOST environment is actually the service name
katenary.v3/map-env: |-
DB_HOST: '{{ .Release.Name }}-database'
# get the values from the "database" service
# this will use the database secrets and environment,
# see the "database" service to see the values
katenary.v3/values-from: |-
DB_USER: database.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:
```text
To get more information about a label, use `katenary help-label
e.g. katenary help-label dependencies
katenary.v3/configmap-files: []string Inject files as Configmap.
katenary.v3/cronjob: object Create a cronjob from the service.
katenary.v3/dependencies: []object Add Helm dependencies to the service.
katenary.v3/description: string Description of the service
katenary.v3/env-from: []string Add environment variables from another service.
katenary.v3/exchange-volumes: []object 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: map[string]string Map env vars from the service to the deployment.
katenary.v3/ports: []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: []string Env vars to be set as secrets.
katenary.v3/values: []string or map[string]string 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:
```yaml
services:
web:
image: nginx:latest
katenary.v3/ingress: |-
hostname: myapp.example.com
port: 80
```
You can remove the labels, and use a `katenary.yaml` file:
```yaml
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/Katenary/katenary/refs/heads/master/katenary.json`
It's easy to configure in [LazyVim](https://www.lazyvim.org/), using `nvim-lspconfig`,
create a Lua file in your `plugins` directory, or apply the settings as the example below:
```lua
-- yaml.lua
return {
{
"neovim/nvim-lspconfig",
opts = {
servers = {
yamlls = {
settings = {
yaml = {
schemas = {
["https://raw.githubusercontent.com/Katenary/katenary/master/katenary.json"] = "katenary.yaml",
},
},
},
},
},
},
},
}
```
Use this address to validate the `katenary.yaml` file in VSCode:
```json
{
"yaml.schemas": {
"https://raw.githubusercontent.com/Katenary/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.