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

Enhance doc, description, examples #88

Merged
metal3d merged 2 commits from develop into master 2024-11-26 23:00:58 +00:00
Conversation 0 Commits 2 Files Changed 5 +61 -45
5 changed files with 61 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@@ -19,11 +19,8 @@ Then call `katenary convert` and let the magic happen.
## What ?
Katenary is a tool to help to transform `docker-compose` files to a working Helm Chart for Kubernetes.
> **Important Note:** Katenary is a tool to help to build Helm Chart from a docker-compose file, but docker-compose
> doesn't propose as many features as what can do Kubernetes. So, we strongly recommend to use Katenary as a "bootstrap"
> tool and then to manually enhance the generated helm chart.
Katenary is a tool to help to transform `compose` (`docker compose`, `podman compose`, `nerdctl compose`, ...) files
to a working Helm Chart for Kubernetes.
Today, it's partially developed in collaboration with [Klee Group](https://www.kleegroup.com). Note that Katenary is
and **will stay an open source and free (as freedom) project**. We are convinced that the best way to make it better is to
@@ -149,6 +146,10 @@ services:
# note that "database" is a "compose" service name
# so we need to adapt it with the map-env label
DB_HOST: database
# a pitty to repeat this values, isn't it?
# so, let's change them with "values-from" label
DB_USER: foo
DB_PASSWORD: bar
expose:
- 80
depends_on:
@@ -163,11 +164,16 @@ services:
katenary.v3/map-env: |-
# make adaptations, DB_HOST environment is actually the service name
DB_HOST: '{{ .Release.Name }}-database'
katenary.v3/values-from: |-
# get the values from the "database" service
# this will use the databas secret, see below
DB_USER: databse.MARIADB_USER
DB_PASSWORD: database.MARIADB_PASSWORD
database:
image: mariadb:10
env_file:
# this will create a configMap
# this valuse will be added in a configMap
- my_env.env
environment:
MARIADB_USER: foo
@@ -239,7 +245,8 @@ To validate the `katenary.yaml` file, you can use the JSON schema using the "mas
`https://raw.githubusercontent.com/metal3d/katenary/refs/heads/master/katenary.json`
It's easy to configure in LazyVim, create a Lua file in your plugins directory:
It's easy to configure in [LazyVim](https://www.lazyvim.org/), using `nvim-lspconfig`,
create a Lua file in your `plugins` directory, or apply the settings as the example below:
```lua
-- yaml.lua
@@ -274,7 +281,7 @@ Use this address to validate the `katenary.yaml` file in VSCode:
}
```
You can, of course, replace the `refs/heads/master` with a specific tag or branch.
> You can, of course, replace the `refs/heads/master` with a specific tag or branch.
## What a name…

52
doc/docs/labels.md
View File

