diff --git a/Makefile b/Makefile index 2ecd77b..5178f56 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ VERSION=$(shell git describe --exact-match --tags $(CUR_SHA) 2>/dev/null || echo CTN:=$(shell which podman 2>&1 1>/dev/null && echo "podman" || echo "docker") PREFIX=~/.local -GOVERSION=1.21 +GOVERSION=1.22 GO=container OUT=katenary BLD_CMD=go build -ldflags="-X 'katenary/generator.Version=$(VERSION)'" -o $(OUT) ./cmd/katenary @@ -154,6 +154,15 @@ clean: rm -rf katenary dist/* release.id +serve-doc: __label_doc + @cd doc && \ + [ -d venv ] || python -m venv venv; \ + source venv/bin/activate && \ + echo "==> Installing requirements in the virtual env..." + pip install -qq -r requirements.txt && \ + echo "==> Serving doc with mkdocs..." && \ + mkdocs serve + tests: test test: @echo -e "\033[1;33mTesting katenary $(VERSION)...\033[0m" @@ -183,6 +192,8 @@ push-release: build-all __label_doc: + @command -v gomarkdoc || (echo "==> We need to install gomarkdoc..." && \ + go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest) @echo "=> Generating labels doc..." # short label doc go run ./cmd/katenary help-labels -m | \ @@ -201,16 +212,6 @@ __label_doc: PACKAGES=$$(for f in $$(find . -name "*.go" -type f); do dirname $$f; done | sort -u) for pack in $$PACKAGES; do echo "-> Generating doc for $$pack" - #gomarkdoc -o doc/docs/packages/$$pack.md $$pack - gomarkdoc -f azure-devops $$pack | pandoc -t gfm -o doc/docs/packages/$$pack.md - # drop the Index section without removing the title - # - remove the Index section, but keep the following heading + gomarkdoc --repository.default-branch $(shell git branch --show-current) -o doc/docs/packages/$$pack.md $$pack sed -i '/^## Index/,/^##/ { /## Index/d; /^##/! d }' doc/docs/packages/$$pack.md - # fixes for markdown problem - # - there are \* on heading, replace to * - sed -i 's/\\\*/\*/g' doc/docs/packages/$$pack.md - ## parenthis in heading are escaped, replace to unescaped - sed -i 's/\\(/\(/g' doc/docs/packages/$$pack.md - sed -i 's/\\)/\)/g' doc/docs/packages/$$pack.md - ## list are badly formatted with 2 spaces, replace to 4 done diff --git a/doc/docs/index.md b/doc/docs/index.md index 3121831..70acac9 100644 --- a/doc/docs/index.md +++ b/doc/docs/index.md @@ -1,20 +1,3 @@ - - # Welcome to Katenary documentation @@ -29,6 +12,11 @@ and Helm Chart creation. πŸ’‘ Effortless Efficiency: You only need to add labels when it's necessary to precise things. Then call `katenary convert` and let the magic happen. +
+ +
+ + # What ? Katenary is a tool made to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to diff --git a/doc/docs/packages/cmd/katenary.md b/doc/docs/packages/cmd/katenary.md index 03a3bb2..9261889 100644 --- a/doc/docs/packages/cmd/katenary.md +++ b/doc/docs/packages/cmd/katenary.md @@ -2,7 +2,11 @@ # katenary -``` go +```go import "katenary/cmd/katenary" ``` +Katenary CLI, main package. + +This package is not intended to be imported. It contains the main function that build the command line with \`cobra\` package. + diff --git a/doc/docs/packages/generator.md b/doc/docs/packages/generator.md index 864a478..82f9db8 100644 --- a/doc/docs/packages/generator.md +++ b/doc/docs/packages/generator.md @@ -2,40 +2,33 @@ # generator -``` go +```go import "katenary/generator" ``` -The generator package generates kubernetes objects from a compose file -and transforms them into a helm chart. +The generator package generates kubernetes objects from a compose file and transforms them into a helm chart. -The generator package is the core of katenary. It is responsible for -generating kubernetes objects from a compose file and transforming them -into a helm chart. Convertion manipulates Yaml representation of -kubernetes object to add conditions, labels, annotations, etc. to the -objects. It also create the values to be set to the values.yaml file. +The generator package is the core of katenary. It is responsible for generating kubernetes objects from a compose file and transforming them into a helm chart. Convertion manipulates Yaml representation of kubernetes object to add conditions, labels, annotations, etc. to the objects. It also create the values to be set to the values.yaml file. -The generate.Convert() create an HelmChart object and call β€œGenerate()” -method to convert from a compose file to a helm chart. It saves the helm -chart in the given directory. +The generate.Convert\(\) create an HelmChart object and call "Generate\(\)" method to convert from a compose file to a helm chart. It saves the helm chart in the given directory. -If you want to change or override the write behavior, you can use the -HelmChart.Generate() function and implement your own write function. -This function returns the helm chart object containing all kubernetes -objects and helm chart ingormation. It does not write the helm chart to -the disk. +If you want to change or override the write behavior, you can use the HelmChart.Generate\(\) function and implement your own write function. This function returns the helm chart object containing all kubernetes objects and helm chart ingormation. It does not write the helm chart to the disk. -TODO: Manage cronjob + rbac TODO: create note.txt TODO: manage emptyDirs +TODO: Manage cronjob \+ rbac TODO: create note.txt TODO: manage emptyDirs ## Constants -``` go + + +```go const KATENARY_PREFIX = "katenary.v3/" ``` ## Variables -``` go + + +```go var ( // Standard annotationss @@ -45,172 +38,179 @@ var ( ) ``` -Version is the version of katenary. It is set at compile time. +Version is the version of katenary. It is set at compile time. -``` go +```go var Version = "master" // changed at compile time ``` -## func Convert + +## func [Convert]() -``` go +```go func Convert(config ConvertOptions, dockerComposeFile ...string) ``` -Convert a compose (docker, podman…) project to a helm chart. It calls -Generate() to generate the chart and then write it to the disk. +Convert a compose \(docker, podman...\) project to a helm chart. It calls Generate\(\) to generate the chart and then write it to the disk. -## func GetLabelHelp + +## func [GetLabelHelp]() -``` go +```go func GetLabelHelp(asMarkdown bool) string ``` Generate the help for the labels. -## func GetLabelHelpFor + +## func [GetLabelHelpFor]() -``` go +```go func GetLabelHelpFor(labelname string, asMarkdown bool) string ``` GetLabelHelpFor returns the help for a specific label. -## func GetLabelNames + +## func [GetLabelNames]() -``` go +```go func GetLabelNames() []string ``` GetLabelNames returns a sorted list of all katenary label names. -## func GetLabels + +## func [GetLabels]() -``` go +```go func GetLabels(serviceName, appName string) map[string]string ``` -## func GetMatchLabels +GetLabels returns the labels for a service. It uses the appName to replace the \_\_replace\_\_ in the labels. This is used to generate the labels in the templates. -``` go + +## func [GetMatchLabels]() + +```go func GetMatchLabels(serviceName, appName string) map[string]string ``` -## func Helper +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. -``` go + +## func [Helper]() + +```go func Helper(name string) string ``` Helper returns the \_helpers.tpl file for a chart. -## func NewCronJob + +## func [NewCronJob]() -``` go +```go func NewCronJob(service types.ServiceConfig, chart *HelmChart, appName string) (*CronJob, *RBAC) ``` -NewCronJob creates a new CronJob from a compose service. The appName is -the name of the application taken from the project name. +NewCronJob creates a new CronJob from a compose service. The appName is the name of the application taken from the project name. -## type ChartTemplate + +## type [ChartTemplate]() -ChartTemplate is a template of a chart. It contains the content of the -template and the name of the service. This is used internally to -generate the templates. +ChartTemplate is a template of a chart. It contains the content of the template and the name of the service. This is used internally to generate the templates. TODO: maybe we can set it private. -``` go +```go type ChartTemplate struct { Content []byte Servicename string } ``` -## type ConfigMap + +## type [ConfigMap]() ConfigMap is a kubernetes ConfigMap. Implements the DataMap interface. -``` go +```go type ConfigMap struct { *corev1.ConfigMap // contains filtered or unexported fields } ``` -### func NewConfigMap + +### func [NewConfigMap]() -``` go +```go func NewConfigMap(service types.ServiceConfig, appName string) *ConfigMap ``` -NewConfigMap creates a new ConfigMap from a compose service. The appName -is the name of the application taken from the project name. The -ConfigMap is filled by environment variables and labels β€œmap-env”. +NewConfigMap creates a new ConfigMap from a compose service. The appName is the name of the application taken from the project name. The ConfigMap is filled by environment variables and labels "map\-env". -### func NewConfigMapFromFiles + +### func [NewConfigMapFromFiles]() -``` go +```go func NewConfigMapFromFiles(service types.ServiceConfig, appName string, path string) *ConfigMap ``` -NewConfigMapFromFiles creates a new ConfigMap from a compose service. -This path is the path to the file or directory. If the path is a -directory, all files in the directory are added to the ConfigMap. Each -subdirectory are ignored. Note that the Generate() function will create -the subdirectories ConfigMaps. +NewConfigMapFromFiles creates a new ConfigMap from a compose service. This path is the path to the file or directory. If the path is a directory, all files in the directory are added to the ConfigMap. Each subdirectory are ignored. Note that the Generate\(\) function will create the subdirectories ConfigMaps. -### func (*ConfigMap) AddData + +### func \(\*ConfigMap\) [AddData]() -``` go +```go func (c *ConfigMap) AddData(key string, value string) ``` -AddData adds a key value pair to the configmap. Append or overwrite the -value if the key already exists. +AddData adds a key value pair to the configmap. Append or overwrite the value if the key already exists. -### func (*ConfigMap) AppendDir + +### func \(\*ConfigMap\) [AppendDir]() -``` go +```go func (c *ConfigMap) AppendDir(path string) ``` -AddFile adds files from given path to the configmap. It is not -recursive, to add all files in a directory, you need to call this -function for each subdirectory. +AddFile adds files from given path to the configmap. It is not recursive, to add all files in a directory, you need to call this function for each subdirectory. -### func (*ConfigMap) Filename + +### func \(\*ConfigMap\) [Filename]() -``` go +```go func (c *ConfigMap) Filename() string ``` -Filename returns the filename of the configmap. If the configmap is used -for files, the filename contains the path. +Filename returns the filename of the configmap. If the configmap is used for files, the filename contains the path. -### func (*ConfigMap) SetData + +### func \(\*ConfigMap\) [SetData]() -``` go +```go func (c *ConfigMap) SetData(data map[string]string) ``` SetData sets the data of the configmap. It replaces the entire data. -### func (*ConfigMap) Yaml + +### func \(\*ConfigMap\) [Yaml]() -``` go +```go func (c *ConfigMap) Yaml() ([]byte, error) ``` Yaml returns the yaml representation of the configmap -## type ConvertOptions + +## type [ConvertOptions]() -ConvertOptions are the options to convert a compose project to a helm -chart. +ConvertOptions are the options to convert a compose project to a helm chart. -``` go +```go type ConvertOptions struct { Force bool // Force the chart directory deletion if it already exists. OutputDir string // The output directory of the chart. @@ -221,20 +221,22 @@ type ConvertOptions struct { } ``` -## type CronJob + +## type [CronJob]() CronJob is a kubernetes CronJob. -``` go +```go type CronJob struct { *batchv1.CronJob // contains filtered or unexported fields } ``` -### func (*CronJob) Filename + +### func \(\*CronJob\) [Filename]() -``` go +```go func (c *CronJob) Filename() string ``` @@ -242,9 +244,10 @@ Filename returns the filename of the cronjob. Implements the Yaml interface. -### func (*CronJob) Yaml + +### func \(\*CronJob\) [Yaml]() -``` go +```go func (c *CronJob) Yaml() ([]byte, error) ``` @@ -252,12 +255,12 @@ Yaml returns the yaml representation of the cronjob. Implements the Yaml interface. -## type CronJobValue + +## type [CronJobValue]() -CronJobValue is a cronjob configuration that will be saved in -values.yaml. +CronJobValue is a cronjob configuration that will be saved in values.yaml. -``` go +```go type CronJobValue struct { Repository *RepositoryValue `yaml:"repository,omitempty"` Environment map[string]any `yaml:"environment,omitempty"` @@ -266,32 +269,33 @@ type CronJobValue struct { } ``` -## type DataMap + +## type [DataMap]() -DataMap is a kubernetes ConfigMap or Secret. It can be used to add data -to the ConfigMap or Secret. +DataMap is a kubernetes ConfigMap or Secret. It can be used to add data to the ConfigMap or Secret. -``` go +```go type DataMap interface { SetData(map[string]string) AddData(string, string) } ``` -### func NewFileMap + +### func [NewFileMap]() -``` go +```go func NewFileMap(service types.ServiceConfig, appName string, kind string) DataMap ``` -NewFileMap creates a new DataMap from a compose service. The appName is -the name of the application taken from the project name. +NewFileMap creates a new DataMap from a compose service. The appName is the name of the application taken from the project name. -## type Dependency + +## type [Dependency]() Dependency is a dependency of a chart to other charts. -``` go +```go type Dependency struct { Name string `yaml:"name"` Version string `yaml:"version"` @@ -301,122 +305,132 @@ type Dependency struct { } ``` -## type Deployment + +## type [Deployment]() Deployment is a kubernetes Deployment. -``` go +```go type Deployment struct { *appsv1.Deployment `yaml:",inline"` // contains filtered or unexported fields } ``` -### func NewDeployment + +### func [NewDeployment]() -``` go +```go func NewDeployment(service types.ServiceConfig, chart *HelmChart) *Deployment ``` -NewDeployment creates a new Deployment from a compose service. The -appName is the name of the application taken from the project name. It -also creates the Values map that will be used to create the values.yaml -file. +NewDeployment creates a new Deployment from a compose service. The appName is the name of the application taken from the project name. It also creates the Values map that will be used to create the values.yaml file. -### func (*Deployment) AddContainer + +### func \(\*Deployment\) [AddContainer]() -``` go +```go func (d *Deployment) AddContainer(service types.ServiceConfig) ``` AddContainer adds a container to the deployment. -### func (*Deployment) AddHealthCheck + +### func \(\*Deployment\) [AddHealthCheck]() -``` go +```go func (d *Deployment) AddHealthCheck(service types.ServiceConfig, container *corev1.Container) ``` -### func (*Deployment) AddIngress -``` go + + +### func \(\*Deployment\) [AddIngress]() + +```go func (d *Deployment) AddIngress(service types.ServiceConfig, appName string) *Ingress ``` -AddIngress adds an ingress to the deployment. It creates the ingress -object. +AddIngress adds an ingress to the deployment. It creates the ingress object. -### func (*Deployment) AddVolumes + +### func \(\*Deployment\) [AddVolumes]() -``` go +```go func (d *Deployment) AddVolumes(service types.ServiceConfig, appName string) ``` -AddVolumes adds a volume to the deployment. It does not create the PVC, -it only adds the volumes to the deployment. If the volume is a bind -volume it will warn the user that it is not supported yet. +AddVolumes adds a volume to the deployment. It does not create the PVC, it only adds the volumes to the deployment. If the volume is a bind volume it will warn the user that it is not supported yet. -### func (*Deployment) BindFrom + +### func \(\*Deployment\) [BindFrom]() -``` go +```go func (d *Deployment) BindFrom(service types.ServiceConfig, binded *Deployment) ``` -### func (*Deployment) DependsOn -``` go + + +### func \(\*Deployment\) [DependsOn]() + +```go func (d *Deployment) DependsOn(to *Deployment, servicename string) error ``` -DependsOn adds a initContainer to the deployment that will wait for the -service to be up. +DependsOn adds a initContainer to the deployment that will wait for the service to be up. -### func (*Deployment) Filename + +### func \(\*Deployment\) [Filename]() -``` go +```go func (d *Deployment) Filename() string ``` -### func (*Deployment) SetEnvFrom +Filename returns the filename of the deployment. -``` go + +### func \(\*Deployment\) [SetEnvFrom]() + +```go func (d *Deployment) SetEnvFrom(service types.ServiceConfig, appName string) ``` -SetEnvFrom sets the environment variables to a configmap. The configmap -is created. +SetEnvFrom sets the environment variables to a configmap. The configmap is created. -### func (*Deployment) Yaml + +### func \(\*Deployment\) [Yaml]() -``` go +```go func (d *Deployment) Yaml() ([]byte, error) ``` Yaml returns the yaml representation of the deployment. -## type FileMapUsage + +## type [FileMapUsage]() FileMapUsage is the usage of the filemap. -``` go +```go type FileMapUsage uint8 ``` -FileMapUsage constants. +FileMapUsage constants. -``` go +```go const ( FileMapUsageConfigMap FileMapUsage = iota // pure configmap for key:values. FileMapUsageFiles // files in a configmap. ) ``` -## type HelmChart + +## type [HelmChart]() -HelmChart is a Helm Chart representation. It contains all the tempaltes, -values, versions, helpers… +HelmChart is a Helm Chart representation. It contains all the tempaltes, values, versions, helpers... -``` go +```go type HelmChart struct { Name string `yaml:"name"` ApiVersion string `yaml:"apiVersion"` @@ -432,48 +446,41 @@ type HelmChart struct { } ``` -### func Generate + +### func [Generate]() -``` go +```go func Generate(project *types.Project) (*HelmChart, error) ``` -Generate a chart from a compose project. This does not write files to -disk, it only creates the HelmChart object. +Generate a chart from a compose project. This does not write files to disk, it only creates the HelmChart object. The Generate function will create the HelmChart object this way: -1. Detect the service port name or leave the port number if not found. +- Detect the service port name or leave the port number if not found. +- Create a deployment for each service that are not ingnore. +- Create a service and ingresses for each service that has ports and/or declared ingresses. +- Create a PVC or Configmap volumes for each volume. +- Create init containers for each service which has dependencies to other services. +- Create a chart dependencies. +- Create a configmap and secrets from the environment variables. +- Merge the same\-pod services. -2. Create a deployment for each service that are not ingnore. + +### func [NewChart]() -3. Create a service and ingresses for each service that has ports - and/or declared ingresses. - -4. Create a PVC or Configmap volumes for each volume. - -5. Create init containers for each service which has dependencies to - other services. - -6. Create a chart dependencies. - -7. Create a configmap and secrets from the environment variables. - -8. Merge the same-pod services. - -### func NewChart - -``` go +```go func NewChart(name string) *HelmChart ``` NewChart creates a new empty chart with the given name. -## type Help + +## type [Help]() Help is the documentation of a label. -``` go +```go type Help struct { Short string `yaml:"short"` Long string `yaml:"long"` @@ -482,41 +489,51 @@ type Help struct { } ``` -## type Ingress + +## type [Ingress]() -``` go + + +```go type Ingress struct { *networkv1.Ingress // contains filtered or unexported fields } ``` -### func NewIngress + +### func [NewIngress]() -``` go +```go func NewIngress(service types.ServiceConfig, Chart *HelmChart) *Ingress ``` NewIngress creates a new Ingress from a compose service. -### func (*Ingress) Filename + +### func \(\*Ingress\) [Filename]() -``` go +```go func (ingress *Ingress) Filename() string ``` -### func (*Ingress) Yaml -``` go + + +### func \(\*Ingress\) [Yaml]() + +```go func (ingress *Ingress) Yaml() ([]byte, error) ``` -## type IngressValue -IngressValue is a ingress configuration that will be saved in -values.yaml. -``` go + +## type [IngressValue]() + +IngressValue is a ingress configuration that will be saved in values.yaml. + +```go type IngressValue struct { Enabled bool `yaml:"enabled"` Host string `yaml:"host"` @@ -526,17 +543,18 @@ type IngressValue struct { } ``` -## type Label + +## type [Label]() Label is a katenary label to find in compose files. -``` go +```go type Label = string ``` -Known labels. +Known labels. -``` go +```go const ( LABEL_MAIN_APP Label = KATENARY_PREFIX + "main-app" LABEL_VALUES Label = KATENARY_PREFIX + "values" @@ -555,28 +573,30 @@ const ( ) ``` -## type LabelType + +## type [LabelType]() -LabelType identifies the type of label to generate in objects. TODO: is -this still needed? +LabelType identifies the type of label to generate in objects. TODO: is this still needed? -``` go +```go type LabelType uint8 ``` -``` go + + +```go const ( DeploymentLabel LabelType = iota ServiceLabel ) ``` -## type PersistenceValue + +## type [PersistenceValue]() -PersistenceValue is a persistence configuration that will be saved in -values.yaml. +PersistenceValue is a persistence configuration that will be saved in values.yaml. -``` go +```go type PersistenceValue struct { Enabled bool `yaml:"enabled"` StorageClass string `yaml:"storageClass"` @@ -585,12 +605,12 @@ type PersistenceValue struct { } ``` -## type RBAC + +## type [RBAC]() -RBAC is a kubernetes RBAC containing a role, a rolebinding and an -associated serviceaccount. +RBAC is a kubernetes RBAC containing a role, a rolebinding and an associated serviceaccount. -``` go +```go type RBAC struct { RoleBinding *RoleBinding Role *Role @@ -598,213 +618,247 @@ type RBAC struct { } ``` -### func NewRBAC + +### func [NewRBAC]() -``` go +```go func NewRBAC(service types.ServiceConfig, appName string) *RBAC ``` -NewRBAC creates a new RBAC from a compose service. The appName is the -name of the application taken from the project name. +NewRBAC creates a new RBAC from a compose service. The appName is the name of the application taken from the project name. -## type RepositoryValue + +## type [RepositoryValue]() -RepositoryValue is a docker repository image and tag that will be saved -in values.yaml. +RepositoryValue is a docker repository image and tag that will be saved in values.yaml. -``` go +```go type RepositoryValue struct { Image string `yaml:"image"` Tag string `yaml:"tag"` } ``` -## type Role + +## type [Role]() Role is a kubernetes Role. -``` go +```go type Role struct { *rbacv1.Role // contains filtered or unexported fields } ``` -### func (*Role) Filename + +### func \(\*Role\) [Filename]() -``` go +```go func (r *Role) Filename() string ``` -### func (*Role) Yaml -``` go + + +### func \(\*Role\) [Yaml]() + +```go func (r *Role) Yaml() ([]byte, error) ``` -## type RoleBinding + + + +## type [RoleBinding]() RoleBinding is a kubernetes RoleBinding. -``` go +```go type RoleBinding struct { *rbacv1.RoleBinding // contains filtered or unexported fields } ``` -### func (*RoleBinding) Filename + +### func \(\*RoleBinding\) [Filename]() -``` go +```go func (r *RoleBinding) Filename() string ``` -### func (*RoleBinding) Yaml -``` go + + +### func \(\*RoleBinding\) [Yaml]() + +```go func (r *RoleBinding) Yaml() ([]byte, error) ``` -## type Secret + + + +## type [Secret]() Secret is a kubernetes Secret. Implements the DataMap interface. -``` go +```go type Secret struct { *corev1.Secret // contains filtered or unexported fields } ``` -### func NewSecret + +### func [NewSecret]() -``` go +```go func NewSecret(service types.ServiceConfig, appName string) *Secret ``` NewSecret creates a new Secret from a compose service -### func (*Secret) AddData + +### func \(\*Secret\) [AddData]() -``` go +```go func (s *Secret) AddData(key string, value string) ``` AddData adds a key value pair to the secret. -### func (*Secret) Filename + +### func \(\*Secret\) [Filename]() -``` go +```go func (s *Secret) Filename() string ``` Filename returns the filename of the secret. -### func (*Secret) SetData + +### func \(\*Secret\) [SetData]() -``` go +```go func (s *Secret) SetData(data map[string]string) ``` SetData sets the data of the secret. -### func (*Secret) Yaml + +### func \(\*Secret\) [Yaml]() -``` go +```go func (s *Secret) Yaml() ([]byte, error) ``` Yaml returns the yaml representation of the secret. -## type Service + +## type [Service]() Service is a kubernetes Service. -``` go +```go type Service struct { *v1.Service `yaml:",inline"` // contains filtered or unexported fields } ``` -### func NewService + +### func [NewService]() -``` go +```go func NewService(service types.ServiceConfig, appName string) *Service ``` NewService creates a new Service from a compose service. -### func (*Service) AddPort + +### func \(\*Service\) [AddPort]() -``` go +```go func (s *Service) AddPort(port types.ServicePortConfig, serviceName ...string) ``` AddPort adds a port to the service. -### func (*Service) Filename + +### func \(\*Service\) [Filename]() -``` go +```go func (s *Service) Filename() string ``` Filename returns the filename of the service. -### func (*Service) Yaml + +### func \(\*Service\) [Yaml]() -``` go +```go func (s *Service) Yaml() ([]byte, error) ``` Yaml returns the yaml representation of the service. -## type ServiceAccount + +## type [ServiceAccount]() ServiceAccount is a kubernetes ServiceAccount. -``` go +```go type ServiceAccount struct { *corev1.ServiceAccount // contains filtered or unexported fields } ``` -### func (*ServiceAccount) Filename + +### func \(\*ServiceAccount\) [Filename]() -``` go +```go func (r *ServiceAccount) Filename() string ``` -### func (*ServiceAccount) Yaml -``` go + + +### func \(\*ServiceAccount\) [Yaml]() + +```go func (r *ServiceAccount) Yaml() ([]byte, error) ``` -## type Value -Value will be saved in values.yaml. It contains configuraiton for all -deployment and services. The content will be lile: - name_of_component: - repository: - image: image_name - tag: image_tag - persistence: - enabled: true - storageClass: storage_class_name - ingress: - enabled: true - host: host_name - path: path_name - environment: - ENV_VAR_1: value_1 - ENV_VAR_2: value_2 + +## type [Value]() -``` go +Value will be saved in values.yaml. It contains configuraiton for all deployment and services. The content will be lile: + +``` +name_of_component: + repository: + image: image_name + tag: image_tag + persistence: + enabled: true + storageClass: storage_class_name + ingress: + enabled: true + host: host_name + path: path_name + environment: + ENV_VAR_1: value_1 + ENV_VAR_2: value_2 +``` + +```go type Value struct { Repository *RepositoryValue `yaml:"repository,omitempty"` Persistence map[string]*PersistenceValue `yaml:"persistence,omitempty"` @@ -816,78 +870,84 @@ type Value struct { } ``` -### func NewValue + +### func [NewValue]() -``` go +```go func NewValue(service types.ServiceConfig, main ...bool) *Value ``` -NewValue creates a new Value from a compose service. The value contains -the necessary information to deploy the service (image, tag, replicas, -etc.). +NewValue creates a new Value from a compose service. The value contains the necessary information to deploy the service \(image, tag, replicas, etc.\). -If \`main\` is true, the tag will be empty because it will be set in the -helm chart appVersion. +If \`main\` is true, the tag will be empty because it will be set in the helm chart appVersion. -### func (*Value) AddIngress + +### func \(\*Value\) [AddIngress]() -``` go +```go func (v *Value) AddIngress(host, path string) ``` -### func (*Value) AddPersistence -``` go + + +### func \(\*Value\) [AddPersistence]() + +```go func (v *Value) AddPersistence(volumeName string) ``` AddPersistence adds persistence configuration to the Value. -## type VolumeClaim + +## type [VolumeClaim]() -VolumeClaim is a kubernetes VolumeClaim. This is a -PersistentVolumeClaim. +VolumeClaim is a kubernetes VolumeClaim. This is a PersistentVolumeClaim. -``` go +```go type VolumeClaim struct { *v1.PersistentVolumeClaim // contains filtered or unexported fields } ``` -### func NewVolumeClaim + +### func [NewVolumeClaim]() -``` go +```go func NewVolumeClaim(service types.ServiceConfig, volumeName, appName string) *VolumeClaim ``` NewVolumeClaim creates a new VolumeClaim from a compose service. -### func (*VolumeClaim) Filename + +### func \(\*VolumeClaim\) [Filename]() -``` go +```go func (v *VolumeClaim) Filename() string ``` Filename returns the suggested filename for a VolumeClaim. -### func (*VolumeClaim) Yaml + +### func \(\*VolumeClaim\) [Yaml]() -``` go +```go func (v *VolumeClaim) Yaml() ([]byte, error) ``` Yaml marshals a VolumeClaim into yaml. -## type Yaml + +## type [Yaml]() Yaml is a kubernetes object that can be converted to yaml. -``` go +```go type Yaml interface { Yaml() ([]byte, error) Filename() string } ``` -Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc) +Generated by [gomarkdoc]() diff --git a/doc/docs/packages/generator/extrafiles.md b/doc/docs/packages/generator/extrafiles.md index ca80dd0..a0a6b84 100644 --- a/doc/docs/packages/generator/extrafiles.md +++ b/doc/docs/packages/generator/extrafiles.md @@ -2,27 +2,27 @@ # extrafiles -``` go +```go import "katenary/generator/extrafiles" ``` -extrafiles package provides function to generate the Chart files that -are not objects. Like README.md and notes.txt… +extrafiles package provides function to generate the Chart files that are not objects. Like README.md and notes.txt... -## func NotesFile +## func [NotesFile]() -``` go +```go func NotesFile() string ``` NoteTXTFile returns the content of the note.txt file. -## func ReadMeFile + +## func [ReadMeFile]() -``` go +```go func ReadMeFile(charname, description string, values map[string]any) string ``` ReadMeFile returns the content of the README.md file. -Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc) +Generated by [gomarkdoc]() diff --git a/doc/docs/packages/parser.md b/doc/docs/packages/parser.md index 3283326..1acfc81 100644 --- a/doc/docs/packages/parser.md +++ b/doc/docs/packages/parser.md @@ -2,19 +2,18 @@ # parser -``` go +```go import "katenary/parser" ``` -Parser package is a wrapper around compose-go to parse compose files. +Parser package is a wrapper around compose\-go to parse compose files. -## func Parse +## func [Parse]() -``` go +```go func Parse(profiles []string, dockerComposeFile ...string) (*types.Project, error) ``` -Parse compose files and return a project. The project is parsed with -dotenv, osenv and profiles. +Parse compose files and return a project. The project is parsed with dotenv, osenv and profiles. -Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc) +Generated by [gomarkdoc]() diff --git a/doc/docs/packages/update.md b/doc/docs/packages/update.md index c6fab01..ff63677 100644 --- a/doc/docs/packages/update.md +++ b/doc/docs/packages/update.md @@ -2,54 +2,59 @@ # update -``` go +```go import "katenary/update" ``` -Update package is used to check if a new version of katenary is -available. +Update package is used to check if a new version of katenary is available. ## Variables -``` go -var Version = "master" // reset by cmd/main.go + + +```go +var ( + Version = "master" // reset by cmd/main.go +) ``` -## func DownloadFile + +## func [DownloadFile]() -``` go +```go func DownloadFile(url, exe string) error ``` -DownloadFile will download a url to a local file. It also ensure that -the file is executable. +DownloadFile will download a url to a local file. It also ensure that the file is executable. -## func DownloadLatestVersion + +## func [DownloadLatestVersion]() -``` go +```go func DownloadLatestVersion(assets []Asset) error ``` DownloadLatestVersion will download the latest version of katenary. -## type Asset + +## type [Asset]() Asset is a github asset from release url. -``` go +```go type Asset struct { Name string `json:"name"` URL string `json:"browser_download_url"` } ``` -### func CheckLatestVersion + +### func [CheckLatestVersion]() -``` go +```go func CheckLatestVersion() (string, []Asset, error) ``` -CheckLatestVersion check katenary latest version from release and -propose to download it +CheckLatestVersion check katenary latest version from release and propose to download it -Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc) +Generated by [gomarkdoc]() diff --git a/doc/docs/packages/utils.md b/doc/docs/packages/utils.md index b497f03..35f5e0c 100644 --- a/doc/docs/packages/utils.md +++ b/doc/docs/packages/utils.md @@ -2,186 +2,193 @@ # utils -``` go +```go import "katenary/utils" ``` -Utils package provides some utility functions used in katenary. It -defines some constants and functions used in the whole project. +Utils package provides some utility functions used in katenary. It defines some constants and functions used in the whole project. -## Constants +## func [CountStartingSpaces]() -Icons used in katenary. - -``` go -const ( - IconSuccess Icon = "βœ…" - IconFailure = "❌" - IconWarning = "⚠️'" - IconNote = "πŸ“" - IconWorld = "🌐" - IconPlug = "πŸ”Œ" - IconPackage = "πŸ“¦" - IconCabinet = "πŸ—„οΈ" - IconInfo = "❕" - IconSecret = "πŸ”’" - IconConfig = "πŸ”§" - IconDependency = "πŸ”—" -) -``` - -## func CountStartingSpaces - -``` go +```go func CountStartingSpaces(line string) int ``` -CountStartingSpaces counts the number of spaces at the beginning of a -string. +CountStartingSpaces counts the number of spaces at the beginning of a string. -## func GetContainerByName + +## func [GetContainerByName]() -``` go +```go func GetContainerByName(name string, containers []corev1.Container) (*corev1.Container, int) ``` -GetContainerByName returns a container by name and its index in the -array. It returns nil, -1 if not found. +GetContainerByName returns a container by name and its index in the array. It returns nil, \-1 if not found. -## func GetKind + +## func [GetKind]() -``` go +```go func GetKind(path string) (kind string) ``` GetKind returns the kind of the resource from the file path. -## func GetServiceNameByPort + +## func [GetServiceNameByPort]() -``` go +```go func GetServiceNameByPort(port int) string ``` -GetServiceNameByPort returns the service name for a port. It the service -name is not found, it returns an empty string. +GetServiceNameByPort returns the service name for a port. It the service name is not found, it returns an empty string. -## func GetValuesFromLabel + +## func [GetValuesFromLabel]() -``` go +```go func GetValuesFromLabel(service types.ServiceConfig, LabelValues string) map[string]*EnvConfig ``` GetValuesFromLabel returns a map of values from a label. -## func HashComposefiles + +## func [HashComposefiles]() -``` go +```go func HashComposefiles(files []string) (string, error) ``` HashComposefiles returns a hash of the compose files. -## func Int32Ptr + +## func [Int32Ptr]() -``` go +```go func Int32Ptr(i int32) *int32 ``` Int32Ptr returns a pointer to an int32. -## func MapKeys + +## func [MapKeys]() -``` go +```go func MapKeys(m map[string]interface{}) []string ``` -## func PathToName -``` go + + +## func [PathToName]() + +```go func PathToName(path string) string ``` PathToName converts a path to a kubernetes complient name. -## func StrPtr + +## func [StrPtr]() -``` go +```go func StrPtr(s string) *string ``` StrPtr returns a pointer to a string. -## func TplName + +## func [TplName]() -``` go +```go func TplName(serviceName, appname string, suffix ...string) string ``` -TplName returns the name of the kubernetes resource as a template -string. It is used in the templates and defined in \_helper.tpl file. +TplName returns the name of the kubernetes resource as a template string. It is used in the templates and defined in \_helper.tpl file. -## func TplValue + +## func [TplValue]() -``` go +```go func TplValue(serviceName, variable string, pipes ...string) string ``` -GetContainerByName returns a container by name and its index in the -array. +GetContainerByName returns a container by name and its index in the array. -## func Warn + +## func [Warn]() -``` go +```go func Warn(msg ...interface{}) ``` Warn prints a warning message -## func WordWrap + +## func [WordWrap]() -``` go +```go func WordWrap(text string, lineWidth int) string ``` -WordWrap wraps a string to a given line width. Warning: it may break the -string. You need to check the result. +WordWrap wraps a string to a given line width. Warning: it may break the string. You need to check the result. -## func Wrap + +## func [Wrap]() -``` go +```go func Wrap(src, above, below string) string ``` -Wrap wraps a string with a string above and below. It will respect the -indentation of the src string. +Wrap wraps a string with a string above and below. It will respect the indentation of the src string. -## func WrapBytes + +## func [WrapBytes]() -``` go +```go func WrapBytes(src, above, below []byte) []byte ``` -WrapBytes wraps a byte array with a byte array above and below. It will -respect the indentation of the src string. +WrapBytes wraps a byte array with a byte array above and below. It will respect the indentation of the src string. -## type EnvConfig + +## type [EnvConfig]() -EnvConfig is a struct to hold the description of an environment -variable. +EnvConfig is a struct to hold the description of an environment variable. -``` go +```go type EnvConfig struct { Description string Service types.ServiceConfig } ``` -## type Icon + +## type [Icon]() Icon is a unicode icon -``` go +```go type Icon string ``` -Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc) +Icons used in katenary. + +```go +const ( + IconSuccess Icon = "βœ…" + IconFailure Icon = "❌" + IconWarning Icon = "⚠️'" + IconNote Icon = "πŸ“" + IconWorld Icon = "🌐" + IconPlug Icon = "πŸ”Œ" + IconPackage Icon = "πŸ“¦" + IconCabinet Icon = "πŸ—„οΈ" + IconInfo Icon = "❕" + IconSecret Icon = "πŸ”’" + IconConfig Icon = "πŸ”§" + IconDependency Icon = "πŸ”—" +) +``` + +Generated by [gomarkdoc]() diff --git a/doc/docs/usage.md b/doc/docs/usage.md index 6fe08ca..715d5f5 100644 --- a/doc/docs/usage.md +++ b/doc/docs/usage.md @@ -4,24 +4,56 @@ Basically, you can use `katenary` to transpose a docker-compose file (or any com `podman-compose` and `docker-compose`) to a configurable Helm Chart. This resulting helm chart can be installed with `helm` command to your Kubernetes cluster. +!!! Warning "YAML in multiline label" + + Compose only accept text label. So, to put a complete YAML content in the target label, you need to use a pipe char (`|` or `|-`) + and to **indent** your content. + + For example : + + ```yaml + labels: + # your labels + foo: bar + # katenary labels with multiline + katenary.v3/ingress: |- + hostname: my.website.tld + port: 80 + katenary.v3/ports: |- + - 1234 + ``` + + Katenary transforms compose services this way: - Takes the service and create a "Deployment" file - if a port is declared, katenary creates a service (ClusterIP) -- it a port is exposed, katenary creates a service (NodePort) -- environment variables will be stored in `values.yaml` file +- if a port is exposed, katenary creates a service (NodePort) +- environment variables will be stored inside a configMap - 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) -- any other volume (local mount points) are ignored +- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file - `depends_on` needs that the pointed service declared a port. If not, you can use labels to inform katenary +For any other specific configuration, like binding local files as configMap, bind variables, add values with documentation, etc. You'll need to use 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). +!!! Info "Overriding file" + + It could be sometimes more convinient to separate the + configuration related to Katenary inside a secondary file. + + Instead of adding labels inside the `compose.yaml` file, + you can create a file named `compose.katenary.yaml` and + declare your labels inside. Katenary will detect it by + default. + + **No need to precise the file in the command line.** + ## Make convertion After having installed `katenary`, the standard usage is to call: @@ -153,8 +185,6 @@ 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 This label can be used to map others environment for any others reason. E.g. to change an informational environment variable. diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index 6035216..3c7a813 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -42,6 +42,7 @@ nav: - coding.md - dependencies.md - Go Packages: + - packages/cmd/katenary.md - packages/generator.md - packages/parser.md - packages/update.md diff --git a/doc/requirements.txt b/doc/requirements.txt index 234bde6..c9d5e41 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,6 @@ -mkdocs>=1.3.0 -Jinja2>=2.10.2 -MarkupSafe>=2.0 -pymdown-extensions>=9.5 -mkdocs-material>=8.3.4 -mkdocs-material-extensions>=1.0.3 +mkdocs>=1.5.3 +Jinja2>=3.1.3 +MarkupSafe>=2.1.5 +pymdown-extensions>=10.7.1 +mkdocs-material>=9.5.17 +mkdocs-material-extensions>=1.3.1