From 3ae5ec99ff81677988191d3c30ab6d5062dbf5e8 Mon Sep 17 00:00:00 2001 From: Patrice Ferlet Date: Wed, 3 Apr 2024 23:26:54 +0200 Subject: [PATCH] Typo, format of markdown I prefer to limit 120 columns. A .nvimrc will be proposed to avoid having to wide markdown lines. --- doc/docs/coding.md | 35 +++++++++++++++++--------- doc/docs/dependencies.md | 5 ++-- doc/docs/index.md | 33 +++++++++++++++--------- doc/docs/labels.md | 2 +- doc/docs/packages/generator.md | 2 +- doc/docs/usage.md | 43 +++++++++++++++++++++----------- generator/katenaryLabelsDoc.yaml | 2 +- 7 files changed, 79 insertions(+), 43 deletions(-) diff --git a/doc/docs/coding.md b/doc/docs/coding.md index d631300..a63e93e 100644 --- a/doc/docs/coding.md +++ b/doc/docs/coding.md @@ -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: diff --git a/doc/docs/dependencies.md b/doc/docs/dependencies.md index 0f88491..36f8975 100644 --- a/doc/docs/dependencies.md +++ b/doc/docs/dependencies.md @@ -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 diff --git a/doc/docs/index.md b/doc/docs/index.md index d77acf5..202015b 100644 --- a/doc/docs/index.md +++ b/doc/docs/index.md @@ -1,35 +1,42 @@ -
- -
+
# Welcome to Katenary documentation + !!! Edit "Thanks to..." **Katenary is built with:**
:fontawesome-brands-golang:{ .go-logo } **Documentation is built with:**
- MkDocs using Material for MkDocs theme template. + MkDocs using Material for MkDocs 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 diff --git a/doc/docs/labels.md b/doc/docs/labels.md index 1365270..985ba09 100644 --- a/doc/docs/labels.md +++ b/doc/docs/labels.md @@ -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 diff --git a/doc/docs/packages/generator.md b/doc/docs/packages/generator.md index 5fd4773..864a478 100644 --- a/doc/docs/packages/generator.md +++ b/doc/docs/packages/generator.md @@ -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 diff --git a/doc/docs/usage.md b/doc/docs/usage.md index 81ef15d..6fe08ca 100644 --- a/doc/docs/usage.md +++ b/doc/docs/usage.md @@ -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. diff --git a/generator/katenaryLabelsDoc.yaml b/generator/katenaryLabelsDoc.yaml index ea34133..36cd49b 100644 --- a/generator/katenaryLabelsDoc.yaml +++ b/generator/katenaryLabelsDoc.yaml @@ -48,7 +48,7 @@ long: |- 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