Skip to content

Commit

Permalink
Enhance documentation
Browse files Browse the repository at this point in the history 
- upgraded mkdocs and dependencise (+ add mermaid)
- linted markdown
- add more details
  • Loading branch information
@metal3d
metal3d committed Oct 18, 2024
1 parent 7f0597e commit e8eba7c
Show file tree
Hide file tree
Showing 12 changed files with 227 additions and 183 deletions.
33 changes: 31 additions & 2 deletions doc/docs/coding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Katenary is developed in Go. The version currently supported is 1.20. For reason
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.
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
Expand All @@ -25,6 +25,35 @@ During conversion, the `generator` package is primarily responsible for creating
one `Deployment` per `compose` service. If the container coming from "compose" exposes ports (explicitly), then a
service is created.

```mermaid
flowchart TD
D[Deployment]:::outputs@{shape: curv-trap}
C[Container List]@{shape: docs}
ConfigMap:::outputs@{shape: curv-trap}
Secrets:::outputs@{shape: curv-trap}
H[Helm Chart.yaml file]:::outputs@{shape: curv-trap}
Val[Values files]:::outputs@{shape: curv-trap}
PVC:::outputs@{shape: curv-trap}
S[Service]:::outputs@{shape: curv-trap}
A[Compose file]:::inputs --> B[Compose parser]
B --> G[Generator]
G --> P[Ports exposed to services] ---> S
G ------> H
G --> C --> D
G ------> Val
G ....-> M[Merge Continainers if same-pod]
M ..-> C
G --> E[Environment variables] ----> Secrets & ConfigMap
G--> V[Bind volumes] -------> PVC
V -----> CF[ Create ConfigMap\nfor static files as\nconfigmap-files] --> ConfigMap
Secrets & ConfigMap -- create envFrom --> D
V -- bind volumes --> D
```

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.

Expand All @@ -34,7 +63,6 @@ The `generator` package is where object struct are defined, and where the `Gener

The generation is made by using a `HelmChart` object:

```golang
```golang
for _, service := range project.Services {
dep := NewDeployment(service)
Expand All @@ -44,6 +72,7 @@ for _, service := range project.Services {
Servicename: service.Name,
}
}
```