@@ -7,24 +7,24 @@ Katenary will try to Unmarshal these labels.
## Label list and types
<!-- START_LABEL_DOC : do not remove this tag !-->
| Label name | Description | Type |
| ----------------------------- | ---------------------------------------------------------------- | --------------------- |
| `katenary.v3/configmap-files` | Add files to the configmap. | list of strings |
| `katenary.v3/cronjob` | Create a cronjob from the service. | object |
| `katenary.v3/dependencies` | Add Helm dependencies to the service. | list of objects |
| `katenary.v3/description` | Description of the service | string |
| `katenary.v3/env-from` | Add environment variables from antoher service. | list of strings |
| `katenary.v3/exchange-volumes` | Add exchange volumes (empty directory on the node) to share data | list of objects |
| `katenary.v3/health-check` | Health check to be added to the deployment. | object |
| `katenary.v3/ignore` | Ignore the service | bool |
| `katenary.v3/ingress` | Ingress rules to be added to the service. | object |
| `katenary.v3/main-app` | Mark the service as the main app. | bool |
| `katenary.v3/map-env` | Map env vars from the service to the deployment. | object |
| `katenary.v3/ports` | Ports to be added to the service. | list of uint32 |
| `katenary.v3/same-pod` | Move the same-pod deployment to the target deployment. | string |
| `katenary.v3/secrets` | Env vars to be set as secrets. | list of string |
| `katenary.v3/values` | Environment variables to be added to the values.yaml | list of string or map |
| `katenary.v3/values-from` | Add values from another service. | map[string]string |
| Label name | Description | Type |
| ------------------------------ | ---------------------------------------------------------------- | -------------------------------- |
| `katenary.v3/configmap-files` | Add files to the configmap. | `[]string` |
| `katenary.v3/cronjob` | Create a cronjob from the service. | `object` |
| `katenary.v3/dependencies` | Add Helm dependencies to the service. | `[]object` |
| `katenary.v3/description` | Description of the service | `string` |
| `katenary.v3/env-from` | Add environment variables from antoher service. | `[]string` |
| `katenary.v3/exchange-volumes` | Add exchange volumes (empty directory on the node) to share data | `[]object` |
| `katenary.v3/health-check` | Health check to be added to the deployment. | `object` |
| `katenary.v3/ignore` | Ignore the service | `bool` |
| `katenary.v3/ingress` | Ingress rules to be added to the service. | `object` |
| `katenary.v3/main-app` | Mark the service as the main app. | `bool` |
| `katenary.v3/map-env` | Map env vars from the service to the deployment. | `map[string]string` |
| `katenary.v3/ports` | Ports to be added to the service. | `[]uint32` |
| `katenary.v3/same-pod` | Move the same-pod deployment to the target deployment. | `string` |
| `katenary.v3/secrets` | Env vars to be set as secrets. | `[]string` |
| `katenary.v3/values` | Environment variables to be added to the values.yaml | `[]string or map[string]string` |
| `katenary.v3/values-from` | Add values from another service. | `map[string]string` |
<!-- STOP_LABEL_DOC : do not remove this tag !-->
@@ -35,7 +35,7 @@ Katenary will try to Unmarshal these labels.
Add files to the configmap.
**Type**: `list of strings`
**Type**: `[]string`
It makes a file or directory to be converted to one or more ConfigMaps
and mounted in the pod. The file or directory is relative to the
@@ -91,7 +91,7 @@ labels:
Add Helm dependencies to the service.
**Type**: `list of objects`
**Type**: `[]object`
Set the service to be, actually, a Helm dependency. This means that the
service will not be exported as template. The dependencies are added to
@@ -159,7 +159,7 @@ labels:
Add environment variables from antoher service.
**Type**: `list of strings`
**Type**: `[]string`
It adds environment variables from another service to the current service.
@@ -185,7 +185,7 @@ service2:
Add exchange volumes (empty directory on the node) to share data
**Type**: `list of objects`
**Type**: `[]object`
This label allows sharing data between containres. The volume is created in
the node and mounted in the pod. It is useful to share data between containers
@@ -310,7 +310,7 @@ ghost:
Map env vars from the service to the deployment.
**Type**: `object`
**Type**: `map[string]string`
Because you may need to change the variable for Kubernetes, this label
forces the value to another. It is also particullary helpful to use a template
@@ -338,7 +338,7 @@ labels:
Ports to be added to the service.
**Type**: `list of uint32`
**Type**: `[]uint32`
Only useful for services without exposed port. It is mandatory if the
service is a dependency of another service.
@@ -382,7 +382,7 @@ php:
Env vars to be set as secrets.
**Type**: `list of string`
**Type**: `[]string`
This label allows setting the environment variables as secrets. The variable
is removed from the environment and added to a secret object.
@@ -406,7 +406,7 @@ labels:
Environment variables to be added to the values.yaml
**Type**: `list of string or map`
**Type**: `[]string or map[string]string`
By default, all environment variables in the "env" and environment
files are added to configmaps with the static values set. This label

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

