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

Better doc for ReadTheDocs

Browse Source
This commit is contained in:
Patrice Ferlet
2022-06-14 09:25:43 +02:00
parent bc3c5dc932
commit bb83384d62
7 changed files with 559 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
doc/docs/index.md
View File

@@ -1,36 +1,70 @@
# Home
<div class="md-center">
<img src="statics/logo.png" />
</div>
Welcome to the documentation of Katenary.
# Welcome to Katenary documentation
## What is Katenary?
!!! Edit "Thanks to..."
**Katenary is built with:**
<br /><a href="https://go.dev" target="_blank">:fontawesome-brands-golang:{ .go-logo }</a>
Katenary is a project that aims to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to a complete and production ready [Helm Chart](https://helm.sh).
**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.
> 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).
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://smile.eu). The project source code is hosted on the [Katenary GitHub Repository](https://github.com/metal3d/katenary).
It's an opensource project, under MIT licence, partially developped at [Smile](https://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 [Go](https://go.dev). The binary is statically linked, so you can only download it from the [release page](https://github.com/metal3d/katenary/releases) of the project in GutHub.
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.
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 you `$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)
```
You can also build and install it yourself, the giver Makefile provides a `build` command that uses `podman` or `docker` to build the binary. You don't need to install Go compiler so.
!!! Info "Upgrading is integrated to the `katenary` command"
Katenary propose a `upgrade` subcommand to update the current binary to the latest stable release.
Of course, you need to install Katenary once :smile:
!!! 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.
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.
```bash
git clone https://github.com/metal3d/katenary.git
cd katenary
make build
make install
```
Then, copy `./katenary` binary to you `PATH` (`~/.local/bin` or `/usr/local/bin` with `sudo`) and type `katenary version` and / or `katenary help`
`make install` copies `./katenary` binary to your user binary path (`~/.local/bin`)
You can install it in other directory by changing the `PREFIX` variable. E.g.:
```bash
make build
sudo make install PREFIX=/usr/local
```
Check if everything is OK using `katenary version` and / or `katenary help`
## Install completion

354
doc/docs/labels.md Normal file
View File