**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
Expand Down
12 changes: 7 additions & 5 deletions doc/docs/dependencies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@

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/compose-spec/compose-go`: to parse compose files. It ensures :
- that the project respects the "compose" specification
- that Katenary uses the "compose" struct exactly the same way `podman compose` or `docker copose` does
- `github.com/spf13/cobra`: to parse command line arguments, subcommands and flags. It also generates completion for
bash, zsh, fish and powershell.
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
- `k8s.io/api` and `k8s.io/apimachinery` to create Kubernetes objects
- `sigs.k8s.io/yaml`: to generate Katenary yaml files
- `sigs.k8s.io/yaml`: to generate Katenary YAML files in the format of Kubernetes objects

There are also some other packages used in the project, like `gopkg.in/yaml` to parse labels. I'm sorry to not list the
entire dependencies. You can check the `go.mod` file to see all the dependencies.
78 changes: 50 additions & 28 deletions doc/docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,86 +2,108 @@

## Why Katenary?

The main author[^1] of Katenary is a big fan of Podman, Docker and makes a huge use of Compose. He uses it a lot in his daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose. He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts.
The main author[^1] of Katenary is a big fan of Podman, Docker and makes a huge use of Compose. He uses it a lot in his
daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose.
He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts.

Kompose was a good option. But the lacks of some options and configuration for the output Helm chart made him think about creating a new tool. He wanted to have a tool that could generate a complete Helm chart, with a lot of options and flexibility.
Kompose was a good option. But the lacks of some options and configuration for the output Helm chart made him think
about creating a new tool. He wanted to have a tool that could generate a complete Helm chart, with a lot of options
and flexibility.

[^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka metal3d, Tech Lead and DevOps Engineer at Klee Group.
[^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka Metal3d, Tech Lead and DevOps Engineer at Klee Group.

## What's the difference between Katenary and Kompose?

[Kompose](https://kompose.io/) is a very nice tool, made by the Kubernetes community. It's a tool to convert `docker-compose` files to Kubernetes manifests. It's a very good tool, and it's more mature than Katenary.
[Kompose](https://kompose.io/) is a very nice tool, made by the Kubernetes community. It's a tool to convert
`docker-compose` files to Kubernetes manifests. It's a very good tool, and it's more mature than Katenary.

Kompose is able to genererate Helm charts, but [it could be not the case in future releases](https://github.com/kubernetes/kompose/issues/1716) for several reasons[^2].
Kompose is able to generate Helm charts, but [it could be not the case in future releases](https://github.com/kubernetes/kompose/issues/1716) for several reasons[^2].

[^2]: The author of Kompose explains that they have no bandwidth to maintain the Helm chart generation. It's a complex task, and we can confirm. Katenary takes a lot of time to be developed and maintained. This issue mentions Katenary as an alternative to Helm chart generation :smile:
[^2]: The author of Kompose explains that they have no bandwidth to maintain the Helm chart generation. It's a complex
task, and we can confirm. Katenary takes a lot of time to be developed and maintained. This issue mentions Katenary as
an alternative to Helm chart generation :smile:

The project is focused on Kubernetes manifests and proposes to use "kusomize" to adapt the manifests. Helm seems to be not the priority.
The project is focused on Kubernetes manifests and proposes to use "kusomize" to adapt the manifests. Helm seems to be
not the priority.

Anyway, before this decision, the Helm chart generation was not what we expected. We wanted to have a more complete chart, with more options and more flexibility.
Anyway, before this decision, the Helm chart generation was not what we expected. We wanted to have a more complete
chart, with more options and more flexibility.

> That's why we decided to create Katenary.
Kompose didn't manage to generate a values file, complexe volume binding, and many other things. It was also not able to manage dependencies between services.
Kompose didn't manage to generate a values file, complex volume binding, and many other things. It was also not able
to manage dependencies between services.

> Be sure that we don't want to compete with Kompose. We just want to propose a different approach to the problem.
Kompose is an excellent tool, and we use it in some projects. It's a good choice if you want to convert your `docker-compose` files to Kubernetes manifests, but if you want to use Helm, Katenary is the tool you need.
Kompose is an excellent tool, and we use it in some projects. It's a good choice if you want to convert
your `docker-compose` files to Kubernetes manifests, but if you want to use Helm, Katenary is the tool you need.

## Why not using "one label" for all the configuration?

That was a dicsussion I had with my colleagues. The idea was to use a single label to store all the configuration. But, it's not a good idea.
That was a dicsussion I had with my colleagues. The idea was to use a single label to store all the configuration.
But, it's not a good idea.

Sometimes, you will have a long list of things to configure, like ports, ingress, dependecies, etc. It's better to have a clear and readable configuration. Segmented labels are easier to read and to maintain. It also avoids to have too many indentation levels in the YAML file.
Sometimes, you will have a long list of things to configure, like ports, ingress, dependencies, etc. It's better to have
a clear and readable configuration. Segmented labels are easier to read and to maintain. It also avoids having too
many indentation levels in the YAML file.

It is also more flexible. You can add or remove labels without changing the others.

## Why not using a configuration file?

The idea was to keep the configuration at a same place, and using the go-compose library to read the labels. It's easier to have a single file to manage.
The idea was to keep the configuration at a same place, and using the go-compose library to read the labels. It's
easier to have a single file to manage.

By the way, Katenary auto accepts a `compose.katenary.yaml` file in the same directory. It's a way to separate the configuration from the compose file. It uses the [overrides mecanism](https://docs.docker.com/compose/multiple-compose-files/merge/) like "compose" does.
By the way, Katenary auto accepts a `compose.katenary.yaml` file in the same directory. It's a way to separate the
configuration from the compose file. It uses
the [overrides' mechanism](https://docs.docker.com/compose/multiple-compose-files/merge/) like "compose" does.


## Why not developping with Rust?
## Why not developing with Rust?

Seriously...

OK, I will answer.

Rust is a good language. But, Podman, Docker, Kubernetes, Helm, and mostly all technologies around Kubernetes are written in Go. We have a large ecosystem in Go to manipulate, read, and write Kubernetes manifests as parsing Compose files.
Rust is a good language. But, Podman, Docker, Kubernetes, Helm, and mostly all technologies around Kubernetes are
written in Go. We have a large ecosystem in Go to manipulate, read, and write Kubernetes manifests as parsing
Compose files.

Go is better for this task.
> Go is better for this task.
There is no reason to use Rust for this project.

## Any chance to have a GUI?

Yes, it's a possibility. But, it's not a priority. We have a lot of things to do before. We need to stabilize the project, to have a good documentation, to have a good test coverage, and to have a good community.
Yes, it's a possibility. But, it's not a priority. We have a lot of things to do before. We need to stabilize the
project, to have a good documentation, to have a good test coverage, and to have a good community.

But, in a not so far future, we could have a GUI. The choice of [Fyne.io](https://fyne.io) is already made and we tested some concepts.


## I'm rich (or not), I want to help you. How can I do?

You can help us in many ways.

- The first things we really need, more than money, more than anything else, is to have feedback. If you use Katenary, if you have some issues, if you have some ideas, please open an issue on the [GitHub repository](https://github.com/metal3d/katenary).
- The second things is to help us to fix issues. If you're a Go developper, or if you want to fix the documentation, your help is greatly appreciated.
- The first things we really need, more than money, more than anything else, is to have feedback. If you use Katenary,
if you have some issues, if you have some ideas, please open an issue on the [GitHub repository](https://github.com/metal3d/katenary).
- The second things is to help us to fix issues. If you're a Go developper, or if you want to fix the documentation,
your help is greatly appreciated.
- And then, of course, we need money, or sponsors.

### If you're a company

We will be happy to communicate your help by putting your logo on the website and in the documentaiton. You can sponsor us by giving us some money, or by giving us some time of your developers, or leaving us some time to work on the project.
We will be happy to communicate your help by putting your logo on the website and in the documentaiton. You can sponsor
us by giving us some money, or by giving us some time of your developers, or leaving us some time to work on the project.

### If you're an individual

All donators will be listed on the website and in the documentation. You can give us some money by using the [GitHub Sponsors]()
All donators will be listed on the website and in the documentation. You can give us some money by using
the [GitHub Sponsors]()

All main contributors[^3] will be listed on the website and in the documentation.
All main contributors[^3] will be listed on the website and in the documentation.

> If you want to be anonymous, please tell us.

[^3]: Main contributors are the people who have made a significant contribution to the project. It could be code, documentation, or any other help. There is no defined rules, at this time, to evaluate the contribution. It's a subjective decision.

[^3]: Main contributors are the people who have made a significant contribution to the project. It could be code,
documentation, or any other help. There is no defined rules, at this time, to evaluate the contribution.
It's a subjective decision.
30 changes: 13 additions & 17 deletions doc/docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@

🚀 Unleash Productivity with Katenary! 🚀

Tired of manual conversions? Katenary harnesses the labels from your "compose" file to craft complete Helm Charts
Tired of manual conversions? Katenary harnesses the labels from your "compose" file to craft complete Helm Charts
effortlessly, saving you time and energy.

🛠️ Simple autmated CLI: Katenary handles the grunt work, generating everything needed for seamless service binding
🛠️ Simple autmated CLI: Katenary handles the grunt work, generating everything needed for seamless service binding
and Helm Chart creation.

💡 Effortless Efficiency: You only need to add labels when it's necessary to precise things. Then call `katenary convert`
Expand All @@ -19,13 +19,12 @@ and let the magic happen.
![](statics/workflow.svg)
</div>


# What is it?

Katenary is a tool made to help you to transform "compose" files (`compose.yaml`, `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
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.
Expand All @@ -42,19 +41,19 @@ share it with the community.

