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

Typo, format of markdown

Browse Source 
I prefer to limit 120 columns. A .nvimrc will be proposed to avoid
having to wide markdown lines.
This commit is contained in:
Patrice Ferlet
2024-04-03 23:26:54 +02:00
parent ef7fcb6133
commit 3ae5ec99ff
7 changed files with 79 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
doc/docs/coding.md
View File

@@ -1,14 +1,19 @@
# How Katenary works behind the scene
This section is for developers who want to take part in Katenary. Here we describe how it works and the expected principles.
This section is for developers who want to take part in Katenary. Here we describe how it works and the expected
principles.
## A few important points
Katenary is developed in Go. The version currently supported is 1.20. For reasons of readability, the `any` type is preferred to `interface{}`.
Katenary is developed in Go. The version currently supported is 1.20. For reasons of readability, the `any` type is
preferred to `interface{}`.
Since version v3, Katenary uses, in addition to `go-compose`, the `k8s` library to generate objects that are guaranteed to work before transformation. Katenary adds Helm syntax entries to add loops, transformations and conditions.
Since version v3, Katenary uses, in addition to `go-compose`, the `k8s` library to generate objects that are guaranteed
to work before transformation. Katenary adds Helm syntax entries to add loops, transformations and conditions.
We really try to follow best practices and code principles. But, Katenary needs a lot of workarounds and string manipulation during the process. There are, also, some drawbacks using standard k8s packages that makes a lot of type checks when generating the objects. We need to finalize the values after object generation.
We really try to follow best practices and code principles. But, Katenary needs a lot of workarounds and string
manipulation during the process. There are, also, some drawbacks using standard k8s packages that makes a lot of type
checks when generating the objects. We need to finalize the values after object generation.
**This makes the coding a bit harder than simply converting from YAML to YAML.**
@@ -16,9 +21,12 @@ We really try to follow best practices and code principles. But, Katenary needs
## General principle
During conversion, the `generator` package is primarily responsible for creating "objects". The principle is to generate one `Deployment` per `compose` service. If the container coming from "compose" exposes ports (explicitly), then a service is created.
During conversion, the `generator` package is primarily responsible for creating "objects". The principle is to generate
one `Deployment` per `compose` service. If the container coming from "compose" exposes ports (explicitly), then a
service is created.
If the declaration of a container is to be integrated into another pod (via the `same-pod` label), this `Deployment` and its associated service are still created. They are deleted last, once the merge has been completed.
If the declaration of a container is to be integrated into another pod (via the `same-pod` label), this `Deployment` and
its associated service are still created. They are deleted last, once the merge has been completed.
## Conversion in "`generator`" package
@@ -28,8 +36,8 @@ The generation is made by using a `HelmChart` object:
```golang
chart := NewChart(appName string)
```
Then, some processes are made to detect the "main app verion" (tag for the main service image), bootstrapping declared ports in labels, managing links to bind containers in one pods...
``` Then, some processes are made to detect the "main app verion" (tag for the main service image), bootstrapping
declared ports in labels, managing links to bind containers in one pods...
Then, a loop basically makes this:
@@ -44,12 +52,15 @@ for _, service := range project.Services {
}
```
**A lot** of string manipulations are made by each `Yaml()` methods. This is where you find the complex and impacting operations. The `Yaml` methods **don't return a valid YAML content**. This is a Helm Chart Yaml content with template conditions, vamues and calls to helper templates.
**A lot** of string manipulations are made by each `Yaml()` methods. This is where you find the complex and impacting
operations. The `Yaml` methods **don't return a valid YAML content**. This is a Helm Chart Yaml content with template
conditions, vamues and calls to helper templates.
> The `Yaml()` methods, in each object, need contribution, help, fixes, enhancements...
> They work, but there is a lot of complexity. Please, create issues, pull-requests and conversation in the GitHub repository.
> The `Yaml()` methods, in each object, need contribution, help, fixes, enhancements... They work, but there is a lot of
> complexity. Please, create issues, pull-requests and conversation in the GitHub repository.
The final step, before sending all templates to chart, is to bind the containers inside the same pod where it's specified.
The final step, before sending all templates to chart, is to bind the containers inside the same pod where it's
specified.
For each source container linked to the destination:

