Fileformats in KOSI

This Guide shows you the different fileformats KOSI uses and how to use them.

KOSI config.yaml

Default installation-location: /var/kubeops/kosi/config.yaml Location for usage: $KUBEOPSROOT/kosi/config.yaml

The config.yaml file contains all necessary settings for networking and logging. For example, config.yaml contains the hub from which the packages are downloaded. If you have custom values for your config, you have to put them in $KUBEOPSROOT/kosi/config.yaml. If KOSI cannot find the config.yaml, it will use the default values like in the example.

Example:

apiversion: kubernative/sina/config/v3                # Shows the supported API-Version
spec:                                            
  hub: https://dispatcher.kubeops.net/v4/dispatcher/  # Adress to the KOSI online hub
  plugins: <your kubeopsroot>/plugins/                # <-- set the path to your plugin folder (~ for home or $KUBEOPSROOT don't work, it has to be the full path)
  workspace: /tmp/kosi/process/                       # Workspace Path 
  logging: info                                       # Loglevel options: info (default), warning, error, debug1, debug2, debug3
  housekeeping: true                                  # Housekeeping options: true (all temporary created files and images (-r flag) will be deleted), false (all temporary created files and images won't be deleted)
  checkforupdates: false                              # <-- set to 'true' to enable update checks

Note

If a $KUBEOPSROOT variable is set and then KOSI is installed, removed or reinstalled, the KOSI config.yaml must be adapted to the path of the previously set $KUBEOPSROOT variable. Otherwise KOSI takes the default value which is /var/kubeops/kosi/config.yaml.

#apiversion: kubernative/sina/config/v3                # Shows the supported API-Version
#spec:                                            
  #hub: https://dispatcher.kubeops.net/v4/dispatcher/  # Adress to the KOSI online hub
 --> plugins: <your kubeopsroot>/plugins/              # <-- set the path to your plugin folder (~ for home or $KUBEOPSROOT don't work, it has to be the full path)
  #workspace: /tmp/kosi/process/                       # Workspace Path 
  #logging: info                                       # Loglevel options: info (default), warning, error, debug1, debug2, debug3
  #housekeeping: true                                  # Housekeeping options: true (all temporary created files and images (-r flag) will be deleted), false (all temporary created files and images won't be deleted)

If you want to use your own hub, you can create a user-specific config.yaml file. The original file can be changed too, but it is not recommended.

KOSI values.yaml

Example:

In the example is a package.kosi with an if plugin call, where the condition is templated.

values.yaml

firstparam: 1
secondparam: 2

More information about the if plugin can be found here if plugin Reference.

package.kosi

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
description = "kosi-example-package description";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

#Included files inside the kosi-package
files = 
{
  input="template.yaml";
}

#Included images inside the kosi-package. Default has to be changed
containers = 
{
    nginx = ["docker.io", "nginx", "latest"];
}

#Installation-section of the kosi-package
install 
{
    cmd(command = "echo using if plugin");

    if (condition = "{{values.firstparam}}<2") then
    {
        cmd(command = "echo using templated values.")
        cmd(command = "echo {{values.firstparam}} is smaller than 2");
    }
    else
    {
        cmd(command = "echo {{values.firstparam}} is bigger than 2");
    }
}

More information about the KOSI language can be found here KOSI Language Reference.

KOSI template.yaml

In KOSI there are two ways to template values. One of them is using a template.yaml, the other is using a values.yaml. This type of templating works with the template plugin.

For more information about the template syntax check the Scriban documentation

Example:

package:
  file: {{package.includes.files.input}}

KOSI package.kosi

The package.kosi file defines the properties of a KOSI package (.tgz). A default package.kosi is created after a kosi create command.

The file is used as input for the kosi build command. During the build process, KOSI translates the package.kosi file into a generated package.yaml.

A package.kosi file does contain mandatory metadata, included files, container definitions and task trees for install, update and delete operations.

If both package.kosi and package.yaml are available during the build process, package.kosi is preferred.

More information about the metadata and syntax of package.kosi can be found here KOSI Language Reference.

KOSI package.yaml

The package.yaml defines the properties of a KOSI package (.tgz). A package.yaml is created after a kosi build command with a valid package.kosi file.

The generated package.yaml contains package metadata, included files, container definitions and task definitions used during install, update and delete operations.

The includes.containers element is used for Docker images. The includes.files element describes the files which are included in the KOSI package. The installation.tasks tree describes the tasks which are executed with the kosi install command. The update.tasks tree describes the tasks which are executed with the kosi update command. The delete.tasks tree describes the tasks which are executed with the kosi delete command.

Example:

# languageversion: "0.1.0"
apiversion: "kubernative/kubeops/sina/user/v4"
name: "kosi-example-packagev3"
description: "kosi-example-package"
version: "0.1.0"
docs: "docs.tgz"
logo: "logo.png"
includes:
  files:
    input: "template.yaml"
  containers:
    example:
      registry: "docker.io"
      image: "nginx"
      tag: "latest"
installation:
  tasks:
    - cmd:
        command: "touch ~/kosiExample1"
update:
  tasks:
    - cmd:
        command: "touch ~/kosiExample2"
delete:
  tasks:
    - cmd:
        command: "rm ~/kosiExample1"
    - cmd:
        command: "rm ~/kosiExample2"

KOSI package.tgz

The package.tgz file is the KOSI package. It contains all metadata, included files, container and installation, update and delete tasks. A package.tgz is created after a kosi build command with a valid package.kosi or package.yaml file. The package.tgz is the artifact that will be pushed to the KubeOpsHub. There are some default files that are always included in the package.tgz, beside your included files.

Note: package.kosi will be preferred in the build process.

File	Description
docs.tgz	A Tgz with the documentation of the package, which contains Markdown files.
logo.png	A PNG for a logo of the package.
package.yaml	Generated KOSI package definition for task execution.
template.yaml	KOSI template file for templating values.