The main developer is [Patrice FERLET](https://github.com/metal3d).

The project source
The project source
code is hosted on the [:fontawesome-brands-github: Katenary GitHub Repository](https://github.com/metal3d/katenary).

## Install Katenary

Katenary is developped using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language.
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
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
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
Expand All @@ -66,10 +65,9 @@ sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install

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.
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:.

Expand All @@ -85,7 +83,7 @@ make build
make install
```

`make install` copies `./katenary` binary to your user binary path (`~/.local/bin`)
`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.:

Expand All @@ -109,8 +107,7 @@ source <(katenary completion bash)

Add this line in you `~/.profile`, `~/.bash_aliases` or `~/.bashrc` file to have completion at startup.


## What a name...
## What a name

A catenary is the curve that a hanging chain or cable assumes under its own weight when supported only at its ends.
I, the maintainer, decided to name "Katenary" this project because it's like a chain that links a boat to a dock.
Expand All @@ -122,14 +119,13 @@ Anyway, it's too late to change the name now :smile:

I spent time to find it :wink:

## Special thanks to...
## Special thanks to

I really want to thank all the contributors, testers, and of course, the authors of the packages and tools that are used
in this project. There is too many to list here. Katenary can works because of all these people. Open source is a great
thing! :heart:


!!! Edit "Special thanks"
!!! Edit "Special thanks"

**Katenary is built with:** <br />

Expand Down
Loading

0 comments on commit e8eba7c

Please sign in to comment.