5
doc/docs/dependencies.md
View File

@@ -5,8 +5,9 @@ Katenary uses `compose-go` and several kubernetes official packages.
- `github.com/compose-spec/compose-go`: to parse compose files. It ensures that:
- the project respects the "compose" specification
- katenary uses the "compose" struct exactly the same way that podman-compose or docker does
- `github.com/spf13/cobra`: to parse command line arguments, subcommands and flags. It also generates completion for bash, zsh, fish and powershell.
- `github.com/thediveo/netdb`: to get the standard names of a service from it's port number
- `github.com/spf13/cobra`: to parse command line arguments, subcommands and flags. It also generates completion for
bash, zsh, fish and powershell.
- `github.com/thediveo/netdb`: to get the standard names of a service from its port number
- `gopkg.in/yaml.v3`:
- to generate `Chart.yaml` and `values.yaml` files (only)
- to parse Katenary labels in the compose file

33
doc/docs/index.md
View File

@@ -1,35 +1,42 @@
<div class="md-center">
<img src="statics/logo.png" />
</div>
<div class="md-center"> <img src="statics/logo.png" /> </div>
# Welcome to Katenary documentation
!!! Edit "Thanks to..."
**Katenary is built with:**
<br /><a href="https://go.dev" target="_blank">:fontawesome-brands-golang:{ .go-logo }</a>
**Documentation is built with:**
<br />
<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.
<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.
> Special thanks to all contributors, testors, and of course packages and tools authors.
Katenary is a tool made to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to a complete and production ready [Helm Chart](https://helm.sh).
Katenary is a tool made to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to
complete and production ready [Helm Chart](https://helm.sh).
You'll be able to deploy your project in [:material-kubernetes: Kubernetes](https://kubernetes.io) in a few seconds (of course, more if you need to tweak with labels).
You'll be able to deploy your project in [:material-kubernetes: Kubernetes](https://kubernetes.io) in a few seconds
(of course, more if you need to tweak with labels).
It uses your current file and optionnaly labels to configure the result.
It's an opensource project, under MIT licence, partially developped at [Smile](https://www.smile.eu). The project source code is hosted on the [:fontawesome-brands-github: Katenary GitHub Repository](https://github.com/metal3d/katenary).
It's an opensource project, under MIT licence, partially developped at [Smile](https://www.smile.eu). The project source
code is hosted on the [:fontawesome-brands-github: Katenary GitHub Repository](https://github.com/metal3d/katenary).
## Install Katenary
Katenary is developped in :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev). The binary is statically linked, so you can simply download it from the [release page](https://github.com/metal3d/katenary/releases) of the project in GutHub.
Katenary is developped using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language.
The binary is statically linked, so you can simply download it from the [release
page](https://github.com/metal3d/katenary/releases) of the project in GutHub.
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`.
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`.
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.
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.
```bash
sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install.sh)
@@ -42,11 +49,13 @@ sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install
!!! 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:.
But, note that the "master" branch is not the "stable" version. It's preferable to switch to a tag, or to use the releases.
But, note that the "master" branch is not the "stable" version. It's preferable to switch to a tag, or to use the
releases.
```bash
git clone https://github.com/metal3d/katenary.git

2
doc/docs/labels.md
View File

@@ -353,7 +353,7 @@ Environment variables to be added to the values.yaml
By default, all environment variables in the "env" and environment
files are added to configmaps with the static values set. This label
allows to add 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
you can set the value to a template that will be rendered with the

2
doc/docs/packages/generator.md
View File

@@ -365,7 +365,7 @@ func (d *Deployment) BindFrom(service types.ServiceConfig, binded *Deployment)
### func (*Deployment) DependsOn
``` go
func (d *Deployment) DependsOn(to *Deployment) error
func (d *Deployment) DependsOn(to *Deployment, servicename string) error
```
DependsOn adds a initContainer to the deployment that will wait for the

43
doc/docs/usage.md
View File

@@ -1,6 +1,8 @@
# Basic Usage
Basically, you can use `katenary` to transpose a docker-compose file (or any compose file compatible with `podman-compose` and `docker-compose`) to a configurable Helm Chart. This resulting helm chart can be installed with `helm` command to your Kubernetes cluster.
Basically, you can use `katenary` to transpose a docker-compose file (or any compose file compatible with
`podman-compose` and `docker-compose`) to a configurable Helm Chart. This resulting helm chart can be installed with
`helm` command to your Kubernetes cluster.
Katenary transforms compose services this way:
@@ -9,11 +11,14 @@ Katenary transforms compose services this way:
- it a port is exposed, katenary creates a service (NodePort)
- environment variables will be stored in `values.yaml` file
- image, tags, and ingresses configuration are also stored in `values.yaml` file
- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file (a `emptyDir` is used by default)
- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file (a `emptyDir` is
used by default)
- any other volume (local mount points) are ignored
- `depends_on` needs that the pointed service declared a port. If not, you can use labels to inform katenary
Katenary can also configure containers grouping in pods, declare dependencies, ignore some services, force variables as secrets, mount files as `configMap`, and many others things. To adapt the helm chart generation, you will need to use some specific labels.
Katenary can also configure containers grouping in pods, declare dependencies, ignore some services, force variables as
secrets, mount files as `configMap`, and many others things. To adapt the helm chart generation, you will need to use
some specific labels.
For more complete label usage, see [the labels page](labels.md).
@@ -28,7 +33,8 @@ katenary convert
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 (cummulative) `-c` options:
@@ -47,7 +53,8 @@ Katenary proposes a lot of labels to configure the helm chart generation, but so
### Work with Depends On?
Kubernetes does not propose service or pod starting detection from others pods. But katenary will create init containers to make you able to wait for a service to respond. But you'll probably need to adapt a bit the compose file.
Kubernetes does not propose service or pod starting detection from others pods. But katenary will create init containers
to make you able to wait for a service to respond. But you'll probably need to adapt a bit the compose file.
See this compose file:
@@ -66,7 +73,9 @@ services:
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 (yet) solution to check the database startup. Katenary wants to create a `initContainer` to hit on the related service. So, instead of exposing the port in the compose definition, let's declare this to katenary with labels:
In this case, `webapp` needs to know the `database` port because the `depends_on` points on it and Kubernetes has not
(yet) solution to check the database startup. Katenary wants to create a `initContainer` to hit on the related service.
So, instead of exposing the port in the compose definition, let's declare this to katenary with labels:
```yaml
@@ -89,7 +98,8 @@ services:
### Declare ingresses
It's very common to have an `Ingress` on web application to deploy on Kuberenetes. The `katenary.io/ingress` declare the port to bind.
It's very common to have an `Ingress` on web application to deploy on Kuberenetes. The `katenary.io/ingress` declare the
port to bind.
```yaml
# ...
@@ -103,12 +113,14 @@ services:
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 service to bind the container itself.
Note that the port to bind is the one used by the container, not the used locally. This is because Katenary create a
service to bind the container itself.
### Map environment to helm values
A lot of framework needs to receive service host or IP in an environment variable to configure the connexion. For example, to connect a PHP application to a database.
A lot of framework needs to receive service host or IP in an environment variable to configure the connexion. For
example, to connect a PHP application to a database.
With a compose file, there is no problem as Docker/Podman allows to resolve the name by container name:
@@ -123,7 +135,8 @@ services:
image: mariadb
```
Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times in a namespace), so you need to "remap" the environment variable to the right one.
Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times
in a namespace), so you need to "remap" the environment variable to the right one.
```yaml
@@ -140,10 +153,11 @@ services:
image: mariadb
```
!!! Warning
This is a "multiline" label that accepts YAML or JSON content, don't forget to add a pipe char (`|` or `|-`) and to **indent** your content
!!! Warning This is a "multiline" label that accepts YAML or JSON content, don't forget to add a pipe char (`|` or `|-`)
and to **indent** your content
This label can be used to map others environment for any others reason. E.g. to change an informational environment variable.
This label can be used to map others environment for any others reason. E.g. to change an informational environment
variable.
```yaml
@@ -157,4 +171,5 @@ services:
RUNNING: kubernetes
```
In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's `docker` for "podman" and "docker" executions.
In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's
`docker` for "podman" and "docker" executions.