Katenary/katenary
2
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

feat(doc): Enhancement, cleanup, add package instructions
All checks were successful
Go-Tests / tests (pull_request) Successful in 1m48s
Details
Go-Tests / sonar (pull_request) Successful in 52s
Details
Go-Tests / tests (push) Successful in 3m30s
Details
Go-Tests / sonar (push) Successful in 50s
Details

Browse Source 
- remove trailing spaces
- add instruction for packages
- reindent YAML examples
- remove section telling that there is no config files, as
`katenary.yaml` file can now be used
This commit is contained in:
Patrice Ferlet
2025-08-29 13:24:32 +02:00
parent 6c2e8fa9b2
commit 6cd1c92997
9 changed files with 297 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -37,6 +37,24 @@ The main developer is [Patrice FERLET](https://repo.katenary.io/metal3d).
## Install ## Install
### Package from repository and Windows installer
You can find Linux packages repository and Windows installer in the [packages page](https://repo.katenary.io/Katenary/katenary/packages).
> Note for Fedora >= 42, the repository instructions are not up-to-date. You should use:
>
> ```bash
> dnf config-manager addrepo \
> --from-repofile https://repo.katenary.io/Katenary/katenary/fedora/katenary.repo
> dnf install katenary
> ```
- Windows users, go to the "generic" packages page, and download the `setup.exe` file.
- macOS users, please use the "`darwin`" binary. An experimental package is in preparation.
- FreedBSD users, please use the "`freebsd`" package in "generic" packages page.
### Binary installation
You can download the binaries from the [Release](https://repo.katenary.io/Katenary/katenary/releases) section. Copy the binary You can download the binaries from the [Release](https://repo.katenary.io/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. and rename it to `katenary`. Place the binary inside your `PATH`. You should now be able to call the `katenary` command.
@@ -54,7 +72,7 @@ go install -u katenary.io/cmd@latest
go install -u katenary.io/cmd@v3.0.0 go install -u katenary.io/cmd@v3.0.0
``` ```
## Or, build yourself ### Or, build yourself
If you've got `podman` or `docker`, you can build `katenary` by using: If you've got `podman` or `docker`, you can build `katenary` by using:
@@ -69,7 +87,7 @@ make install
``` ```
It will use the default PREFIX (`~/.local/`) to install the binary in the `bin` subdirectory. You can force the PREFIX 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": value at install time, but maybe you need to use "`sudo`":
```bash ```bash
sudo make install PREFIX=/usr/local sudo make install PREFIX=/usr/local

2
doc/.editorconfig Normal file
View File

@@ -0,0 +1,2 @@
[*.md]
indent_size=2

8
doc/docs/coding.md
View File

@@ -36,14 +36,14 @@ flowchart TD
Val[Values files]:::outputs@{shape: curv-trap} Val[Values files]:::outputs@{shape: curv-trap}
PVC:::outputs@{shape: curv-trap} PVC:::outputs@{shape: curv-trap}
S[Service]:::outputs@{shape: curv-trap} S[Service]:::outputs@{shape: curv-trap}
A[Compose file]:::inputs --> B[Compose parser] A[Compose file]:::inputs --> B[Compose parser]
B --> G[Generator] B --> G[Generator]
G --> P[Ports exposed to services] ---> S G --> P[Ports exposed to services] ---> S
G ------> H G ------> H
G --> C --> D G --> C --> D
G ------> Val G ------> Val
G ....-> M[Merge Continainers if same-pod] G ....-> M[Merge Continainers if same-pod]
M ..-> C M ..-> C
G --> E[Environment variables] ----> Secrets & ConfigMap G --> E[Environment variables] ----> Secrets & ConfigMap
G--> V[Bind volumes] -------> PVC G--> V[Bind volumes] -------> PVC
@@ -51,7 +51,7 @@ flowchart TD
Secrets & ConfigMap -- create envFrom --> D Secrets & ConfigMap -- create envFrom --> D
V -- bind volumes --> D V -- bind volumes --> D
``` ```
If the declaration of a container is to be integrated into another pod (via the `same-pod` label), this `Deployment` and If the declaration of a container is to be integrated into another pod (via the `same-pod` label), this `Deployment` and
@@ -92,7 +92,7 @@ For each source container linked to the destination:
- we then copy the service port to the destination service - we then copy the service port to the destination service
- we finally remove the source service and deployment - we finally remove the source service and deployment
> The `Configmap`, secrets, variables... are kept. > The `Configmap`, secrets, variables, and so on, are kept.
It finally computes the `helper` file. It finally computes the `helper` file.

18
doc/docs/faq.md
View File

@@ -6,9 +6,9 @@ The main author[^1] of Katenary is a big fan of Podman, Docker and makes a huge
daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose. daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose.
He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts. He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts.
Kompose was a good option. But the lacks of some options and configuration for the output Helm chart made him think [Kompose](https://kompose.io/) was a good option. But the lacks of some options and configuration for the output Helm
about creating a new tool. He wanted to have a tool that could generate a complete Helm chart, with a lot of options chart made him think about creating a new tool. He wanted to have a tool that could generate a complete Helm chart,
and flexibility. with a lot of options and flexibility.
[^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka Metal3d, Tech Lead and DevOps Engineer at Klee Group. [^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka Metal3d, Tech Lead and DevOps Engineer at Klee Group.
@@ -51,15 +51,6 @@ many indentation levels in the YAML file.
It is also more flexible. You can add or remove labels without changing the others. It is also more flexible. You can add or remove labels without changing the others.
## Why not using a configuration file?
The idea was to keep the configuration at a same place, and using the go-compose library to read the labels. It's
easier to have a single file to manage.
By the way, Katenary auto accepts a `compose.katenary.yaml` file in the same directory. It's a way to separate the
configuration from the compose file. It uses
the [overrides' mechanism](https://docs.docker.com/compose/multiple-compose-files/merge/) like "compose" does.
## Why not developing with Rust? ## Why not developing with Rust?
Seriously... Seriously...
@@ -99,9 +90,6 @@ us by giving us some money, or by giving us some time of your developers, or lea
### If you're an individual ### If you're an individual
All donators will be listed on the website and in the documentation. You can give us some money by using
the [GitHub Sponsors]()
All main contributors[^3] will be listed on the website and in the documentation. All main contributors[^3] will be listed on the website and in the documentation.
> If you want to be anonymous, please tell us. > If you want to be anonymous, please tell us.

48
doc/docs/index.md
View File

@@ -44,30 +44,52 @@ The main developer is [Patrice FERLET](https://repo.katenary.io/metal3d).
The project source The project source
code is hosted on the [:fontawesome-brands-git: Katenary Repository](https://repo.katenary.io/Katenary/katenary). code is hosted on the [:fontawesome-brands-git: Katenary Repository](https://repo.katenary.io/Katenary/katenary).
## Install Katenary # Install Katenary
Katenary is developed using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language. ## Linux / Windows package distribution or setup.exe
The binary is statically linked, so you can simply download it from the [release
page](https://github.com/Katenary/katenary/releases) of the project in GitHub. The simplest way to install Katenary is to install the package or use Windows installer from the page [packages page](https://repo.katenary.io/Katenary/katenary/packages).
You will find packages and instructions to install the repository for your distribution for :
- RPM (Fedora, Rocky, Alma, OpenSUSE...)
- DEB (Debian, Ubuntu, Mint...)
- Arch Linux (AUR)
- Windows (in the "generic" packages page, use the "setup" file)
!!! Note "Fedora >= 42"
The instruction is not updated for newest version of `dnf`. If the command to add the repository doesn't work, you can
try:
```bash
dnf config-manager addrepo \
--from-repofile https://repo.katenary.io/api/packages/Katenary/rpm.repo
```
As Katenary is developed using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language the binary is statically
linked, so you can simply download it from the [generic package page](https://repo.katenary.io/Katenary/katenary/packages) and get the version
which is compatible with your operating system and architecture.
You need to select the right binary for your operating system and architecture, and copy the binary in a directory You need to select the right binary for your operating system and architecture, and copy the binary in a directory
that is in your `PATH`. that is in your `PATH`.
If you are a Linux user, you can use the "one line installation command" which will download the binary in your ## Linux - one line installation command
If you are a Linux user, you can use the "one line installation command" which will download the **binary** in your
`$HOME/.local/bin` directory if it exists. `$HOME/.local/bin` directory if it exists.
```bash ```bash
sh <(curl -sSL https://repo.katenary.io/Katenary/katenary/raw/branch/master/install.sh) sh <(curl -sSL https://repo.katenary.io/Katenary/katenary/raw/branch/master/install.sh)
``` ```
!!! Info "Upgrading is integrated to the `katenary` command" ## Compile from sources
Katenary propose a `upgrade` sub-command to update the current binary to the latest stable release.
Of course, you need to install Katenary once :smile: You can, of course, compile Katenary from sources.
!!! Note "You prefer to compile it, no need to install Go" !!! Note "You prefer to compile it, no need to install Go"
You can also build and install it yourself, the provided Makefile has got a `build` command that uses `podman` or
`docker` to build the binary. You can also build and install it yourself, the provided Makefile has got a `build` command that uses `podman` or
`docker` to build the binary.
So, you don't need to install Go compiler :+1:. So, you don't need to install Go compiler :+1:.
@@ -107,7 +129,7 @@ source <(katenary completion bash)
Add this line in you `~/.profile`, `~/.bash_aliases` or `~/.bashrc` file to have completion at startup. Add this line in you `~/.profile`, `~/.bash_aliases` or `~/.bashrc` file to have completion at startup.
## What a name # What a name
A catenary is the curve that a hanging chain or cable assumes under its own weight when supported only at its ends. A catenary is the curve that a hanging chain or cable assumes under its own weight when supported only at its ends.
I, the maintainer, decided to name "Katenary" this project because it's like a chain that links a boat to a dock. I, the maintainer, decided to name "Katenary" this project because it's like a chain that links a boat to a dock.
@@ -119,7 +141,7 @@ Anyway, it's too late to change the name now :smile:
I spent time to find it :wink: I spent time to find it :wink:
## Special thanks to # Special thanks to
I really want to thank all the contributors, testers, and of course, the authors of the packages and tools that are used I really want to thank all the contributors, testers, and of course, the authors of the packages and tools that are used
in this project. There is too many to list here. Katenary can work because of all these people. Open source is a great in this project. There is too many to list here. Katenary can work because of all these people. Open source is a great
@@ -157,6 +179,6 @@ thing! :heart:
<a href="https://www.mkdocs.org/" target="_blank">MkDocs</a> using <a <a href="https://www.mkdocs.org/" target="_blank">MkDocs</a> using <a
href="https://squidfunk.github.io/mkdocs-material/" target="_blank">Material for MkDocs</a> theme template. href="https://squidfunk.github.io/mkdocs-material/" target="_blank">Material for MkDocs</a> theme template.
## License # License
Katenary is an open source project under the MIT license. You can use it, modify it, and distribute it as you want. Katenary is an open source project under the MIT license. You can use it, modify it, and distribute it as you want.

76
doc/docs/labels.md
View File

@@ -6,9 +6,9 @@ While compose labels are string, we can use _here-doc_ syntax using `|` to use Y
```yaml ```yaml
label-name: |- label-name: |-
# this is actually a multiline string here # this is actually a multiline string here
key1: value1 key1: value1
key2: value2 key2: value2
``` ```
Katenary will try to _Unmarshal_ these labels. Katenary will try to _Unmarshal_ these labels.
@@ -46,17 +46,17 @@ Inject files as Configmap.
**Type**: `[]string` **Type**: `[]string`
It makes a file or directory to be converted to one or more ConfigMaps It makes a file or directory to be converted to one or more ConfigMaps
and mounted in the pod. The file or directory is relative to the and mounted in the pod. The file or directory is relative to the
service directory. service directory.
If it is a directory, all files inside it are added to the ConfigMap. If it is a directory, all files inside it are added to the ConfigMap.
If the directory as subdirectories, so one configmap per subpath are created. If the directory as subdirectories, so one ConfigMap per sub-path are created.
!!! Warning !!! Warning
It is not intended to be used to store an entire project in configmaps. It is not intended to be used to store an entire project in ConfigMaps.
It is intended to be used to store configuration files that are not managed It is intended to be used to store configuration files that are not managed
by the application, like nginx configuration files. Keep in mind that your by the application, like nginx configuration files. Keep in mind that your
project sources should be stored in an application image or in a storage. project sources should be stored in an application image or in a storage.
@@ -80,8 +80,9 @@ Create a cronjob from the service.
This adds a cronjob to the chart. This adds a cronjob to the chart.
The label value is a YAML object with the following attributes: The label value is a YAML object with the following attributes:
- command: the command to be executed
- schedule: the cron schedule (cron format or @every where "every" is a - command: the command to be executed
- schedule: the cron schedule (cron format or @every where "every" is a
duration like 1h30m, daily, hourly...) duration like 1h30m, daily, hourly...)
- rbac: false (optionnal), if true, it will create a role, a rolebinding and - rbac: false (optionnal), if true, it will create a role, a rolebinding and
a serviceaccount to make your cronjob able to connect the Kubernetes API a serviceaccount to make your cronjob able to connect the Kubernetes API
@@ -90,9 +91,9 @@ The label value is a YAML object with the following attributes:
```yaml ```yaml
labels: labels:
katenary.v3/cronjob: |- katenary.v3/cronjob: |-
command: echo "hello world" command: echo "hello world"
schedule: "* */1 * * *" # or @hourly for example schedule: "* */1 * * *" # or @hourly for example
``` ```
@@ -102,8 +103,8 @@ Add Helm dependencies to the service.
**Type**: `[]object` **Type**: `[]object`
Set the service to be, actually, a Helm dependency. This means that the Set the service to be, actually, a Helm dependency. This means that the
service will not be exported as template. The dependencies are added to service will not be exported as template. The dependencies are added to
the Chart.yaml file and the values are added to the values.yaml file. the Chart.yaml file and the values are added to the values.yaml file.
It's a list of objects with the following attributes: It's a list of objects with the following attributes:
@@ -115,12 +116,12 @@ It's a list of objects with the following attributes:
!!! Info !!! Info
Katenary doesn't update the helm depenedencies by default. Katenary doesn't update the helm depenedencies by default.
Use `--helm-update` (or `-u`) flag to update the dependencies. Use `--helm-update` (or `-u`) flag to update the dependencies.
example: <code>katenary convert -u</code> example: <code>katenary convert -u</code>
By setting an alias, it is possible to change the name of the dependency By setting an alias, it is possible to change the name of the dependency
in values.yaml. in values.yaml.
**Example:** **Example:**
@@ -149,7 +150,7 @@ Description of the service
**Type**: `string` **Type**: `string`
This replaces the default comment in values.yaml file to the given description. This replaces the default comment in values.yaml file to the given description.
It is useful to document the service and configuration. It is useful to document the service and configuration.
The value can be set with a documentation in multiline format. The value can be set with a documentation in multiline format.
@@ -178,15 +179,15 @@ It adds environment variables from another service to the current service.
service1: service1:
image: nginx:1.19 image: nginx:1.19
environment: environment:
FOO: bar FOO: bar
service2: service2:
image: php:7.4-fpm image: php:7.4-fpm
labels: labels:
# get the congigMap from service1 where FOO is # get the congigMap from service1 where FOO is
# defined inside this service too # defined inside this service too
katenary.v3/env-from: |- katenary.v3/env-from: |-
- myservice1 - myservice1
``` ```
@@ -196,7 +197,7 @@ Add exchange volumes (empty directory on the node) to share data
**Type**: `[]object` **Type**: `[]object`
This label allows sharing data between containres. The volume is created in This label allows sharing data between containres. The volume is created in
the node and mounted in the pod. It is useful to share data between containers the node and mounted in the pod. It is useful to share data between containers
in a "same pod" logic. For example to let PHP-FPM and Nginx share the same direcotory. in a "same pod" logic. For example to let PHP-FPM and Nginx share the same direcotory.
@@ -207,6 +208,7 @@ This will create:
- a `initContainer` for each definition - a `initContainer` for each definition
Fields: Fields:
- name: the name of the volume (manadatory) - name: the name of the volume (manadatory)
- mountPath: the path where the volume is mounted in the pod (optional, default is `/opt`) - mountPath: the path where the volume is mounted in the pod (optional, default is `/opt`)
- init: a command to run to initialize the volume with data (optional) - init: a command to run to initialize the volume with data (optional)
@@ -275,7 +277,7 @@ Ingress rules to be added to the service.
**Type**: `object` **Type**: `object`
Declare an ingress rule for the service. The port should be exposed or Declare an ingress rule for the service. The port should be exposed or
declared with `katenary.v3/ports`. declared with `katenary.v3/ports`.
**Example:** **Example:**
@@ -294,7 +296,7 @@ Mark the service as the main app.
**Type**: `bool` **Type**: `bool`
This makes the service to be the main application. Its image tag is This makes the service to be the main application. Its image tag is
considered to be the Chart appVersion and to be the defaultvalue in Pod considered to be the Chart appVersion and to be the defaultvalue in Pod
container image attribute. container image attribute.
@@ -309,7 +311,7 @@ ghost:
image: ghost:1.25.5 image: ghost:1.25.5
labels: labels:
# The chart is now named ghost, and the appVersion is 1.25.5. # The chart is now named ghost, and the appVersion is 1.25.5.
# In Deployment, the image attribute is set to ghost:1.25.5 if # In Deployment, the image attribute is set to ghost:1.25.5 if
# you don't change the "tag" attribute in values.yaml # you don't change the "tag" attribute in values.yaml
katenary.v3/main-app: true katenary.v3/main-app: true
``` ```
@@ -322,8 +324,8 @@ Map env vars from the service to the deployment.
**Type**: `map[string]string` **Type**: `map[string]string`
Because you may need to change the variable for Kubernetes, this label Because you may need to change the variable for Kubernetes, this label
forces the value to another. It is also particullary helpful to use a template forces the value to another. It is also particullary helpful to use a template
value instead. For example, you could bind the value to a service name value instead. For example, you could bind the value to a service name
with Helm attributes: with Helm attributes:
`{{ tpl .Release.Name . }}`. `{{ tpl .Release.Name . }}`.
@@ -349,7 +351,7 @@ Ports to be added to the service.
**Type**: `[]uint32` **Type**: `[]uint32`
Only useful for services without exposed port. It is mandatory if the Only useful for services without exposed port. It is mandatory if the
service is a dependency of another service. service is a dependency of another service.
**Example:** **Example:**
@@ -368,10 +370,10 @@ Move the same-pod deployment to the target deployment.
**Type**: `string` **Type**: `string`
This will make the service to be included in another service pod. Some services This will make the service to be included in another service pod. Some services
must work together in the same pod, like a sidecar or a proxy or nginx + php-fpm. must work together in the same pod, like a sidecar or a proxy or nginx + php-fpm.
Note that volume and VolumeMount are copied from the source to the target Note that volume and VolumeMount are copied from the source to the target
deployment. deployment.
**Example:** **Example:**
@@ -393,7 +395,7 @@ Env vars to be set as secrets.
**Type**: `[]string` **Type**: `[]string`
This label allows setting the environment variables as secrets. The variable This label allows setting the environment variables as secrets. The variable
is removed from the environment and added to a secret object. is removed from the environment and added to a secret object.
The variable can be set to the `katenary.v3/values` too, The variable can be set to the `katenary.v3/values` too,
@@ -418,14 +420,14 @@ Environment variables to be added to the values.yaml
**Type**: `[]string or map[string]string` **Type**: `[]string or map[string]string`
By default, all environment variables in the "env" and environment By default, all environment variables in the "env" and environment
files are added to configmaps with the static values set. This label files are added to ConfigMaps with the static values set. This label
allows adding environment variables to the values.yaml file. allows adding environment variables to the values.yaml file.
Note that the value inside the configmap is `{{ tpl vaname . }}`, so Note that the value inside the configmap is `{{ tpl vaname . }}`, so
you can set the value to a template that will be rendered with the you can set the value to a template that will be rendered with the
values.yaml file. values.yaml file.
The value can be set with a documentation. This may help to understand The value can be set with a documentation. This may help to understand
the purpose of the variable. the purpose of the variable.
**Example:** **Example:**
@@ -442,7 +444,7 @@ labels:
- TO_CONFIGURE - TO_CONFIGURE
# complex values, set as a template in values.yaml with a documentation # complex values, set as a template in values.yaml with a documentation
- A_COMPLEX_VALUE: |- - A_COMPLEX_VALUE: |-
This is the documentation for the variable to This is the documentation for the variable to
configure in values.yaml. configure in values.yaml.
It can be, of course, a multiline text. It can be, of course, a multiline text.
``` ```

152
doc/docs/usage.md
View File

@@ -34,18 +34,18 @@ For example. With "labels", you should do:
```yaml ```yaml
# in compose file # in compose file
services: services:
webapp: webapp:
image: php:7-apache image: php:7-apache
ports: ports:
- 8080:80 - 8080:80
environment: environment:
DB_HOST: database DB_HOST: database
labels: labels:
katenary.v3/ingress: |- katenary.v3/ingress: |-
hostname: myapp.example.com hostname: myapp.example.com
port: 8080 port: 8080
katenary.v3/map-env: |- katenary.v3/map-env: |-
DB_HOST: "{{ .Release.Name }}-database" DB_HOST: "{{ .Release.Name }}-database"
``` ```
Using a Katenary file, you can do: Using a Katenary file, you can do:
@@ -53,21 +53,21 @@ Using a Katenary file, you can do:
```yaml ```yaml
# in compose file, no need to add labels # in compose file, no need to add labels
services: services:
webapp: webapp:
image: php:7-apache image: php:7-apache
ports: ports:
- 8080:80 - 8080:80
environment: environment:
DB_HOST: database DB_HOST: database
# in katenary.yaml # in katenary.yaml
webapp: webapp:
ingress: ingress:
hostname: myapp.example.com hostname: myapp.example.com
port: 8080 port: 8080
map-env: map-env:
DB_HOST: "{{ .Release.Name }}-database" DB_HOST: "{{ .Release.Name }}-database"
``` ```
!!! Warning "YAML in multiline label" !!! Warning "YAML in multiline label"
@@ -129,8 +129,9 @@ After having installed `katenary`, the standard usage is to call:
It will search standard compose files in the current directory and try to create a helm chart in "chart" directory. It will search standard compose files in the current directory and try to create a helm chart in "chart" directory.
!!! Info !!! Info
Katenary uses the compose-go library which respects the Docker and Docker-Compose specification. Keep in mind that
it will find files exactly the same way as `docker-compose` and `podman-compose` do it. Katenary uses the compose-go library which respects the Docker and Docker-Compose specification. Keep in mind that
it will find files exactly the same way as `docker-compose` and `podman-compose` do it.
Of course, you can provide others files than the default with (cumulative) `-c` options: Of course, you can provide others files than the default with (cumulative) `-c` options:
@@ -141,7 +142,8 @@ Of course, you can provide others files than the default with (cumulative) `-c`
Katenary proposes a lot of labels to configure the helm chart generation, but some are very important. Katenary proposes a lot of labels to configure the helm chart generation, but some are very important.
!!! Info !!! Info
For more complete label usage, see [the labels page](labels.md).
For more complete label usage, see [the labels page](labels.md).
### Work with Depends On? ### Work with Depends On?
@@ -154,15 +156,15 @@ See this compose file:
version: "3" version: "3"
services: services:
webapp: webapp:
image: php:8-apache image: php:8-apache
depends_on: depends_on:
- database - database
database: database:
image: mariadb image: mariadb
environment: environment:
MYSQL_ROOT_PASSWORD: foobar MYSQL_ROOT_PASSWORD: foobar
``` ```
In this case, `webapp` needs to know the `database` port because the `depends_on` points on it and Kubernetes has not In this case, `webapp` needs to know the `database` port because the `depends_on` points on it and Kubernetes has not
@@ -173,18 +175,18 @@ So, instead of exposing the port in the compose definition, let's declare this t
version: "3" version: "3"
services: services:
webapp: webapp:
image: php:8-apache image: php:8-apache
depends_on: depends_on:
- database - database
database: database:
image: mariadb image: mariadb
environment: environment:
MYSQL_ROOT_PASSWORD: foobar MYSQL_ROOT_PASSWORD: foobar
labels: labels:
katenary.v3/ports: |- katenary.v3/ports: |-
- 3306 - 3306
``` ```
### Declare ingresses ### Declare ingresses
@@ -196,14 +198,14 @@ Katenary can create this resource for you. You just need to declare the hostname
```yaml ```yaml
services: services:
webapp: webapp:
image: ... image: ...
ports: 8080:5050 ports: 8080:5050
labels: labels:
katenary.v3/ingress: |- katenary.v3/ingress: |-
# the target port is 5050 wich is the "service" port # the target port is 5050 wich is the "service" port
port: 5050 port: 5050
hostname: myapp.example.com hostname: myapp.example.com
``` ```
Note that the port to bind is the one used by the container, not the used locally. This is because Katenary create a Note that the port to bind is the one used by the container, not the used locally. This is because Katenary create a
@@ -218,13 +220,13 @@ With a compose file, there is no problem as Docker/Podman allows resolving the n
```yaml ```yaml
services: services:
webapp: webapp:
image: php:7-apache image: php:7-apache
environment: environment:
DB_HOST: database DB_HOST: database
database: database:
image: mariadb image: mariadb
``` ```
Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times
@@ -232,16 +234,16 @@ in a namespace), so you need to "remap" the environment variable to the right on
```yaml ```yaml
services: services:
webapp: webapp:
image: php:7-apache image: php:7-apache
environment: environment:
DB_HOST: database DB_HOST: database
labels: labels:
katenary.v3/mapenv: |- katenary.v3/mapenv: |-
DB_HOST: "{{ .Release.Name }}-database" DB_HOST: "{{ .Release.Name }}-database"
database: database:
image: mariadb image: mariadb
``` ```
This label can be used to map others environment for any others reason. E.g. to change an informational environment This label can be used to map others environment for any others reason. E.g. to change an informational environment
@@ -249,13 +251,13 @@ variable.
```yaml ```yaml
services: services:
webapp: webapp:
#... #...
environment: environment:
RUNNING: docker RUNNING: docker
labels: labels:
katenary.v3/mapenv: |- katenary.v3/mapenv: |-
RUNNING: kubernetes RUNNING: kubernetes
``` ```
In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's

162
doc/share/man/man1/katenary.1
View File

@@ -1,7 +1,7 @@
'\" t '\" t
.\" Automatically generated by Pandoc 3.1.11.1 .\" Automatically generated by Pandoc 3.1.11.1
.\" .\"
.TH "Katenary" "1" "2025-08-21" "mkdocs-manpage v2.0.1" "Katenary helm chart generator" .TH "Katenary" "1" "2025-08-29" "mkdocs-manpage v2.0.1" "Katenary helm chart generator"
.SH Basic Usage .SH Basic Usage
Basically, you can use \f[CR]katenary\f[R] to transpose a docker\-compose file (or any compose file compatible with \f[CR]podman\-compose\f[R] and \f[CR]docker\-compose\f[R]) to a configurable Helm Chart. Basically, you can use \f[CR]katenary\f[R] to transpose a docker\-compose file (or any compose file compatible with \f[CR]podman\-compose\f[R] and \f[CR]docker\-compose\f[R]) to a configurable Helm Chart.
This resulting helm chart can be installed with \f[CR]helm\f[R] command to your Kubernetes cluster. This resulting helm chart can be installed with \f[CR]helm\f[R] command to your Kubernetes cluster.
@@ -38,18 +38,18 @@ With \[dq]labels\[dq], you should do:
.EX .EX
# in compose file # in compose file
services: services:
webapp: webapp:
image: php:7\-apache image: php:7\-apache
ports: ports:
\- 8080:80 \- 8080:80
environment: environment:
DB_HOST: database DB_HOST: database
labels: labels:
katenary.v3/ingress: |\- katenary.v3/ingress: |\-
hostname: myapp.example.com hostname: myapp.example.com
port: 8080 port: 8080
katenary.v3/map\-env: |\- katenary.v3/map\-env: |\-
DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq] DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
.EE .EE
.PP .PP
Using a Katenary file, you can do: Using a Katenary file, you can do:
@@ -57,21 +57,21 @@ Using a Katenary file, you can do:
.EX .EX
# in compose file, no need to add labels # in compose file, no need to add labels
services: services:
webapp: webapp:
image: php:7\-apache image: php:7\-apache
ports: ports:
\- 8080:80 \- 8080:80
environment: environment:
DB_HOST: database DB_HOST: database
# in katenary.yaml # in katenary.yaml
webapp: webapp:
ingress: ingress:
hostname: myapp.example.com hostname: myapp.example.com
port: 8080 port: 8080
map\-env: map\-env:
DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq] DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
.EE .EE
.PP .PP
YAML in multiline label YAML in multiline label
@@ -162,15 +162,15 @@ See this compose file:
version: \[dq]3\[dq] version: \[dq]3\[dq]
services: services:
webapp: webapp:
image: php:8\-apache image: php:8\-apache
depends_on: depends_on:
\- database \- database
database: database:
image: mariadb image: mariadb
environment: environment:
MYSQL_ROOT_PASSWORD: foobar MYSQL_ROOT_PASSWORD: foobar
.EE .EE
.PP .PP
In this case, \f[CR]webapp\f[R] needs to know the \f[CR]database\f[R] port because the \f[CR]depends_on\f[R] points on it and Kubernetes has not (yet) solution to check the database startup. In this case, \f[CR]webapp\f[R] needs to know the \f[CR]database\f[R] port because the \f[CR]depends_on\f[R] points on it and Kubernetes has not (yet) solution to check the database startup.
@@ -181,18 +181,18 @@ So, instead of exposing the port in the compose definition, let\[aq]s declare th
version: \[dq]3\[dq] version: \[dq]3\[dq]
services: services:
webapp: webapp:
image: php:8\-apache image: php:8\-apache
depends_on: depends_on:
\- database \- database
database: database:
image: mariadb image: mariadb
environment: environment:
MYSQL_ROOT_PASSWORD: foobar MYSQL_ROOT_PASSWORD: foobar
labels: labels:
katenary.v3/ports: |\- katenary.v3/ports: |\-
\- 3306 \- 3306
.EE .EE
.SS Declare ingresses .SS Declare ingresses
It\[aq]s very common to have an Ingress resource on web application to deploy on Kubernetes. It\[aq]s very common to have an Ingress resource on web application to deploy on Kubernetes.
@@ -203,14 +203,14 @@ You just need to declare the hostname and the port to bind.
.IP .IP
.EX .EX
services: services:
webapp: webapp:
image: ... image: ...
ports: 8080:5050 ports: 8080:5050
labels: labels:
katenary.v3/ingress: |\- katenary.v3/ingress: |\-
# the target port is 5050 wich is the \[dq]service\[dq] port # the target port is 5050 wich is the \[dq]service\[dq] port
port: 5050 port: 5050
hostname: myapp.example.com hostname: myapp.example.com
.EE .EE
.PP .PP
Note that the port to bind is the one used by the container, not the used locally. Note that the port to bind is the one used by the container, not the used locally.
@@ -223,29 +223,29 @@ With a compose file, there is no problem as Docker/Podman allows resolving the n
.IP .IP
.EX .EX
services: services:
webapp: webapp:
image: php:7\-apache image: php:7\-apache
environment: environment:
DB_HOST: database DB_HOST: database
database: database:
image: mariadb image: mariadb
.EE .EE
.PP .PP
Katenary prefixes the services with \f[CR]{{ .Release.Name }}\f[R] (to make it possible to install the application several times in a namespace), so you need to \[dq]remap\[dq] the environment variable to the right one. Katenary prefixes the services with \f[CR]{{ .Release.Name }}\f[R] (to make it possible to install the application several times in a namespace), so you need to \[dq]remap\[dq] the environment variable to the right one.
.IP .IP
.EX .EX
services: services:
webapp: webapp:
image: php:7\-apache image: php:7\-apache
environment: environment:
DB_HOST: database DB_HOST: database
labels: labels:
katenary.v3/mapenv: |\- katenary.v3/mapenv: |\-
DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq] DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
database: database:
image: mariadb image: mariadb
.EE .EE
.PP .PP
This label can be used to map others environment for any others reason. This label can be used to map others environment for any others reason.
@@ -254,13 +254,13 @@ to change an informational environment variable.
.IP .IP
.EX .EX
services: services:
webapp: webapp:
#... #...
environment: environment:
RUNNING: docker RUNNING: docker
labels: labels:
katenary.v3/mapenv: |\- katenary.v3/mapenv: |\-
RUNNING: kubernetes RUNNING: kubernetes
.EE .EE
.PP .PP
In the above example, \f[CR]RUNNING\f[R] will be set to \f[CR]kubernetes\f[R] when you\[aq]ll deploy the application with helm, and it\[aq]s \f[CR]docker\f[R] for \[dq]Podman\[dq] and \[dq]Docker\[dq] executions. In the above example, \f[CR]RUNNING\f[R] will be set to \f[CR]kubernetes\f[R] when you\[aq]ll deploy the application with helm, and it\[aq]s \f[CR]docker\f[R] for \[dq]Podman\[dq] and \[dq]Docker\[dq] executions.
@@ -271,9 +271,9 @@ While compose labels are string, we can use \f[I]here\-doc\f[R] syntax using \f[
.IP .IP
.EX .EX
label\-name: |\- label\-name: |\-
# this is actually a multiline string here # this is actually a multiline string here
key1: value1 key1: value1
key2: value2 key2: value2
.EE .EE
.PP .PP
Katenary will try to \f[I]Unmarshal\f[R] these labels. Katenary will try to \f[I]Unmarshal\f[R] these labels.
@@ -445,9 +445,9 @@ The label value is a YAML object with the following attributes: \- command: the
.IP .IP
.EX .EX
labels: labels:
katenary.v3/cronjob: |\- katenary.v3/cronjob: |\-
command: echo \[dq]hello world\[dq] command: echo \[dq]hello world\[dq]
schedule: \[dq]* */1 * * *\[dq] # or \[at]hourly for example schedule: \[dq]* */1 * * *\[dq] # or \[at]hourly for example
.EE .EE
.SS katenary.v3/dependencies .SS katenary.v3/dependencies
Add Helm dependencies to the service. Add Helm dependencies to the service.
@@ -527,7 +527,7 @@ It adds environment variables from another service to the current service.
service1: service1:
image: nginx:1.19 image: nginx:1.19
environment: environment:
FOO: bar FOO: bar
service2: service2:
image: php:7.4\-fpm image: php:7.4\-fpm
@@ -535,7 +535,7 @@ service2:
# get the congigMap from service1 where FOO is # get the congigMap from service1 where FOO is
# defined inside this service too # defined inside this service too
katenary.v3/env\-from: |\- katenary.v3/env\-from: |\-
\- myservice1 \- myservice1
.EE .EE
.SS katenary.v3/exchange\-volumes .SS katenary.v3/exchange\-volumes
Add exchange volumes (empty directory on the node) to share data Add exchange volumes (empty directory on the node) to share data

70
internal/generator/labels/katenaryLabelsDoc.yaml
View File

@@ -24,7 +24,7 @@
"main-app": "main-app":
short: "Mark the service as the main app." short: "Mark the service as the main app."
long: |- long: |-
This makes the service to be the main application. Its image tag is This makes the service to be the main application. Its image tag is
considered to be the Chart appVersion and to be the defaultvalue in Pod considered to be the Chart appVersion and to be the defaultvalue in Pod
container image attribute. container image attribute.
@@ -36,7 +36,7 @@
image: ghost:1.25.5 image: ghost:1.25.5
labels: labels:
# The chart is now named ghost, and the appVersion is 1.25.5. # The chart is now named ghost, and the appVersion is 1.25.5.
# In Deployment, the image attribute is set to ghost:1.25.5 if # In Deployment, the image attribute is set to ghost:1.25.5 if
# you don't change the "tag" attribute in values.yaml # you don't change the "tag" attribute in values.yaml
{{ .KatenaryPrefix }}/main-app: true {{ .KatenaryPrefix }}/main-app: true
type: "bool" type: "bool"
@@ -45,14 +45,14 @@
short: "Environment variables to be added to the values.yaml" short: "Environment variables to be added to the values.yaml"
long: |- long: |-
By default, all environment variables in the "env" and environment By default, all environment variables in the "env" and environment
files are added to configmaps with the static values set. This label files are added to ConfigMaps with the static values set. This label
allows adding environment variables to the values.yaml file. allows adding environment variables to the values.yaml file.
Note that the value inside the configmap is {{ "{{ tpl vaname . }}" }}, so Note that the value inside the configmap is {{ "{{ tpl vaname . }}" }}, so
you can set the value to a template that will be rendered with the you can set the value to a template that will be rendered with the
values.yaml file. values.yaml file.
The value can be set with a documentation. This may help to understand The value can be set with a documentation. This may help to understand
the purpose of the variable. the purpose of the variable.
example: |- example: |-
env: env:
@@ -66,7 +66,7 @@
- TO_CONFIGURE - TO_CONFIGURE
# complex values, set as a template in values.yaml with a documentation # complex values, set as a template in values.yaml with a documentation
- A_COMPLEX_VALUE: |- - A_COMPLEX_VALUE: |-
This is the documentation for the variable to This is the documentation for the variable to
configure in values.yaml. configure in values.yaml.
It can be, of course, a multiline text. It can be, of course, a multiline text.
type: "[]string or map[string]string" type: "[]string or map[string]string"
@@ -74,7 +74,7 @@
"secrets": "secrets":
short: "Env vars to be set as secrets." short: "Env vars to be set as secrets."
long: |- long: |-
This label allows setting the environment variables as secrets. The variable This label allows setting the environment variables as secrets. The variable
is removed from the environment and added to a secret object. is removed from the environment and added to a secret object.
The variable can be set to the {{ printf "%s/%s" .KatenaryPrefix "values"}} too, The variable can be set to the {{ printf "%s/%s" .KatenaryPrefix "values"}} too,
@@ -91,7 +91,7 @@
"ports": "ports":
short: "Ports to be added to the service." short: "Ports to be added to the service."
long: |- long: |-
Only useful for services without exposed port. It is mandatory if the Only useful for services without exposed port. It is mandatory if the
service is a dependency of another service. service is a dependency of another service.
example: |- example: |-
labels: labels:
@@ -103,7 +103,7 @@
"ingress": "ingress":
short: "Ingress rules to be added to the service." short: "Ingress rules to be added to the service."
long: |- long: |-
Declare an ingress rule for the service. The port should be exposed or Declare an ingress rule for the service. The port should be exposed or
declared with {{ printf "%s/%s" .KatenaryPrefix "ports" }}. declared with {{ printf "%s/%s" .KatenaryPrefix "ports" }}.
example: |- example: |-
labels: labels:
@@ -116,8 +116,8 @@
short: "Map env vars from the service to the deployment." short: "Map env vars from the service to the deployment."
long: |- long: |-
Because you may need to change the variable for Kubernetes, this label Because you may need to change the variable for Kubernetes, this label
forces the value to another. It is also particullary helpful to use a template forces the value to another. It is also particullary helpful to use a template
value instead. For example, you could bind the value to a service name value instead. For example, you could bind the value to a service name
with Helm attributes: with Helm attributes:
{{ "{{ tpl .Release.Name . }}" }}. {{ "{{ tpl .Release.Name . }}" }}.
@@ -148,10 +148,10 @@
"same-pod": "same-pod":
short: "Move the same-pod deployment to the target deployment." short: "Move the same-pod deployment to the target deployment."
long: |- long: |-
This will make the service to be included in another service pod. Some services This will make the service to be included in another service pod. Some services
must work together in the same pod, like a sidecar or a proxy or nginx + php-fpm. must work together in the same pod, like a sidecar or a proxy or nginx + php-fpm.
Note that volume and VolumeMount are copied from the source to the target Note that volume and VolumeMount are copied from the source to the target
deployment. deployment.
example: |- example: |-
web: web:
@@ -166,7 +166,7 @@
"description": "description":
short: "Description of the service" short: "Description of the service"
long: |- long: |-
This replaces the default comment in values.yaml file to the given description. This replaces the default comment in values.yaml file to the given description.
It is useful to document the service and configuration. It is useful to document the service and configuration.
The value can be set with a documentation in multiline format. The value can be set with a documentation in multiline format.
@@ -186,8 +186,8 @@
"dependencies": "dependencies":
short: "Add Helm dependencies to the service." short: "Add Helm dependencies to the service."
long: |- long: |-
Set the service to be, actually, a Helm dependency. This means that the Set the service to be, actually, a Helm dependency. This means that the
service will not be exported as template. The dependencies are added to service will not be exported as template. The dependencies are added to
the Chart.yaml file and the values are added to the values.yaml file. the Chart.yaml file and the values are added to the values.yaml file.
It's a list of objects with the following attributes: It's a list of objects with the following attributes:
@@ -199,12 +199,12 @@
!!! Info !!! Info
Katenary doesn't update the helm depenedencies by default. Katenary doesn't update the helm depenedencies by default.
Use `--helm-update` (or `-u`) flag to update the dependencies. Use `--helm-update` (or `-u`) flag to update the dependencies.
example: <code>katenary convert -u</code> example: <code>katenary convert -u</code>
By setting an alias, it is possible to change the name of the dependency By setting an alias, it is possible to change the name of the dependency
in values.yaml. in values.yaml.
example: |- example: |-
labels: labels:
@@ -226,17 +226,17 @@
"configmap-files": "configmap-files":
short: "Inject files as Configmap." short: "Inject files as Configmap."
long: |- long: |-
It makes a file or directory to be converted to one or more ConfigMaps It makes a file or directory to be converted to one or more ConfigMaps
and mounted in the pod. The file or directory is relative to the and mounted in the pod. The file or directory is relative to the
service directory. service directory.
If it is a directory, all files inside it are added to the ConfigMap. If it is a directory, all files inside it are added to the ConfigMap.
If the directory as subdirectories, so one configmap per subpath are created. If the directory as subdirectories, so one ConfigMap per sub-path are created.
!!! Warning !!! Warning
It is not intended to be used to store an entire project in configmaps. It is not intended to be used to store an entire project in ConfigMaps.
It is intended to be used to store configuration files that are not managed It is intended to be used to store configuration files that are not managed
by the application, like nginx configuration files. Keep in mind that your by the application, like nginx configuration files. Keep in mind that your
project sources should be stored in an application image or in a storage. project sources should be stored in an application image or in a storage.
example: |- example: |-
@@ -253,16 +253,17 @@
This adds a cronjob to the chart. This adds a cronjob to the chart.
The label value is a YAML object with the following attributes: The label value is a YAML object with the following attributes:
- command: the command to be executed
- schedule: the cron schedule (cron format or @every where "every" is a - command: the command to be executed
- schedule: the cron schedule (cron format or @every where "every" is a
duration like 1h30m, daily, hourly...) duration like 1h30m, daily, hourly...)
- rbac: false (optionnal), if true, it will create a role, a rolebinding and - rbac: false (optionnal), if true, it will create a role, a rolebinding and
a serviceaccount to make your cronjob able to connect the Kubernetes API a serviceaccount to make your cronjob able to connect the Kubernetes API
example: |- example: |-
labels: labels:
{{ .KatenaryPrefix }}/cronjob: |- {{ .KatenaryPrefix }}/cronjob: |-
command: echo "hello world" command: echo "hello world"
schedule: "* */1 * * *" # or @hourly for example schedule: "* */1 * * *" # or @hourly for example
type: "object" type: "object"
"env-from": "env-from":
@@ -274,21 +275,21 @@
service1: service1:
image: nginx:1.19 image: nginx:1.19
environment: environment:
FOO: bar FOO: bar
service2: service2:
image: php:7.4-fpm image: php:7.4-fpm
labels: labels:
# get the congigMap from service1 where FOO is # get the congigMap from service1 where FOO is
# defined inside this service too # defined inside this service too
{{ .KatenaryPrefix }}/env-from: |- {{ .KatenaryPrefix }}/env-from: |-
- myservice1 - myservice1
"exchange-volumes": "exchange-volumes":
short: Add exchange volumes (empty directory on the node) to share data short: Add exchange volumes (empty directory on the node) to share data
type: "[]object" type: "[]object"
long: |- long: |-
This label allows sharing data between containres. The volume is created in This label allows sharing data between containres. The volume is created in
the node and mounted in the pod. It is useful to share data between containers the node and mounted in the pod. It is useful to share data between containers
in a "same pod" logic. For example to let PHP-FPM and Nginx share the same direcotory. in a "same pod" logic. For example to let PHP-FPM and Nginx share the same direcotory.
@@ -299,6 +300,7 @@
- a `initContainer` for each definition - a `initContainer` for each definition
Fields: Fields:
- name: the name of the volume (manadatory) - name: the name of the volume (manadatory)
- mountPath: the path where the volume is mounted in the pod (optional, default is `/opt`) - mountPath: the path where the volume is mounted in the pod (optional, default is `/opt`)
- init: a command to run to initialize the volume with data (optional) - init: a command to run to initialize the volume with data (optional)