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.
.PP
For very basic compose files, without any specific configuration, Katenary will create a working helm chart using the simple command line:
.IP
.EX
katenary convert
.EE
.PP
This will create a \f[CR]chart\f[R] directory with the helm chart inside.
.PP
But, in general, you will need to add a few configurations to help Katenary to transpose the compose file to a working helm chart.
.PP
There are two ways to configure Katenary:
.IP\[bu]2
Using the compose files, adding labels to the services
.IP\[bu]2
Using a specific file named \f[CR]katenary.yaml\f[R]
.PP
The Katenary file \f[CR]katenary.yaml\f[R] has benefits over the labels in the compose file:
.IP\[bu]2
you can validate the configuration with a schema, and use completion in your editor
.IP\[bu]2
you separate the configuration and leave the compose file \[dq]intact\[dq]
.IP\[bu]2
the syntax is a bit simpler, instead of using \f[CR]katenary.v3/xxx: |\-\f[R] you can use \f[CR]xxx: ...\f[R]
.PP
But: \f[B]this implies that you have to maintain two files if the compose file changes.\f[R]
So, to put a complete YAML content in the target label, you need to use a pipe char (\f[CR]|\f[R] or \f[CR]|\-\f[R]) and to \f[B]indent\f[R] your content.
.PP
For example :
.IP
.EX
labels:
# your labels
foo: bar
# katenary labels with multiline
katenary.v3/ingress: |\-
hostname: my.website.tld
port: 80
katenary.v3/ports: |\-
\- 1234
.EE
.PP
Katenary transforms compose services this way:
.IP\[bu]2
Takes the service and create a \[dq]Deployment\[dq] file
.IP\[bu]2
if a port is declared, Katenary creates a service (\f[CR]ClusterIP\f[R])
.IP\[bu]2
if a port is exposed, Katenary creates a service (\f[CR]NodePort\f[R])
.IP\[bu]2
environment variables will be stored inside a \f[CR]ConfigMap\f[R]
.IP\[bu]2
image, tags, and ingresses configuration are also stored in \f[CR]values.yaml\f[R] file
.IP\[bu]2
if named volumes are declared, Katenary create \f[CR]PersistentVolumeClaims\f[R]\- not enabled in values file
.IP\[bu]2
\f[CR]depends_on\f[R] needs that the pointed service declared a port.
If not, you can use labels to inform Katenary
.PP
For any other specific configuration, like binding local files as \f[CR]ConfigMap\f[R], bind variables, add values with documentation, etc.
You\[aq]ll need to use labels.
.PP
Katenary can also configure containers grouping in pods, declare dependencies, ignore some services, force variables as secrets, mount files as \f[CR]configMap\f[R], and many others things.
To adapt the helm chart generation, you will need to use some specific labels.
.PP
For more complete label usage, see the labels page.
.PP
Overriding file
.PP
It could be sometimes more convinient to separate the configuration related to Katenary inside a secondary file.
.PP
Instead of adding labels inside the \f[CR]compose.yaml\f[R] file, you can create a file named \f[CR]compose.katenary.yaml\f[R] and declare your labels inside.
Katenary will detect it by default.
.PP
\f[B]No need to precise the file in the command line.\f[R]
.SSMakeconversion
After having installed \f[CR]katenary\f[R], the standard usage is to call:
.IP
.EX
katenary convert
.EE
.PP
It will search standard compose files in the current directory and try to create a helm chart in \[dq]chart\[dq] directory.
.PP
Info
.PP
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 \f[CR]docker\-compose\f[R] and \f[CR]podman\-compose\f[R] do it.
.PP
Of course, you can provide others files than the default with (cumulative) \f[CR]\-c\f[R] options:
.IP
.EX
katenary convert \-c file1.yaml \-c file2.yaml
.EE
.SSSomecommonlabelstouse
Katenary proposes a lot of labels to configure the helm chart generation, but some are very important.
.PP
Info
.PP
For more complete label usage, see the labels page.
.SSWorkwithDependsOn?
Kubernetes does not provide service or pod starting detection from others pods.
But Katenary will create \f[CR]initContainer\f[R] to make you able to wait for a service to respond.
But you\[aq]ll probably need to adapt a bit the compose file.
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.
Katenary wants to create a \f[CR]initContainer\f[R] to hit on the related service.
So, instead of exposing the port in the compose definition, let\[aq]s declare this to Katenary with labels:
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.
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.
.SHLabelsdocumentation
Katenary proposes labels to set in \f[CR]compose.yaml\f[R] files (or override files) to configure the Helm Chart generation.
Because it is sometimes needed to have structured values, it is necessary to use the YAML syntax.
While compose labels are string, we can use \f[I]here\-doc\f[R] syntax using \f[CR]|\f[R] to use YAML multiline as value.
This label allows adding environment variables to the values.yaml file.
.PP
Note that the value inside the configmap is \f[CR]{{ tpl vaname . }}\f[R], so you can set the value to a template that will be rendered with the values.yaml file.
.PP
The value can be set with a documentation.
This may help to understand the purpose of the variable.
.PP
\f[B]Example:\f[R]
.IP
.EX
env:
FOO: bar
DB_NAME: mydb
TO_CONFIGURE: something that can be changed in values.yaml
A_COMPLEX_VALUE: example
labels:
katenary.v3/values: |\-
# simple values, set as is in values.yaml
\- TO_CONFIGURE
# complex values, set as a template in values.yaml with a documentation