@@ -0,0 +1,354 @@
# Using labels
Katenary proposes labels to specify adaptation to provide to the Helm Chart. All labels are declared in the help message using:
```text
$ katenary show-labels
# 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 assign on the container in pod + expose as a service (coma separated)
katenary.io/container-ports : set the ports to assign on the contaienr in pod but avoid 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
```
## healthcheck
HealthCheck label defines how to make LivenessProbe on Kubernetes.
!!! Warning
This overrides the compose file healthcheck
!!! Info
The hostname is set to "localhost" by convention, but Katenary will ignore the hostname in tcp and http tests because it will create a LivenessProbe.
Some example of usage:
```yaml
services:
mariadb:
image: mariadb
labels:
katenary.io/healthcheck: tcp://localhost:3306
webapp:
image: nginx
labels:
katenary.io/healthcheck: http://localhost:80
example:
image: yourimage
labels:
katenary.io/healthcheck: "test -f /opt/installed"
```
## crontabs
Crontabs label proposes to create a complete CronTab object with needed RBAC to make it possible to run command inside the pod(s) with `kubectl`. Katenary will make the job for you. You only need to provide the command(s) to call.
It's a YAML array in multiline label.
```yaml
services:
mariadb:
image: mariadb
labels:
katenary.io/crontabs: |
- command: mysqldump -B myapp -uroot -p$${MYSQL_ROOT_PASSWORD} > dump.sql
schedule: "@every 1h"
```
The object is:
```
command: Command to run
schedule: the cron form schedule string
allPods: boolean (default false) to activate the cront on each pod
image: image name to use (default is bitnami/kubectl)
with corresponding tag to your kubernetes version
```
## empty-dirs
You sometime don't need to create a PersistentVolumeClaim. For example when a volume in your compose file is actually made to share the data between 2 or more containers.
In this case, an "emptyDir" volume is appreciated.
```yaml
services:
webapp:
image: nginx
volumes:
- sources:/var/www/html
labels:
# sources is actually an empty directory on the node
katenary.io/empty-dirs: sources
php:
image: php:7-fpm
volumes:
- sources:/var/www/html
labels:
# in the same pod than webapp
katenary.io/same-pod: webapp
# see the corresponding section, get the volume
# fro webapp
katenary.io/volume-from:
sources: webapp
```
## volume-from
We see this in the [empty-dir](#empty-dir) section, this label defines that the corresponding volume should be shared in this pod.
```yaml
services:
webapp:
image: nginx
volumes:
- data:/var/www/html
app:
image: php
volumes:
- data:/opt/data
labels:
katenary.io/volume-from: |
data: webapp
```
This implies that the declared volume in "webapp" will be mounted to "app" pods.
!!! Warning
This is possible with Kubernetes volumes restrictions. So, it works in these cases:
- if the volume class is Read Write Many
- or if you mount the volume in the same pod (so in the same node)
- and/or the volume is an emptyDir
## same-pod
It's sometimes important and/or necessary to declare that 2 services are in the same pod. For example, using PHP-FPM and NGinx. In this case, you can declare that both services are in the same pod.
You must declare this label only on "supplementary" services and always use the same master service for the entire pod declaration.
```yaml
services:
web:
image: nginx
php:
image: php:8-fpm
labels:
katenary.io/same-pod: web
```
The above example will create a `web` deployment, the PHP container is added in the `web` pod.
## configmap-volumes
This label proposes to declare a file or directory where content is actually static and can be mounted as configMap volume.
It's a comma separated label, you can declare several volumes.
For example, in `static/index.html`:
```html
<html>
<body>Hello</body>
</html>
```
And a compose file (snippet):
```yaml
serivces:
web:
image: nginx
volumes:
- ./static:/usr/share/nginx/html:z
labels:
katenary.io/configmap-volumes: ./statics
```
What will make Katenary:
- create a configmap containing the "index.html" file as data
- declare the volume in the `web` deployment file
- mount the configmap in `/usr/share/nginx/html` directory of the container
## ingress
Declare which port to use to create an ingress. The hostname will be declared in `values.yaml` file.
```yaml
serivces:
web:
image: nginx
ports:
- 8080:80
labels:
katenary.io/ingress: 80
```
!!! Info
A port **must** be declared, in `ports` section or with `katenary.io/ports` label. This to force the creation of a `Service`.
## ports and container-ports
It's sometimes not mandatory to declare a port in compose file, or maybe you want to avoid to expose them in the compose file. But Katenary will sometimes need to know the ports to create service, for example to allow `depends_on` directive.
In this case, you can declare the ports in the corresponding label:
```yaml
serivces:
web:
image: nginx
labels:
katenary.io/ports: 80,443
```
This will leave Katenary creating the service to open these ports to others pods.
Sometimes, you need to have `containerPort` in pods but **avoid the service declaration**, so you can use this label:
```yaml
services:
php:
image: php:8-fpm
labels:
katenary.io/container-ports: 9000
```
That will only declare the container port in the pod, but not in the service.
!!! Info
It's very useful when you need to declare ports in conjonction with `same-pod`. Katenary would create a service with all the pods ports inside. The `container-ports` label will make the ports to be ignored in the service creation.
## mapenv
Environment variables are working great for your compose stack but you sometimes need to change them in Helm. This label allows you to remap the value for Helm.
For example, when you use an environment variable to point on another service.
```yaml
serivces:
php:
image: php
environment:
DB_HOST: database
database:
image: mariadb
labels:
katenary.io/ports: 3306
```
The above example will break when you'll start it in Kubernetes because the `database` service will not be named like this, it will be renamed to `{{ .Release.Name }}-database`. So, you can declare the rewrite:
```yaml
services:
php:
image: php
environment:
DB_HOST: database
labels:
katenary.io/mapenv: |
DB_HOST: "{{ .Release.Name }}"-database
database:
image: mariadb
labels:
katenary.io/ports: 3306
```
It's also useful when you want to change a variable value to another when you deploy on Kubernetes.
## secret-envfiles
Katenary binds all "environemnt files" to config maps. But some of these files can be bound as sercrets.
In this case, declare the files as is:
```yaml
services:
app:
image: #...
env_file:
- ./env/whatever
- ./env/sensitives
labels:
katenary.io/secret-envfiles: ./env/sensitives
```
## secret-vars
If you have some environemnt variables to declare as secret, you can list them in the `secret-vars` label.
```yaml
services:
database:
image: mariadb
environemnt:
MYSQL_PASSWORD: foobar
MYSQL_ROOT_PASSWORD: longpasswordhere
MYSQL_USER: john
MYSQL_DATABASE: appdb
labels:
katenary.io/secret-vars: MYSQL_ROOT_PASSWORD,MYSQL_PASSWORD
```
## ignore
Simply ignore the service to not be exported in the Helm Chart.
```yaml
serivces:
# this service is able to answer HTTP
# on port 5000
webapp:
image: myapp
labels:
# declare the port
katenary.io/ports: 5000
# the ingress controller is a web proxy, so...
katenary.io/ingress: 5000
# with local Docker, I want to access my webapp
# with "myapp.locahost" so I use a nice proxy on
# port 80
proxy:
image: quay.io/pathwae/proxy
ports:
- 80:80
environemnt:
CONFIG: |
myapp.localhost: webapp:5000
labels:
# I don't need it in Helm, it's only
# for local test!
katenary.io/ignore: true
```

49
doc/docs/statics/addons.js
View File

@@ -1,41 +1,48 @@
function addSmileLogo() {
let logo = document.createElement("img");
const logo = document.createElement("img");
logo.src = "/statics/Logo_Smile.png";
logo.classList.add("smile-logo");
logo.alt = "Smile logo";
let link = document.createElement("a");
const link = document.createElement("a");
link.href = "https://www.smile.eu";
link.target = "_blank";
link.title = "Smile website";
link.classList.add("smile-logo");
link.appendChild(logo);
const text = document.createElement("p");
text.innerHTML = "Sponsored by Smile";
const div = document.createElement("div");
div.classList.add("smile-logo");
div.appendChild(text);
div.appendChild(link);
logo.addEventListener("load", () => {
let side = document.querySelector(".wy-menu");
side.appendChild(link);
let side = document.querySelector(".md-footer-meta__inner");
side.appendChild(div);
});
}
function addKatenaryLogo() {
let logo = document.createElement("img");
logo.src = "/statics/logo.png";
logo.classList.add("logo");
logo.alt = "Katenary logo";
function hljsInstall() {
const version = "11.5.1";
const theme = "github-dark";
let link = document.createElement("a");
link.href = "/";
link.title = "Index page";
const script = document.createElement("script");
script.src = `//cdnjs.cloudflare.com/ajax/libs/highlight.js/${version}/highlight.min.js`;
script.onload = () => {
const style = document.createElement("link");
style.rel = "stylesheet";
style.href = `//cdnjs.cloudflare.com/ajax/libs/highlight.js/${version}/styles/${theme}.min.css`;
document.head.appendChild(style);
hljs.initHighlightingOnLoad();
};
link.appendChild(logo);
logo.addEventListener("load", () => {
let side = document.querySelector(".wy-nav-side");
side.insertBefore(link, side.firstChild);
});
document.head.appendChild(script);
}
document.addEventListener("DOMContentLoaded", () => {
//addKatenaryLogo();
//addSmileLogo();
addSmileLogo();
hljsInstall();
});

42
doc/docs/statics/main.css
View File

@@ -1,16 +1,40 @@
.wy-nav-side {
background-color: #333333;
:root {
--md-primary-fg-color: #333333;
}
div.smile-logo {
display: flex;
font-size: 0.7rem;
}
img.smile-logo {
width: 100px;
}
pre code.hljs {
background-color: var(--md-primary-fg-color);
color: var(--md-primary-bg-color);
}
.wy-side-nav-search {
margin-top: 1em;
background-color: #333333;
button.md-clipboard::after {
transition: all 0.5s ease;
color: var(--lt-color-gray-500);
}
button.md-clipboard:hover::after {
color: var(--md-primary-bg-color);
}
img.logo {
max-width: 70% !important;
article a,
article a:visited {
color: var(--md-code-hl-number-color);
}
.wy-nav-top {
background-color: #333333;
.md-center {
text-align: center;
margin: auto;
}
.md-center img {
max-width: 200px;
}
.go-logo {
font-size: 4em;
}

89
doc/docs/usage.md
View File

@@ -15,7 +15,9 @@ Katenary transforms compose services this way:
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.
## Try to convert
For more complete label usage, see [the labels page](/labels).
## Make convertion
After having installed `katenary`, the standard usage is to call:
@@ -25,13 +27,25 @@ katenary convert
It will search standard compose files in the current directory and try to create a helm chart in "chart" directory.
Katenary respects the Docker rules for overrides files, and you can of course force others files:
!!! 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.
Of course, you can provide others files than the default with (cummulative) `-c` options:
```bash
katenary convert -c file1.yaml -c file2.yaml
```
## Some common labels to use
## Work with Depends On?
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).
### 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.
@@ -72,3 +86,72 @@ services:
katenary.io/ports: 3306
```
### 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.
```yaml
# ...
services:
webapp:
image: ...
ports: 8080:5050
labels:
katenary.io/ingress: 5050
```
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.
With a compose file, there is no problem as Docker/Podman allows to resolve the name by container name:
```yaml
services:
webapp:
image: php:7-apache
environment:
DB_HOST: database
database:
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.
```yaml
services:
webapp:
image: php:7-apache
environment:
DB_HOST: database
labels:
katenary.io/mapenv: |
DB_HOST: "{{ .Release.Name }}-database"
database:
image: mariadb
```
!!! Warning
This is a "multiline" label that accepts YAML or JSON content, don't forget to add a pipe char (`|`) 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.
```yaml
services:
webapp:
#...
environment:
RUNNING: docker
labels:
katenary.io/mapenv: |
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.

15
doc/mkdocs.yml
View File

@@ -1,12 +1,23 @@
site_name: Katenary documentation
docs_dir: ./docs
theme:
name: readthedocs
name: material
logo: statics/logo.png
markdown_extensions:
- admonition
- attr_list
- pymdownx.emoji:
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:materialx.emoji.twemoji
- pymdownx.highlight:
anchor_linenums: true
use_pygments: false
- pymdownx.superfences
extra_css:
- statics/main.css
extra_javascript:
- statics/addons.js
nav:
- index.md
- "Home": index.md
- usage.md
- labels.md

2
doc/requirements.txt
View File

@@ -1,3 +1,5 @@
mkdocs==1.3.0
Jinja2>=2.10.2
MarkupSafe>=2.0
pymdown-extensions>=9.5
mkdocs-material=="8.*"