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

chore(doc): Enhance documentation, fix typo

Browse Source
This commit is contained in:
Patrice Ferlet
2025-07-07 22:10:27 +02:00
parent 42bf35593f
commit 69c528e5e0
3 changed files with 96 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
doc/docs/usage.md
View File

@@ -13,7 +13,7 @@ katenary convert
This will create a `chart` directory with the helm chart inside.
But, in general, you will need to add a few configuration to help Katenary to transpose the compose file to a working
But, in general, you will need to add a few configurations to help Katenary to transpose the compose file to a working
helm chart.
There are two ways to configure Katenary:
@@ -25,7 +25,7 @@ The Katenary file `katenary.yaml` has benefits over the labels in the compose fi
- you can validate the configuration with a schema, and use completion in your editor
- you separate the configuration and leave the compose file "intact"
- the syntax is a bit simpler, instead of using `katenary.v3/xxx: |-" you can use`xxx: ...`
- the syntax is a bit simpler, instead of using `katenary.v3/xxx: |-` you can use `xxx: ...`
But: **this implies that you have to maintain two files if the compose file changes.**
@@ -34,19 +34,18 @@ For example. With "labels", you should do:
```yaml
# in compose file
services:
webapp:
image: php:7-apache
ports:
- 8080:80
environment:
DB_HOST: database
labels:
katenary.v3/ingress: |-
hostname: myapp.example.com
port: 8080
katenary.v3/map-env: |-
DB_HOST: "{{ .Release.Name }}-database"
webapp:
image: php:7-apache
ports:
- 8080:80
environment:
DB_HOST: database
labels:
katenary.v3/ingress: |-
hostname: myapp.example.com
port: 8080
katenary.v3/map-env: |-
DB_HOST: "{{ .Release.Name }}-database"
```
Using a Katenary file, you can do:
@@ -54,26 +53,26 @@ Using a Katenary file, you can do:
```yaml
# in compose file, no need to add labels
services:
webapp:
image: php:7-apache
ports:
- 8080:80
environment:
DB_HOST: database
webapp:
image: php:7-apache
ports:
- 8080:80
environment:
DB_HOST: database
# in katenary.yaml
webapp:
ingress:
hostname: myapp.example.com
port: 8080
map-env:
DB_HOST: "{{ .Release.Name }}-database"
ingress:
hostname: myapp.example.com
port: 8080
map-env:
DB_HOST: "{{ .Release.Name }}-database"
```
!!! Warning "YAML in multiline label"
Compose only accept text label. So, to put a complete YAML content in the target label,
Compose only accept text label. So, to put a complete YAML content in the target label,
you need to use a pipe char (`|` or `|-`) and to **indent** your content.
For example :
@@ -130,8 +129,8 @@ 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.
!!! 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:
@@ -142,7 +141,7 @@ 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.
!!! 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?
@@ -155,15 +154,15 @@ See this compose file:
version: "3"
services:
webapp:
image: php:8-apache
depends_on:
- database
webapp:
image: php:8-apache
depends_on:
- database
database:
image: mariadb
environment:
MYSQL_ROOT_PASSWORD: foobar
database:
image: mariadb
environment:
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
@@ -174,18 +173,18 @@ So, instead of exposing the port in the compose definition, let's declare this t
version: "3"
services:
webapp:
image: php:8-apache
depends_on:
- database
webapp:
image: php:8-apache
depends_on:
- database
database:
image: mariadb
environment:
MYSQL_ROOT_PASSWORD: foobar
labels:
katenary.v3/ports: |-
- 3306
database:
image: mariadb
environment:
MYSQL_ROOT_PASSWORD: foobar
labels:
katenary.v3/ports: |-
- 3306
```
### Declare ingresses
@@ -197,14 +196,14 @@ Katenary can create this resource for you. You just need to declare the hostname
```yaml
services:
webapp:
image: ...
ports: 8080:5050
labels:
katenary.v3/ingress: |-
# the target port is 5050 wich is the "service" port
port: 5050
hostname: myapp.example.com
webapp:
image: ...
ports: 8080:5050
labels:
katenary.v3/ingress: |-
# the target port is 5050 wich is the "service" port
port: 5050
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
@@ -219,13 +218,13 @@ With a compose file, there is no problem as Docker/Podman allows resolving the n
```yaml
services:
webapp:
image: php:7-apache
environment:
DB_HOST: database
webapp:
image: php:7-apache
environment:
DB_HOST: database
database:
image: mariadb
database:
image: mariadb
```
Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times
@@ -233,16 +232,16 @@ in a namespace), so you need to "remap" the environment variable to the right on
```yaml
services:
webapp:
image: php:7-apache
environment:
DB_HOST: database
labels:
katenary.v3/mapenv: |-
DB_HOST: "{{ .Release.Name }}-database"
webapp:
image: php:7-apache
environment:
DB_HOST: database
labels:
katenary.v3/mapenv: |-
DB_HOST: "{{ .Release.Name }}-database"
database:
image: mariadb
database:
image: mariadb
```
This label can be used to map others environment for any others reason. E.g. to change an informational environment
@@ -250,13 +249,13 @@ variable.
```yaml
services:
webapp:
#...
environment:
RUNNING: docker
labels:
katenary.v3/mapenv: |-
RUNNING: kubernetes
webapp:
#...
environment:
RUNNING: docker
labels:
katenary.v3/mapenv: |-
RUNNING: kubernetes
```
In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's