Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metal3d/katenary
Convert docker and podamn compose to a configurable helm chart
https://github.com/metal3d/katenary
compose docker docker-compose helm helmcha kubernetes podman
Last synced: about 1 month ago
JSON representation
Convert docker and podamn compose to a configurable helm chart
- Host: GitHub
- URL: https://github.com/metal3d/katenary
- Owner: metal3d
- License: mit
- Created: 2022-02-17T08:41:58.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-05-06T19:13:41.000Z (5 months ago)
- Last Synced: 2024-05-12T18:13:56.493Z (4 months ago)
- Topics: compose, docker, docker-compose, helm, helmcha, kubernetes, podman
- Language: Go
- Homepage:
- Size: 983 KB
- Stars: 121
- Watchers: 8
- Forks: 11
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> 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](https://www.smile.eu)
# Install
You can download the binaries from the [Release](https://github.com/metal3d/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/metal3d/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/metal3d/katenary/master/install.sh)
```
# Else... 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 recommand to add 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
# 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 --help
or
"katenary help "
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:
```yaml
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".