katenary/README.md

<div style="text-align:center; margin: auto 0 4em 0" align="center">
<img src="./doc/docs/statics/logo-vertical.svg" alt="Katenary Logo" style="max-width: 90%" align="center"/>
</div>

<div style="text-align:center; margin: auto 0 4em 0" align="center">

[![Documentation Status](https://readthedocs.org/projects/katenary/badge/?version=latest)](https://katenary.readthedocs.io/en/latest/?badge=latest)
[![Go Report Card](https://goreportcard.com/badge/github.com/Katenary/katenary)](https://goreportcard.com/report/github.com/Katenary/katenary)
[![GitHub release](https://img.shields.io/github/v/release/Katenary/katenary)](https://github.com/Katenary/katenary/releases)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=metal3d_katenary&metric=coverage)](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=metal3d_katenary&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=metal3d_katenary&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)

[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=metal3d_katenary&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=metal3d_katenary)

</div>

<div style="text-align:center; margin: auto 0 4em 0" align="center">
<h3>🚀 Unleash Productivity with Katenary! 🚀</h3>
</div>

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 <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:

```yaml
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:

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