@@ -61,6 +61,15 @@ func GetMatchLabels(serviceName, appName string) map[string]string
GetMatchLabels returns the matchLabels for a service. It uses the appName to replace the \_\_replace\_\_ in the labels. This is used to generate the matchLabels in the templates.
<a name="GetVersion"></a>
## func [GetVersion](<https://github.com/metal3d/katenary/blob/develop/generator/version.go#L14>)
```go
func GetVersion() string
```
GetVersion return the version of katneary. It's important to understand that the version is set at compile time for the github release. But, it the user get katneary using \`go install\`, the version should be different.
<a name="Helper"></a>
## func [Helper](<https://github.com/metal3d/katenary/blob/develop/generator/helper.go#L15>)

6
generator/labels/katenaryLabels.go
View File

@@ -166,9 +166,9 @@ func generateMarkdownHelp(names []string) string {
}
for _, name := range names {
help := labelFullHelp[name]
maxNameLength = max(maxNameLength, len(name)+2+len(KatenaryLabelPrefix))
maxNameLength = max(maxNameLength, len(name)+3+len(KatenaryLabelPrefix))
maxDescriptionLength = max(maxDescriptionLength, len(help.Short))
maxTypeLength = max(maxTypeLength, len(help.Type))
maxTypeLength = max(maxTypeLength, len(help.Type)+3)
}
fmt.Fprintf(&builder, "%s\n", generateTableHeader(maxNameLength, maxDescriptionLength, maxTypeLength))
@@ -179,7 +179,7 @@ func generateMarkdownHelp(names []string) string {
fmt.Fprintf(&builder, "| %-*s | %-*s | %-*s |\n",
maxNameLength, "`"+LabelName(name)+"`", // enclose in backticks
maxDescriptionLength, help.Short,
maxTypeLength, help.Type,
maxTypeLength, "`"+help.Type+"`",
)
}

16
generator/labels/katenaryLabelsDoc.yaml
View File

@@ -69,7 +69,7 @@
This is the documentation for the variable to
configure in values.yaml.
It can be, of course, a multiline text.
type: "list of string or map"
type: "[]string or map[string]string"
"secrets":
short: "Env vars to be set as secrets."
@@ -86,7 +86,7 @@
labels:
{{ .KatenaryPrefix }}/secrets: |-
- PASSWORD
type: "list of string"
type: "[]string"
"ports":
short: "Ports to be added to the service."
@@ -98,7 +98,7 @@
{{ .KatenaryPrefix }}/ports: |-
- 8080
- 8081
type: "list of uint32"
type: "[]uint32"
"ingress":
short: "Ingress rules to be added to the service."
@@ -131,7 +131,7 @@
{{ .KatenaryPrefix }}/map-env: |-
RUNNING: kubernetes
DB_HOST: '{{ "{{ include \"__APP__.fullname\" . }}" }}-database'
type: "object"
type: "map[string]string"
"health-check":
short: "Health check to be added to the deployment."
@@ -221,7 +221,7 @@
database: mydatabasename
username: myuser
password: the secret password
type: "list of objects"
type: "[]object"
"configmap-files":
short: "Add files to the configmap."
@@ -245,7 +245,7 @@
labels:
{{ .KatenaryPrefix }}/configmap-files: |-
- ./conf.d
type: "list of strings"
type: "[]string"
"cronjob":
short: "Create a cronjob from the service."
@@ -267,7 +267,7 @@
"env-from":
short: "Add environment variables from antoher service."
type: "list of strings"
type: "[]string"
long: |-
It adds environment variables from another service to the current service.
example: |-
@@ -286,7 +286,7 @@
"exchange-volumes":
short: Add exchange volumes (empty directory on the node) to share data
type: "list of objects"
type: "[]object"
long: |-
This label allows sharing data between containres. The volume is created in
the node and mounted in the pod. It is useful to share data between containers