Fileformats

Fileformats in KOSI

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

KOSI config.yaml

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

The config.yaml file contains all necessary files 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 these in the $KUBEOPSROOT/kosi/config.yaml.
If KOSI can not find the config.yaml, it will use default like the example.

Example:

apiversion: kubernative/sina/config/v2                # Shows the supported API-Version
spec:                                            
  hub: https://hub.kubernative.net/v4/dispatcher/     # Adress to the KOSI online hub
  plugins: /kubeops/kosi/kosi-plugins/                # Location of the KOSI-Plugins
  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)

KOSI values.yaml

In KOSI there are two ways to template values and one of them is using a values.yaml the other is using the template.yaml. In a normal values.yaml you can do value templating like in helm.

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 find here if-plugin Reference.

package.kosi

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

files = 
{
  input="template.yaml";
}

containers = 
{
    example=["docker.io", "nginx", "latest"];
}

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"');
    }
}

KOSI template.yaml

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

How-to How to use templating within the package.kosi.

For more information about the template syntax check the Scriban documentation (https://github.com/scriban/scriban/blob/master/doc/language.md) and try it out in the online demo (https://scribanonline.azurewebsites.net/).

Example:

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

KOSI package.kosi

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

Metadata

There are a few metadata and they are mandatory.

IMPORTANT: Only use a fully lowercase as name for your package.
Note: Do not change name for logo.png and docs.tgz.
Note: Please name your markdown files inside docs.tgz without versions (docs/documentation-1.0.0.md).

The containers element is used for docker images. The methods which are used in the package.
The files element describes the files which are inluded in the KOSI package.
The installation tree describes the tasks (KOSI plugins), which are executed with the kosi install command.
The update tree describes the tasks (KOSI plugins), which are executed with the kosi update command.
The delete tree describes the tasks (KOSI plugins), which are executed with the kosi delete command.

Example

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

files =
{
  input="template.yaml";
}

containers =
{
    example=["docker.io", "nginx", "latest"];
}

install
{
    cmd(command='"touch ~/kosiExample1"');
}

update
{
    cmd(command='"touch ~/kosiExample2"');
}

delete
{
    cmd(command='"rm ~/kosiExample1"');
    cmd(command='"rm ~/kosiExample2"');
}

KOSI package.yaml

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

Metadata

There are a few metadata and they are mandatory.

IMPORTANT: Only use a fully lowercase as name for your package.
Note: Do not change name for logo.png and docs.tgz.
Note: Please name your markdown files inside docs.tgz without versions (docs/documentation-1.0.0.md).

The includes.containers element is used for docker images. The methods which are used in the package.
The includes.files element describes the files which are inluded in the KOSI package.
The installation tree describes the tasks (KOSI plugins), which are executed with the kosi install.tasks command.
The update.tasks tree describes the tasks (KOSI plugins), which are executed with the kosi update command.
The delete.tasks tree describes the tasks (KOSI plugins), which are executed with the kosi delete command.

# languageversion: "0.1.0"
apiversion: "kubernative/kubeops/sina/user/v3"
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 KOSI package contains all metadata and installation, update and delete tasks. A package.tgz is created after a kosi build-command with a valid package.kosi file. The package.tgz is the artefact that will pushed on the KubeOpsHub. There are some default files, that are always included in the KOSI package, beside your included files.
A package.tgz is created after a kosi build-command with a valid package.kosi or package.yaml file.

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