This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reference

In the reference you will find the full Kosi documentation as well as the file formats and the KOSI Language Reference.

1: Fileformats in KOSI
2: KOSI Language Reference
3: Full Documentation KOSI-2.15.x
4: Full Documentation KOSI-2.14.x
5: Full Documentation KOSI-2.13.x
6: Full Documentation KOSI-2.12.x
7: Full Documentation KOSI-2.11.x
8: Software Bill of Materials (SBOM)

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

2 - KOSI Language Reference

“This Guide explains the basic Structure of the package.kosi File using the if and cmd Plugins”

package.kosi File

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 each KOSI Plugin and their use can be found here Plugins.

Metadata

There are a few metadata and they are mandatory.

Parameter	Description
languageversion	KOSI language version specification.
apiversion	KOSI package version specification.
name	Set the name of the package, which will be displayed on the hub.
description	Set the description of the package, which will be displayed on the hub.
version	Set the version of the package, which will be displayed on the hub. The Versioning is semantic (“major.minor.patch” example: `1.0.1`)
docs	A Tgz with the documentation of the package, which contains Markdown files.
logo	A PNG for a logo of the package.

IMPORTANT: Only use a fully lowercase name for your package. Note: Do not change the names logo.png and docs.tgz. Note: Please name your Markdown files inside docs.tgz without versions, for example docs/documentation.md.

files

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

The files element describes the files which are included in the KOSI package.

When you build the package, the files element is written into package.yaml as includes.files.

containers

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

The containers element is used for docker images. The three element array clearly encodes exactly what KOSI needs to pull an image: the registry docker.io, the repository nginx and the tag latest.

When you build the package, that shorthand is rewritten into YAML form inside package.yaml as includes.containers.

The template exposes everything under the root object package. After the build, you can reference any part of the container definition with dot notation. Registry for example would be: {{package.includes.containers.example.registry}}

install

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 greater or equal to 2");
    }
}

In this section the logic of the used Plugins is described.

The cmd Plugin is for executing commands in the command line and the if Plugin is for creating conditions, under which other plugins are executed.

The main used trees are install for installing a new package, update for updating packages and delete for deleting packages.

3 - Full Documentation KOSI-2.15.x

KubeOps KOSI

How to use KOSI

This guide explains how to use KOSI with detailed instructions and examples.

General commands

Overview of all KOSI commands

kosi:
  Kosi is a software installer for kubernetes cluster

Usage:
  kosi [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    Login
  search                   Shows you all the available packages on the softwarehub
  build                    Builds your KOSI Package
  push                     Push package.tgz to your Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    Installs a .tgz file and if it is required, download it
  update <packagename>     Updates a .tgz file and if it is required, download it
  delete <packagename>     Runs delete section of a .tgz file and if it is required, download it
  list                     Lists packages from storage
  lint                     lint your files for your .kosi package
  version                  Basic infos about KOSI
  create                   Creates a package.yaml and a template.yaml for you to manipulate
  logout                   Logout
  remove <package>         Gives you the possibility to remove packages from the hub, if you have write permissions.
  encrypt                  Gives you the possibility to encrypt your values with a password.
  check <hash>             check your local package hash
  manage                   Manage permissions for users and groups
  tools                    KOSI TOOLS

Command ‘kosi –help’

The command kosi --help gives you an overview of all available commands:

kosi --help

Alternatively, you can also enter kosi or kosi -? in the command line.

Command ‘kosi version’

The kosi version command shows you the current version of KOSI.

kosi version

The output should be:

2026-06-30 16:07:35 Info:      KOSI version: 2.15.0.3_Beta0
2026-06-30 16:07:36 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-06-30 16:07:36 Info:      Latest KOSI-language-version is: 1.0.0
2026-06-30 16:07:36 Info:      This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
2026-06-30 16:07:36 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Command ‘kosi create’

Note : The command works in the current directory.

The command kosi create creates four files (package.kosi, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

Note : The template.yaml is required if the template engine Scriban is to be used.

Note : The logo.png is a package-thumbnail with the size of 50x50px

Note : The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md)..

kosi create

Created files:

package.kosi
template.yaml
logo.png - For showing logo on the KubeOpsHub.
docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘kosi build’

Note : The command works in the current working directory.

Note : If you have no package.kosi file in your current working directory, KOSI will pick a package.yaml file.

Note : Name your package in the package.kosi in full lower case.

Note : Don´t change the name for logo.png and docs.tgz

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

Important : Please name your packages without docker tags (:v1.0.0).

The kosi build command creates the necessary yaml files for building a package:

kosi build

All files specified in the package.kosi are combined together with the package.yaml to form a KOSI package.

Note : The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

-o flag

The -o parameter is used to specify your own package name.

kosi build -o mypackage.tgz

Note : This parameter is optional.
If you omit the parameter, the package name will be package.tgz.

-r flag

The -r parameter is used to push your container images to a registry at build time. Additionally, the image references in the package are rewritten to this registry.

kosi build -r registry.kubeops.net/myuser

Note : This parameter is optional.
It is helpful for transferring images from one registry to another.

Command ‘kosi lint’

The kosi lint command is used to check whether the contents of the package.yaml or package.kosi files are valid:

kosi lint

The kosi login command logs on to the KubeOps services. The account name is required for this command.

Note : To push packages into the hub, you need to create an account here first. We recommend lowercase usernames for your kubeops-accounts.

After the flag -u type your username. Afterwards you will be asked to enter your password.

kosi login -u <username>

The parameter -p is used to enter the password in the command directly, but it is important to know that the password will be shown in plain text. This parameter can help with the automation of KOSI commands.

kosi login -u <username> -p <password>

-u flag

The -u parameter is used to specify the user name.

kosi login -u

Note : This parameter is required.

-p flag

The -p parameter is used to specify the password.

kosi login -p

Note : This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘kosi logout’

The kosi logout command logs out from the KubeOps services.

Note : To logout from the KubeOps services, you have to be logged in.

kosi logout

Command ‘kosi push’

The kosi push command uploads KOSI packages to the KubeOps Hub:

kosi push --hub <hubname>

Note : In order to upload KOSI packages, you first have to log in using the kosi login command.

Note : The package name is case-sensitive and should be lowercase.

–hub flag

The --hub parameter is used to upload KOSI packages to a specific hub, e.g. in this example we upload our KOSI package to the myhub hub.

kosi push --hub myhub

Command ‘kosi pull’

The kosi pull command downloads a specific KOSI package from the hub without installing it directly.

kosi pull --hub <hubname> <packagename> -o <desired name>

Note : kosi pull downloads the package to the current directory.

Note : The downloaded packages can be transferred to machines without internet access via USB, for example.

Note : The package name is case-sensitive and should be lowercase.

Example:

kosi pull --hub myhub donald/kosi-print-test:0.0.1 -o printpackage

Note : The -o option specifies a name that the package will have after download. The file automatically gets the .tgz extension. The -o option is not optional.

–hub flag

The --hub parameter is used to download KOSI packages to a specific hub, e.g. in this example we are pulling our KOSI package from the myhub hub.

kosi pull --hub myhub kubeops/harbor:1.1.0

-r flag

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note : kosi pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0   -o harborpackage -r 127.0.0.1:5000

Note: After the kosi pull --hub myhub kubeops/harbor:1.1.0 -o printpackage -r 127.0.0.1:5000 command you can use kosi install -p printpackage.tgz to use the docker image from your local docker registry.

Note : You can now install your packages including docker images without internet connection from your local machine.

-t flag

For the szenario that the registry of the cluster is exposed to the admin via a network internal domain name, but this name can’t be resolved by the nodes, the flag -t can be used, to use the cluster internal hostname of the registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry> -t <cluster.internal.registry>

Note : local.docker.registry is the same registry as cluster.internal.registry but with a different hostname.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0 -o harborpackage -r myregistry:5000 -t clusterregistry:5000

Important : -t flag can only be used in combination with the -r flag.

Command ‘kosi search’

The kosi search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the package publisher.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the package description.
The Install column provides the package reference, which includes the publisher, package name, and version. Copy this reference to install the package using kosi install

kosi search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

kosi search --hub kosi-enterprise

| User | Name               | Version      | Description             | Install                              |
|------|--------------------|--------------|-------------------------|--------------------------------------|
| kosi | enterprise-plugins | 1.7.0        | KOSI Enterprise Plugins | kosi/enterprise-plugins:1.7.0        |
| kosi | enterprise-plugins | 1.7.1        | KOSI Enterprise Plugins | kosi/enterprise-plugins:1.7.1        |
| kosi | enterprise-plugins | 2.0.0        | KOSI Enterprise Plugins | kosi/enterprise-plugins:2.0.0        |
| kosi | enterprise-plugins | 2.2.0_Alpha1 | KOSI Enterprise Plugins | kosi/enterprise-plugins:2.2.0_Alpha1 |
| kosi | enterprise-plugins | 2.2.0_Beta0  | KOSI Enterprise Plugins | kosi/enterprise-plugins:2.2.0_Beta0  |

–ps flag

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

kosi search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

kosi search --hub kubeops --ps k9s

| User    | Name | Version  | Description | Install              |
|---------|------|----------|-------------|----------------------|
| kubeops | k9s  | v0.50.16 | Install k9s | kubeops/k9s:v0.50.16 |
| kubeops | k9s  | v0.50.18 | Install k9s | kubeops/k9s:v0.50.18 |

–hub flag

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the myhub hub.

kosi search --hub myhub

| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| kosi   | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi   | installation | 0.0.1   | kosi create example package.yaml | kosi/installation:0.0.1 |  
| donald | elk-kosi     | 0.0.1   | ELK installation                 | donald/elk-kosi:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |

The parameters --hub and --ps can be combined for a targeted search in the kosi hub:

kosi search --hub <hubname> --ps <package_name>

Example:
The user kosi wants to display all packages in the kosi hub with the term “lima”.

kosi search --hub kosi  --ps lima

| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| kosi | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi | lima         | 0.7.1   | installs LIMA                    | kosi/lima:0.7.1         |

Command ‘kosi encrypt’

The kosi encrypt command is used to encrypt YAML files with AES-256-CBC:

-f flag

The parameter -f must be used to use yaml files from the user.

Note : This parameter is required.

kosi encrypt -f <user.yaml>

Note : The -f parameter can be specified any number of times to use any number of files.

kosi encrypt -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : Once your file is encrypted, you cannot decrypt it with KOSI to obtain a decrypted file. KOSI decrypts the file at runtime when it is used.

Command ‘kosi install’

The kosi install command installs a KOSI package:

kosi install --hub <hubname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

–hub flag

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

kosi install --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Software Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

-p flag

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

kosi install -p package.tgz

-f flag

The parameter f must be used to use .yaml files from the user.

kosi install <package> -f <user.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi install <package> --cf <encryptedUser.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific encrypted files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

kosi install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a custom kubernetes namespace is used:

kosi install --hub myhub kosi/livedemo:2.7.1 --namespace mynamespace

Note : If no --namespace parameter is specified, the namespace default will be used.

–dname flag

The parameter dname can be used to save the package under a specific name.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a deployment name is set:

kosi install --hub myhub kosi/livedemo:2.7.1 --dname mydeployment

Note : If no --dname parameter is specified, a random deployment name will be generated.

Note : Deploymentnames are unique, the installation will stop if the deploymentname already exists.

Note : The deployment name is stored in the file /<user>/var/kubeops/kosi/deployment.yaml.

Command ‘kosi list’

The kosi list command lists all installed KOSI packages:

kosi list

 KOSI version: KOSI version: 2.15.0.3_Beta0
| Deployment   | Package                                                | PublicHub | Hub             |
|--------------|--------------------------------------------------------|-----------|-----------------|
| harbor       | local/harbor:2.0.0_Beta0                               |           | local           |
| rook-ceph    | local/rook-ceph:2.0.0_Beta0                            |           | local           |
| 273bac       | kosi/basic-plugins:2.2.0_Beta0                         |           | kosi-basic      |

Command ‘kosi update’

The kosi update command updates an already installed KOSI package:

Note : For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

kosi update --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiinstallslima is updated by a package from the myhub Software Hub from kosi.:

kosi update --hub myhub --dname kosiInstallsLima kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

kosi update --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi update --hub myhub kosi/livedemo:2.7.1

create:0.0.1

-p flag

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

kosi update -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi update --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and user specific files are to be used for the update progress:

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi update --hub <hubname> <package> --cf <encryptedUser.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and user specific encrypted files are to be used for the update progress:

kosi update --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

kosi update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi update --hub myhub kosi/livedemo:2.7.1 --namespace mynamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to update the deployment by name.

kosi update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a deployment name is set:

kosi update --hub myhub kosi/livedemo:2.7.1 --dname mydeployment

Command ‘kosi delete’

The kosi delete command deletes an already installed KOSI package:

Note : For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

kosi delete --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiinstallslima is deleted by a package from the myhub Software Hub from kosi.:

kosi delete --hub myhub --dname kosiInstallsLima kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

kosi delete --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi delete --hub myhub kosi/livedemo:2.7.1

create:0.0.1
-create:0.0.1

-p flag

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

kosi delete -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi delete --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and user specific files are to be used for the delete progress:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi delete --hub <hubname> <package> -f <encryptedUser.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and user specific encrypted files are to be used for the delete progress:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f encryptedUserfile1.yaml -f encryptedUserfile2.yaml -f encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

kosi delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi delete --hub myhub kosi/livedemo:2.7.1 --namespace mynamespace

Note : If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to delete the deployment by name.

kosi delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a deployment name is set:

kosi delete --hub myhub kosi/livedemo:2.7.1 --dname mydeployment

Command ‘kosi remove’

The kosi remove command removes a KOSI package from the hub:

Note : Only logged users can delete there OWN packages on their OWN hubs.

kosi remove --hub <hubname> <package>

Note : The package you want to remove can be found in the output of the kosi search command, more precisely in the install column

Example: The package livedemo of the user kosi with version 2.7.1 will be removed from the myhub hub:

kosi remove --hub myhub kosi/livedemo:2.7.1

Note : If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

Command ‘kosi check’

The kosi check command is used to compare a local kosi package with a sha256 Checksum.

kosi check -p <localpackagename> <sha256 hash>

Example:

kosi check -p examplepackage c83f3db9639e175f82e7d07d342533866873e2d9ca2f0fd5ee607ea395417edb

Command ‘kosi manage add user’

The kosi manage add user command is used to add user permissions.

–username [-u]

The parameter username is the user who should be added.

–action [-a]

The parameter action is the action that is to be authorized (one of view, read, write, owner).

–hub

The parameter hub is the hub for which the user should be authorized.

–duration [-d]

The parameter duration is the duration for which the user should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add user --username <username> --action <action> --hub <hub> --duration <duration>

Example:

kosi manage add user --username alice --action view --hub rabbithutch --duration 10d

Command ‘kosi manage add group’

The kosi manage add group command is used to add group permissions.

–groupname [-g]

The parameter groupname is the group to be added.

–action [-a]

The parameter action is the action that should be taken for the group (one of view, read, write, owner).

–hub

The parameter hub is the hub where the group should be added.

–duration [-d]

The parameter duration is the duration for which the group should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add group --groupname <groupname> --action <action> --hub <hub> --duration <duration>

Example:

kosi manage add group --groupname hatter --action view --hub rabbithutch --duration 10d

Command ‘kosi manage add user-to-group’

The kosi manage add user-to-group command is used to add a user to a group.

–username [-u]

The parameter username is the user to be added.

–groupname [-g]

The parameter groupname is the group to be added.

–duration [-d]

The parameter duration is the duration for which the group should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add user-to-group --username <username> --groupname <groupname> --duration <duration>

Example:

kosi manage add user-to-group --username alice --groupname royalcourt --duration 10d

Command ‘kosi manage create group’

The kosi manage create group command is used to create a group on a hub.

–groupname [-g]

The parameter groupname is the group to be added.

–hub

The parameter hub is the hub where the group should be added.

kosi manage create group --groupname <group> --hub <hub>

Example:

kosi manage create group --groupname royalcourt --hub rabbithutch

Command ‘kosi manage list permissions’

The kosi manage list permissions command is used to list permissions for a hub.

–hub

The parameter hub is the hub for which the permissions should be displayed.

kosi manage list permissions --hub <hub>

Example:

kosi manage list permissions --hub rabbithutch

Command ‘kosi manage remove user’

The kosi manage remove user command is used to remove a user for a hub.

–username [-u]

The parameter username is the user to be removed.

–hub

The parameter hub is the hub from which the user should be removed.

kosi manage remove user --username <username> --hub <hub>

Example:

kosi manage remove user --username alice --hub rabbithutch

Command ‘kosi manage remove group’

The kosi manage remove group command is used to remove a group from a hub.

–groupname [-g]

The parameter groupname is the group to be removed.

–hub

The parameter hub is the hub from which the group should be removed.

kosi manage remove group --groupname <groupname> --hub <hub>

Example:

kosi manage remove group --groupname royalcourt --hub rabbithutch

Command ‘kosi manage remove permission’

The kosi manage remove permission command is used to remove permissions.

–username [-u]

The parameter username is the user for whom the permission should be removed.

–groupname [-g]

The parameter groupname is the group for which the permission should be removed.

–action [-a]

The parameter action is the action that should be removed (one of view, read, write, owner).

–hub

The parameter hub is the hub from which the group should be removed.

kosi manage remove permission --groupname <groupname> --action <action> --hub <hub>

Example:

kosi manage remove permission --groupname royalcourt --action write --hub rabbithutch

Command ‘kosi manage remove user-from-group’

The kosi manage remove user-from-group command is used to remove a user from a group.

–username [-u]

The parameter username is the user who should be removed.

–groupname [-g]

The parameter groupname is the group from which the user should be removed.

kosi manage remove user-from-group --username <username> --groupname <groupname>

Example:

kosi manage remove user-from-group --username alice --groupname royalcourt

Command ‘kosi tools’

The kosi tools command provides additional KOSI tools and options.

kosi tools [options] [command]

Options

-?, -h, --help    Show help and usage information

Commands

yq <query>            KOSI tool yq
docs <packagename>    Show docs for kosi package
sbom <packagename>    Show sbom for kosi package

Command ‘kosi tools yq’

The kosi tools yq command runs the yq tool. It can be used to read, convert and modify YAML, JSON, XML and other supported file formats.

kosi tools yq [flags]
kosi tools yq [command]

Example: Read the stuff from a YAML file:

kosi tools yq '.stuff' < myfile.yaml

Example: Update a YAML file in place:

kosi tools yq -i '.stuff = "morestuff"' myfile.yaml

Example: Print a JSON file as YAML:

kosi tools yq -P -oy sample.json

Note : Use kosi tools yq --help to show all available yq commands and flags.

Command ‘kosi tools docs’

The kosi tools docs command shows the documentation of a KOSI package. The documentation can be shown from a local package or from a package on the hub.

kosi tools docs [options] [<package>]

Arguments

<package>    The KOSI package for which the documentation should be shown.

local-package, -p flag

The -p parameter is used to show the documentation from a local KOSI package.

kosi tools docs -p <local-package>

–hub flag

The --hub parameter is used to show the documentation from a package on the hub.

kosi tools docs --hub <hubname> <package>

Note : Package names are case-sensitive. Use lowercase package names.

Command ‘kosi tools sbom’

The kosi tools sbom command shows the Software Bill of Materials (SBOM) of a KOSI package. The SBOM can be shown from a local package or from a package on the hub.

kosi tools sbom [options] [<package>]

Arguments

<package>    The KOSI package for which the SBOM should be shown.

local-package, -p flag

The -p parameter is used to show the SBOM from a local KOSI package.

kosi tools sbom -p <local-package>

–hub flag

The --hub parameter is used to show the SBOM from a package on the hub.

kosi tools sbom --hub <package>

Example:

kosi tools sbom --hub kosi/livedemo:2.7.1

Note : Package names are case-sensitive. Use lowercase package names.

File Formats

package.kosi

This file defines properties of the KOSI package. This file is created after the kosi create command. The package.kosi defines a package in a specific version as well as the tasks needed to install it. The tasks which are used in the package.yaml are plugins, which can be created by the user. The includes.containers element is used for docker images. A container for the docker images will be created when the kosi install, kosi update or kosi delete command is used. There is also a description, which will be shown in the kosi search command. The includes.files element describes the files which are included in the KOSI package. The installation.tasks tree describes the tasks (KOSI plugins), which are executed with the kosi install 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.

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

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 = 
{
    changeme=["registry", "imagename", "tag"];
}

#Installation-section of the kosi-package
install 
{
    #Add install commands here
}

#Update-section of the kosi-package
update 
{
    #Add update commands here
}

#Delete-section of the kosi-package
delete 
{
    #Add delete commands here
}

package.yaml

This file defines properties of the KOSI package. This file is created after the kosi build command. The package.yaml defines a package in a specific version as well as the tasks needed to install it. The tasks which are used in the package.yaml are plugins, which can be created by the user. The includes.containers element is used for docker images. A container for the docker images will be created when the kosi install, kosi update or kosi delete command is used. There is also a description, which will be shown in the kosi search command. The includes.files element describes the files which are inluded in the KOSI package. The installation.tasks tree describes the tasks (KOSI plugins), which are executed with the kosi install 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.

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

# languageversion: "1.0.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"

default.yaml

The default.yaml in a package.tgz is used for setting default variables. In case you use the -f parameter in install, update or delete, the file which you address is merged with the default.yaml. If you have the same keys but different values in both files, your adressed file will overwrite the values set by the default.yaml.

config.yaml

Note : Default location for: /var/kubeops/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.

apiversion: kubernative/sina/config/v3                # Shows the supported API-Version
spec:                                            
  hub: https://dispatcher.kubeops.net/v4/dispatcher/  # Address to the KOSI online hub
  plugins: /var/kubeops/plugins/                      # Location of the KOSI-Plugins
  workspace: /tmp/kosi/process/                       # Workspace Path 
  logging: info                                       # Loglevel options: info (default), warning, error, debug1, debug2, debug3
  housekeeping: false                                 # Housekeeping options: true (all temporary created folders will be deleted), false (all temporary created folders won't be deleted)
  proxy: false                                        # Use kosi proxy false (default) 
  checkforupdates: false                              # Set to true to auto-check for newer Kosi versions. Default: false

Note : KOSI uses Workspaces for processing the packages. These workspaces can be deleted if you using CLI-commands and setting the housekeeping to true. Plugins also will operate in this workspace.

Usage

To keep KOSI running there has to be a valid config.yaml file.
After installing KOSI, a valid config.yaml file is created under the location /var/kubeops/kosi/config.yaml. 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.

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins

Note : If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.kosi

This is an example of how templating in a package.kosi is working with kosi 2.15.x

First we need to create this 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 = 
{
    changeme=["registry", "imagename", "tag"];
}

#Installation-section of the kosi-package
install 
{
  template(tmpl = "{{package.includes.files.input}}"; target = "{{values.target}}");
}

#Update-section of the kosi-package
update 
{
  template(tmpl = "{{package.includes.files.input}}"; target = "{{values.target}}");
}

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.example}}

Next we create a default.yaml:

example: example
target: target.yaml

Note : Please make sure that you create all these files in the same directory.

Now we are ready to create a kosi package. For this we need the following command:

kosi build

Next we can run the installation section we have defined in the package.yaml with the following command:

kosi install -p package.tgz --dname example

We can check the result in the directory $KUBEOPSROOT/kosi/tmp.

The file of interest is the target.yaml. But most of the time this file is not in tmp Folder . In this case, type the command find / -name target.yaml to find the location of the target.yaml file.

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

So what exactly happened?
In the package.yaml you can see that we use {{package.includes.files.input}} for defining the template.yaml as value for the key tmpl. You can use any value of the package.yaml but make sure that the path to the value is correct and starts with package.. This is the indicator for using a variable from the package.yaml.

You can also see that we use {{values.target}} for defining the target.yaml as value for the key target. If you wonder where the target.yaml is coming from you can check the default.yaml. If you want to use a variable from the default.yaml or from a file specified with the parameter -f make sure that the path to the value is correct and starts with values..

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

Plugins

With the installation of KOSI a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References

4 - Full Documentation KOSI-2.14.x

KubeOps KOSI

How to use KOSI

This guide explains how to use KOSI with detailed instructions and examples.

General commands

Overview of all KOSI commands

kosi:
  Kosi is a software installer for kubernetes cluster

Usage:
  Kosi [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    logs you in
  search                   Shows you all the available packages on the softwarehub
  build                    Creates your final kosi.package
  push                     Push package.tgz to KubeOps Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    install a .tgz file and if it is required, download it
  update <packagename>     update a .tgz file and if it is required, download it
  delete <packagename>     run delete section of a .tgz file and if it is required, download it
  list                     List packages from storage
  lint                     lint your files for your .tgz package
  create                   Creates a package.kosi and a template.yaml for you to manipulate
  version                  Basic infos about KOSI
  logout                   Logout
  remove <package>         Gives you the possibility to remove packages from the hub, if you have write permissions.
  encrypt                  Gives you the possibility to encrypt your values with a password.
  check <hash>             check your local package hash
  manage                   Manage permissions for users and groups

Command ‘kosi –help’

The command kosi --help gives you an overview of all available commands:

kosi --help

Alternatively, you can also enter kosi or kosi -? in the command line.

Command ‘kosi version’

The kosi version command shows you the current version of KOSI.

kosi version

The output should be:

2026-01-23 08:57:23 Info:      KOSI version: 2.14.0.0
2026-01-23 08:57:23 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-01-23 08:57:23 Info:      Latest KOSI-language-version is: 1.0.0
2026-01-23 08:57:23 Info:      This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
2026-01-23 08:57:23 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Command ‘kosi create’

Note : The command works in the current directory.

The command kosi create creates four files (package.kosi, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

Note : The template.yaml is required if the template engine Scriban is to be used.

Note : The logo.png is a package-thumbnail with the size of 50x50px

Note : The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md)..

kosi create

Created files:

package.kosi
template.yaml
logo.png - For showing logo on the KubeOpsHub.
docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘kosi build’

Note : The command works in the current working directory.

Note : If you have no package.kosi file in your current working directory, KOSI will pick a package.yaml file.

Note : Name your package in the package.kosi in full lower case.

Note : Don´t change the name for logo.png and docs.tgz

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

Important : Please name your packages without docker tags (:v1.0.0).

The kosi build command creates the necessary yaml files for building a package:

kosi build

All files specified in the package.kosi are combined together with the package.yaml to form a KOSI package.

Note : The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

-o flag

The -o parameter is used to specify your own package name.

kosi build -o mypackage.tgz

Note : This parameter is optional.
If you omit the parameter, the package name will be package.tgz.

-r flag

The -r parameter is used to push your container images to a registry at build time. Additionally, the image references in the package are rewritten to this registry.

kosi build -r registry.kubeops.net/myuser

Note : This parameter is optional.
It is helpful for transferring images from one registry to another.

Command ‘kosi lint’

The kosi lint command is used to check whether the contents of the package.yaml or package.kosi files are valid:

kosi lint

The kosi login command logs on to the KubeOps services. The account name is required for this command.

Note : To push packages into the hub, you need to create an account here first. We recommend lowercase usernames for your kubeops-accounts.

After the flag -u type your username. Afterwards you will be asked to enter your password.

kosi login -u <username>

kosi login -u <username> -p <password>

-u flag

The -u parameter is used to specify the user name.

kosi login -u

Note : This parameter is required.

-p flag

The -p parameter is used to specify the password.

kosi login -p

Note : This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘kosi logout’

The kosi logout command logs out from the KubeOps services.

Note : To logout from the KubeOps services, you have to be logged in.

kosi logout

Command ‘kosi push’

The kosi push command uploads KOSI packages to the KubeOps Hub:

kosi push --hub <hubname>

Note : In order to upload KOSI packages, you first have to log in using the kosi login command.

Note : The package name is case-sensitive and should be lowercase.

–hub flag

The --hub parameter is used to upload KOSI packages to a specific hub, e.g. in this example we upload our KOSI package to the myhub hub.

kosi push --hub myhub

Command ‘kosi pull’

The kosi pull command downloads a specific KOSI package from the hub without installing it directly.

kosi pull --hub <hubname> <packagename> -o <desired name>

Note : kosi pull downloads the package to the current directory.

Note : The downloaded packages can be transferred to machines without internet access via USB, for example.

Note : The package name is case-sensitive and should be lowercase.

Example:

kosi pull --hub myhub donald/kosi-print-test:0.0.1 -o printpackage

Note : The -o option specifies a name that the package will have after download. The file automatically gets the .tgz extension. The -o option is not optional.

–hub flag

The --hub parameter is used to download KOSI packages to a specific hub, e.g. in this example we are pulling our KOSI package from the myhub hub.

kosi pull --hub myhub kubeops/harbor:1.1.0

-r flag

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note : kosi pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0   -o harborpackage -r 127.0.0.1:5000

Note: After the kosi pull --hub myhub kubeops/harbor:1.1.0 -o printpackage -r 127.0.0.1:5000 command you can use kosi install -p printpackage.tgz to use the docker image from your local docker registry.

Note : You can now install your packages including docker images without internet connection from your local machine.

-t flag

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry> -t <cluster.internal.registry>

Note : local.docker.registry is the same registry as cluster.internal.registry but with a different hostname.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0 -o harborpackage -r myregistry:5000 -t clusterregistry:5000

Important : -t flag can only be used in combination with the -r flag.

Command ‘kosi search’

The kosi search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the creator of the package.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the description of the package.
The Install column contains a string consisting of the name of the creator, name and version of the package. This string can be copied and used for the kosi install command.

kosi search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

kosi search --hub kosi-enterprise

| User | Name               | Version      | Description             | Install                              |
|------|--------------------|--------------|-------------------------|--------------------------------------|
| kosi | enterprise-plugins | 1.7.0        | KOSI Enterprise Plugins | kosi/enterprise-plugins:1.7.0        |
| kosi | enterprise-plugins | 1.7.1        | KOSI Enterprise Plugins | kosi/enterprise-plugins:1.7.1        |
| kosi | enterprise-plugins | 2.0.0        | KOSI Enterprise Plugins | kosi/enterprise-plugins:2.0.0        |

–ps flag

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

kosi search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

kosi search --hub kubeops --ps k9s

| User    | Name | Version  | Description | Install              |
|---------|------|----------|-------------|----------------------|
| kubeops | k9s  | v0.50.16 | Install k9s | kubeops/k9s:v0.50.16 |
| kubeops | k9s  | v0.50.18 | Install k9s | kubeops/k9s:v0.50.18 |

–hub flag

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the myhub hub.

kosi search --hub myhub

| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| kosi   | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi   | installation | 0.0.1   | kosi create example package.yaml | kosi/installation:0.0.1 |  
| donald | elk-kosi     | 0.0.1   | ELK installation                 | donald/elk-kosi:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |

The parameters --hub and --ps can be combined for a targeted search in the kosi hub:

kosi search --hub <hubname> --ps <package_name>

Example:
The user kosi wants to display all packages in the kosi hub with the term “lima”.

kosi search --hub kosi  --ps lima

| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| kosi | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi | lima         | 0.7.1   | installs LIMA                    | kosi/lima:0.7.1         |

Command ‘kosi encrypt’

The kosi encrypt command is used to encrypt YAML files with AES-256-CBC:

-f flag

The parameter -f must be used to use yaml files from the user.

Note : This parameter is required.

kosi encrypt -f <user.yaml>

Note : The -f parameter can be specified any number of times to use any number of files.

kosi encrypt -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : Once your file is encrypted, you cannot decrypt it with KOSI to obtain a decrypted file. KOSI decrypts the file at runtime when it is used.

Command ‘kosi install’

The kosi install command installs a KOSI package:

kosi install --hub <hubname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

–hub flag

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

kosi install --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Software Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

-p flag

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

kosi install -p package.tgz

-f flag

The parameter f must be used to use .yaml files from the user.

kosi install <package> -f <user.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi install <package> --cf <encryptedUser.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific encrypted files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

kosi install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a custom kubernetes namespace is used:

kosi install --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note : If no --namespace parameter is specified, the namespace default will be used.

–dname flag

The parameter dname can be used to save the package under a specific name.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a deployment name is set:

kosi install --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Note : If no --dname parameter is specified, a random deployment name will be generated.

Note : Deploymentnames are unique, the installation will stop if the deploymentname already exists.

Note : The deployment name is stored in the file /<user>/var/kubeops/kosi/deployment.yaml.

Command ‘kosi list’

The kosi list command lists all installed KOSI packages:

kosi list

 KOSI version: 2.10.0_preAlpha0
| Deployment       | Package                           | PublicHub | Hub    |
|------------------|-----------------------------------|-----------|--------|
| kosiinstallslima | kosi/lima:0.6.2                   |           | private|
| kosicreatetest   | kosi/kosi-create:0.0.1            |           | public |
| plugininstall    | local/kubeops-basic-plugins:0.4.0 |           | local  |

Command ‘kosi update’

The kosi update command updates an already installed KOSI package:

Note : For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

kosi update --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is updated by a package from the myhub Software Hub from kosi.:

kosi update --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

kosi update --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi update --hub myhub kosi/livedemo:2.7.1

create:0.0.1

-p flag

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

kosi update -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi update --hub <hubname> <package> -f <user.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi update --hub <hubname> <package> --cf <encryptedUser.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

kosi update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi update --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to update the deployment by name.

kosi update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a deployment name is set:

kosi update --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi delete’

The kosi delete command deletes an already installed KOSI package:

Note : For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

kosi delete --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is deleted by a package from the myhub Software Hub from kosi.:

kosi delete --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

kosi delete --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi delete --hub myhub kosi/livedemo:2.7.1

create:0.0.1
-create:0.0.1

-p flag

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

kosi delete -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi delete --hub <hubname> <package> -f <user.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi delete --hub <hubname> <package> -f <encryptedUser.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f encryptedUserfile1.yaml -f encryptedUserfile2.yaml -f encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

kosi delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi delete --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note : If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to delete the deployment by name.

kosi delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a deployment name is set:

kosi delete --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi remove’

The kosi remove command removes a KOSI package from the hub:

Note : Only logged users can delete there OWN packages on their OWN hubs.

kosi remove --hub <hubname> <package>

Note : The package you want to remove can be found in the output of the kosi search command, more precisely in the install column

Example: The package livedemo of the user kosi with version 2.7.1 will be removed from the myhub hub:

kosi remove --hub myhub kosi/livedemo:2.7.1

Note : If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

Command ‘kosi check’

The kosi check command is used to compare a local kosi package with a sha256 Checksum.

kosi check -p <localpackagename> <sha256 hash>

Example:

kosi check -p examplepackage c83f3db9639e175f82e7d07d342533866873e2d9ca2f0fd5ee607ea395417edb

Command ‘kosi manage add user’

The kosi manage add user command is used to add user permissions.

–username [-u]

The parameter username is the user who should be added.

–action [-a]

The parameter action is the action that is to be authorized (one of view, read, write, owner).

–hub

The parameter hub is the hub for which the user should be authorized.

–duration [-d]

The parameter duration is the duration for which the user should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add user --username <username> --action <action> --hub <hub> --duration <duration>

Example:

kosi manage add user --username alice --action view --hub rabbithutch --duration 10d

Command ‘kosi manage add group’

The kosi manage add group command is used to add group permissions.

–groupname [-g]

The parameter groupname is the group to be added.

–action [-a]

The parameter action is the action that should be taken for the group (one of view, read, write, owner).

–hub

The parameter hub is the hub where the group should be added.

–duration [-d]

The parameter duration is the duration for which the group should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add group --groupname <groupname> --action <action> --hub <hub> --duration <duration>

Example:

kosi manage add group --groupname hatter --action view --hub rabbithutch --duration 10d

Command ‘kosi manage add user-to-group’

The kosi manage add user-to-group command is used to add a user to a group.

–username [-u]

The parameter username is the user to be added.

–groupname [-g]

The parameter groupname is the group to be added.

–duration [-d]

The parameter duration is the duration for which the group should be authorized (format e.g. 10d, 1y, 86400s).

kosi manage add user-to-group --username <username> --groupname <groupname> --duration <duration>

Example:

kosi manage add user-to-group --username alice --groupname royalcourt --duration 10d

Command ‘kosi manage create group’

The kosi manage create group command is used to create a group on a hub.

–groupname [-g]

The parameter groupname is the group to be added.

–hub

The parameter hub is the hub where the group should be added.

kosi manage create group --groupname <group> --hub <hub>

Example:

kosi manage create group --groupname royalcourt --hub rabbithutch

Command ‘kosi manage list permissions’

The kosi manage list permissions command is used to list permissions for a hub.

–hub

The parameter hub is the hub for which the permissions should be displayed.

kosi manage list permissions --hub <hub>

Example:

kosi manage list permissions --hub rabbithutch

Command ‘kosi manage remove user’

The kosi manage remove user command is used to remove a user for a hub.

–username [-u]

The parameter username is the user to be removed.

–hub

The parameter hub is the hub from which the user should be removed.

kosi manage remove user --username <username> --hub <hub>

Example:

kosi manage remove user --username alice --hub rabbithutch

Command ‘kosi manage remove group’

The kosi manage remove group command is used to remove a group from a hub.

–groupname [-g]

The parameter groupname is the group to be removed.

–hub

The parameter hub is the hub from which the group should be removed.

kosi manage remove group --groupname <groupname> --hub <hub>

Example:

kosi manage remove group --groupname royalcourt --hub rabbithutch

Command ‘kosi manage remove permission’

The kosi manage remove permission command is used to remove permissions.

–username [-u]

The parameter username is the user for whom the permission should be removed.

–groupname [-g]

The parameter groupname is the group for which the permission should be removed.

–action [-a]

The parameter action is the action that should be removed (one of view, read, write, owner).

–hub

The parameter hub is the hub from which the group should be removed.

kosi manage remove group --groupname <groupname> --hub <hub>

Example:

kosi manage remove group --groupname royalcourt --hub rabbithutch

Command ‘kosi manage remove user-from-group’

The kosi manage remove user-from-group command is used to remove a user from a group.

–username [-u]

The parameter username is the user who should be removed.

–groupname [-g]

The parameter groupname is the group from which the user should be removed.

kosi manage remove user-from-group --username <username> --groupname <groupname>

Example:

kosi manage remove user-from-group --username alice --groupname royalcourt

File Formats

package.kosi

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

languageversion = "1.0.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");
}

package.yaml

⚠ Warning : The apiversion has been changed from …/user/v2 to …/user/v3. The Image Key has been split into to separate Keys registry and image.

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

# languageversion: "1.0.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"

default.yaml

config.yaml

Note : Default location for: /var/kubeops/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.

apiversion: kubernative/sina/config/v2                # Shows the supported API-Version
spec:                                            
  hub: https://dispatcher.kubeops.net/v4/dispatcher/  # Address to the KOSI online hub
  plugins: /var/kubeops/plugins/                      # Location of the KOSI-Plugins
  workspace: /tmp/kosi/process/                       # Workspace Path 
  logging: info                                       # Loglevel options: info (default), warning, error, debug1, debug2, debug3
  housekeeping: false                                 # Housekeeping options: true (all temporary created folders will be deleted), false (all temporary created folders won't be deleted)
  proxy: false                                        # Use kosi proxy false (default)

Usage

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins

Note : If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.kosi

This is an example of how templating in a package.kosi is working with kosi 2.14.x

First we need to create this package.kosi:

languageversion = "1.0.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 template plugin.");
    template(tmpl = "{{package.includes.files.input}}"; target = "{{values.target}}");
}

update
{
    cmd(command = "touch ~/kosiExample2");
    template(tmpl = "{{package.includes.files.input}}"; target = "{{values.target}}");
}

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

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.example}}

Next we create a default.yaml:

example: example
target: target.yaml

Note : Please make sure that you create all these files in the same directory.

Now we are ready to create a kosi package. For this we need the following command:

kosi build

Next we can run the installation section we have defined in the package.yaml with the following command:

kosi install -p package.tgz --dname example

We can check the result in the directory $KUBEOPSROOT/kosi/tmp.

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

Plugins

With the installation of KOSI a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References

5 - Full Documentation KOSI-2.13.x

KubeOps KOSI

How to use KOSI

This guide explains how to use KOSI with detailed instructions and examples.

General commands

Overview of all KOSI commands

kosi:
  Kosi is a SoftwareINstAller for kubernetes cluster

Usage:
  Kosi [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    logs you in
  search                   Shows you all the available packages on the softwarehub
  build                    Creates your final kosi.package
  push                     Push package.tgz to KubeOps Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    install a .tgz file and if it is required, download it
  update <packagename>     update a .tgz file and if it is required, download it
  delete <packagename>     run delete section of a .tgz file and if it is required, download it
  list                     List packages from storage
  lint                     lint your files for your .tgz package
  create                   Creates a package.kosi and a template.yaml for you to manipulate
  version                  Basic infos about KOSI
  logout                   Logout
  remove <package>         Gives you the possibility to remove packages from the hub, if you have write permissions.
  encrypt                  Gives you the possibility to encrypt your values with a password.
  check <hash>             check your local package hash

Command ‘kosi –help’

The command kosi --help gives you an overview of all available commands:

kosi --help

Alternatively, you can also enter kosi or kosi -? in the command line.

Command ‘kosi version’

The kosi version command shows you the current version of KOSI.

kosi version

The output should be:

2025-03-18 08:07:41 Info:      KOSI version: 2.13.0.1
2025-03-18 08:07:41 Info:      Latest KOSI-package-apiversion is: kubernative/kubeops/sina/user/v4
2025-03-18 08:07:41 Info:      Latest KOSI-language-version is: 1.0.0
2025-03-18 08:07:41 Info:      This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
2025-03-18 08:07:41 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Command ‘kosi create’

Note : The command works in the current directory.

The command kosi create creates four files (package.kosi, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

Note : The template.yaml is required if the template engine Scriban is to be used.

Note : The logo.png is a package-thumbnail with the size of 50x50px

Note : The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md)..

kosi create

Created files:

package.kosi
template.yaml
logo.png - For showing logo on the KubeOpsHub.
docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘kosi build’

Note : The command works in the current working directory.

Note : If you have no package.kosi file in your current working directory, KOSI will pick a package.yaml file.

Note : Name your package in the package.kosi in full lower case.

Note : Don´t change the name for logo.png and docs.tgz

Note : Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

Important : Please name your packages without docker tags (:v1.0.0).

The kosi build command creates the necessary yaml files for building a package:

kosi build

All files specified in the package.kosi are combined together with the package.yaml to form a KOSI package.

Note : The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

Command ‘kosi lint’

The kosi lint command is used to check whether the contents of the package.yaml or package.kosi files are valid:

kosi lint

The kosi login command logs on to the KubeOps services. The account name is required for this command.

Note : To push packages into the hub, you need to create an account here first. We recommend lowercase usernames for your kubeops-accounts.

After the flag -u type your username. Afterwards you will be asked to enter your password.

kosi login -u <username>

kosi login -u <username> -p <password>

-u flag

The -u parameter is used to specify the user name.

kosi login -u

Note : This parameter is required.

-p flag

The -p parameter is used to specify the password.

kosi login -p

Note : This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘kosi logout’

The kosi logout command logs out from the KubeOps services.

Note : To logout from the KubeOps services, you have to be logged in.

kosi logout

Command ‘kosi push’

The kosi push command uploads KOSI packages to the KubeOps Hub:

kosi push --hub <hubname>

Note : In order to upload KOSI packages, you first have to log in using the kosi login command.

Note : The package name is case-sensitive and should be lowercase.

–hub flag

The --hub parameter is used to upload KOSI packages to a specific hub, e.g. in this example we upload our KOSI package to the myhub hub.

kosi push --hub myhub

Command ‘kosi pull’

The kosi pull command downloads a specific KOSI package from the hub without installing it directly.

kosi pull --hub <hubname> <packagename> -o <desired name>

Note : kosi pull downloads the package to the current directory.

Note : The downloaded packages can be transferred to machines without internet access via USB, for example.

Note : The package name is case-sensitive and should be lowercase.

Example:

kosi pull --hub myhub donald/kosi-print-test:0.0.1 -o printpackage

Note : The -o option specifies a name that the package will have after download. The file automatically gets the .tgz extension. The -o option is not optional.

–hub flag

The --hub parameter is used to download KOSI packages to a specific hub, e.g. in this example we are pulling our KOSI package from the myhub hub.

kosi pull --hub myhub kubeops/harbor:1.1.0

-r flag

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note : kosi pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0   -o harborpackage -r 127.0.0.1:5000

Note: After the kosi pull --hub myhub kubeops/harbor:1.1.0 -o printpackage -r 127.0.0.1:5000 command you can use kosi install -p printpackage.tgz to use the docker image from your local docker registry.

Note : You can now install your packages including docker images without internet connection from your local machine.

-t flag

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry> -t <cluster.internal.registry>

Note : local.docker.registry is the same registry as cluster.internal.registry but with a different hostname.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0 -o harborpackage -r myregistry:5000 -t clusterregistry:5000

Important : -t flag can only be used in combination with the -r flag.

Command ‘kosi search’

The kosi search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the creator of the package.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the description of the package.
The Install column contains a string consisting of the name of the creator, name and version of the package. This string can be copied and used for the kosi install command.

kosi search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

kosi search --hub donald

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |
| donald | livedemo     | 2.7.2   | welcome to kosi                  | donald/livedemo:2.7.1     |

–ps flag

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

kosi search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

kosi search --hub donald --ps private

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |

–hub flag

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the myhub hub.

kosi search --hub myhub

| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| kosi   | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi   | installation | 0.0.1   | kosi create example package.yaml | kosi/installation:0.0.1 |  
| donald | elk-kosi     | 0.0.1   | ELK installation                 | donald/elk-kosi:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |

The parameters --hub and --ps can be combined for a targeted search in the kosi hub:

kosi search --hub <hubname> --ps <package_name>

Example:
The user kosi wants to display all packages in the kosi hub with the term “lima”.

kosi search --hub kosi  --ps lima

| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| kosi | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi | lima         | 0.7.1   | installs LIMA                    | kosi/lima:0.7.1         |

Command ‘kosi encrypt’

The kosi encrypt command is used to encrypt YAML files with AES-256-CBC:

-f flag

The parameter -f must be used to use yaml files from the user.

Note : This parameter is required.

kosi encrypt -f <user.yaml>

Note : The -f parameter can be specified any number of times to use any number of files.

kosi encrypt -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : Once your file is encrypted, you cannot decrypt it with KOSI to obtain a decrypted file. KOSI decrypts the file at runtime when it is used.

Command ‘kosi install’

The kosi install command installs a KOSI package:

kosi install --hub <hubname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

–hub flag

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

kosi install --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Software Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

-p flag

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

kosi install -p package.tgz

-f flag

The parameter f must be used to use .yaml files from the user.

kosi install <package> -f <user.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi install <package> --cf <encryptedUser.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific encrypted files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

kosi install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a custom kubernetes namespace is used:

kosi install --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note : If no --namespace parameter is specified, the namespace default will be used.

–dname flag

The parameter dname can be used to save the package under a specific name.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a deployment name is set:

kosi install --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Note : If no --dname parameter is specified, a random deployment name will be generated.

Note : Deploymentnames are unique, the installation will stop if the deploymentname already exists.

Note : The deployment name is stored in the file /<user>/var/kubeops/kosi/deployment.yaml.

Command ‘kosi list’

The kosi list command lists all installed KOSI packages:

kosi list

 KOSI version: 2.10.0_preAlpha0
| Deployment       | Package                           | PublicHub | Hub    |
|------------------|-----------------------------------|-----------|--------|
| kosiinstallslima | kosi/lima:0.6.2                   |           | private|
| kosicreatetest   | kosi/kosi-create:0.0.1            |           | public |
| plugininstall    | local/kubeops-basic-plugins:0.4.0 |           | local  |

Command ‘kosi update’

The kosi update command updates an already installed KOSI package:

Note : For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

kosi update --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is updated by a package from the myhub Software Hub from kosi.:

kosi update --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

kosi update --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi update --hub myhub kosi/livedemo:2.7.1

create:0.0.1

-p flag

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

kosi update -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi update --hub <hubname> <package> -f <user.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi update --hub <hubname> <package> --cf <encryptedUser.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

kosi update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi update --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to update the deployment by name.

kosi update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a deployment name is set:

kosi update --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi delete’

The kosi delete command deletes an already installed KOSI package:

Note : For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

kosi delete --hub <hubname> --dname <deploymentname> <package>

Note : The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is deleted by a package from the myhub Software Hub from kosi.:

kosi delete --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

kosi delete --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi delete --hub myhub kosi/livedemo:2.7.1

create:0.0.1
-create:0.0.1

-p flag

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

kosi delete -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi delete --hub <hubname> <package> -f <user.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note : The -f parameter can be specified any number of times to use any number of files.

Note : The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi delete --hub <hubname> <package> -f <encryptedUser.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f encryptedUserfile1.yaml -f encryptedUserfile2.yaml -f encryptedUserfile3.yaml

Note : The --cf parameter can be specified any number of times to use any number of encrypted files.

Note : The --cf parameter can also be combined with the --hub parameter.

Note : The --cf parameter can also be combined with the -f parameter.

Important : If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

kosi delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi delete --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note : If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to delete the deployment by name.

kosi delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a deployment name is set:

kosi delete --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi remove’

The kosi remove command removes a KOSI package from the hub:

Note : Only logged users can delete there OWN packages on their OWN hubs.

kosi remove --hub <hubname> <package>

Note : The package you want to remove can be found in the output of the kosi search command, more precisely in the install column

Example: The package livedemo of the user kosi with version 2.7.1 will be removed from the myhub hub:

kosi remove --hub myhub kosi/livedemo:2.7.1

Note : If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

Command ‘kosi check’

The kosi check command is used to compare a local kosi package with a sha256 Checksum.

kosi check -p <localpackagename> <sha256 hash>

Example:

kosi check -p examplepackage c83f3db9639e175f82e7d07d342533866873e2d9ca2f0fd5ee607ea395417edb

File Formats

package.kosi

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

languageversion = "1.0.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");
}

package.yaml

⚠ Warning : The apiversion has been changed from …/user/v2 to …/user/v3. The Image Key has been split into to separate Keys registry and image.

⚠ Warning : To get your package please enter a fully lowercase 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).

⚠ Warning : Please name your packages without docker tags (:v1.0.0).

# 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"

default.yaml

config.yaml

Note : Default location for: /var/kubeops/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.

apiversion: kubernative/kosi/config/v2           # Shows the supported API-Version
spec:                                            
  hub: https://hub.kubernative.net/dispatcher/     # Address to the KOSI online hub
  plugins: /kubeops/kosi/kosi-plugins/             # Location of the KOSI-Plugins
  registry: registry1.kubernative.net/             # Registry, where Docker-images will be pulled to (kosi pull)
  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 folders will be deleted), false (all temporary created folders won't be deleted)

Usage

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
rm -rf /var/kubeops/kosi
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins
rm -rf /var/kubeops/plugins

Note : If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.kosi

This is an example of how templating in a package.kosi is working with kosi 2.10.x

First we need to create this 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 template plugin."');
    template(tmpl='{{package.includes.files.input}}';target='{{values.target}}');
}

update
{
    cmd(command='"touch ~/kosiExample2"');
    template(tmpl='{{package.includes.files.input}}';target='{{values.target}}');
}

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

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.example}}

Next we create a default.yaml:

example: example
target: target.yaml

Note : Please make sure that you create all these files in the same directory.

Now we are ready to create a kosi package. For this we need the following command:

kosi build

Next we can run the installation section we have defined in the package.yaml with the following command:

kosi install -p package.tgz --dname example

We can check the result in the directory $KUBEOPSROOT/kosi/tmp.

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

Plugins

With the installation of KOSI a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References

6 - Full Documentation KOSI-2.12.x

KubeOps KOSI

How to use KOSI

This guide explains how to use KOSI with detailed instructions and examples.

General commands

Overview of all KOSI commands

kosi:
  Kosi is a SoftwareINstAller for kubernetes cluster

Usage:
  Kosi [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    logs you in
  search                   Shows you all the available packages on the softwarehub
  build                    Creates your final kosi.package
  push                     Push package.tgz to KubeOps Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    install a .tgz file and if it is required, download it
  update <packagename>     update a .tgz file and if it is required, download it
  delete <packagename>     run delete section of a .tgz file and if it is required, download it
  list                     List packages from storage
  lint                     lint your files for your .tgz package
  create                   Creates a package.kosi and a template.yaml for you to manipulate
  version                  Basic infos about KOSI
  logout                   Logout
  remove <package>         Gives you the possibility to remove packages from the hub, if you have write permissions.
  encrypt                  Gives you the possibility to encrypt your values with a password.
  check <hash>             check your local package hash

Command ‘kosi –help’

The command kosi --help gives you an overview of all available commands:

kosi --help

Alternatively, you can also enter kosi or kosi -? in the command line.

Command ‘kosi version’

The kosi version command shows you the current version of KOSI.

kosi version

The output should be:

2025-03-18 08:07:41 Info:      KOSI version: 2.12.0.11
2025-03-18 08:07:41 Info:      Latest KOSI-package-apiversion is: kubernative/kubeops/sina/user/v4
2025-03-18 08:07:41 Info:      Latest KOSI-language-version is: 1.0.0
2025-03-18 08:07:41 Info:      This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
2025-03-18 08:07:41 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Command ‘kosi create’

Note: The command works in the current directory.

The command kosi create creates four files (package.kosi, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

The template.yaml is required if the template engine Scriban is to be used.

The logo.png is a package-thumbnail with the size of 50x50px

The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

kosi create

Created files:

package.kosi
template.yaml
logo.png - For showing logo on the KubeOpsHub.
docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘kosi build’

Note: The command works in the current working directory.

Note: If you have no package.kosi file in your current working directory, KOSI will pick a package.yaml file.

Note: Name your package in the package.kosi in full lower case.

Note: Don´t change the name for logo.png and docs.tgz

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

The kosi build command creates the necessary yaml files for building a package:

kosi build

All files specified in the package.kosi are combined together with the package.yaml to form a KOSI package.

The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

Command ‘kosi lint’

The kosi lint command is used to check whether the contents of the package.yaml or package.kosi files are valid:

kosi lint

The kosi login command logs on to the KubeOps services. The account name is required for this command.

Note: To push packages into the hub, you need to create an account here first. Note: We recommend lowercase usernames for your kubeops-accounts.

After the flag -u type your username. Afterwards you will be asked to enter your password.

kosi login -u <username>

kosi login -u <username> -p <password>

-u flag

The -u parameter is used to specify the user name.

kosi login -u

This parameter is required.

-p flag

The -p parameter is used to specify the password.

kosi login -p

This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘kosi logout’

The kosi logout command logs out from the KubeOps services.

Note: To logout from the KubeOps services, you have to be logged in.

kosi logout

Command ‘kosi push’

The kosi push command uploads KOSI packages to the KubeOps Hub:

kosi push --hub <hubname>

Note: In order to upload KOSI packages, you first have to log in using the kosi login command.

Note: The package name is case-sensitive and should be lowercase.

–hub flag

The --hub parameter is used to upload KOSI packages to a specific hub, e.g. in this example we upload our KOSI package to the myhub hub.

kosi push --hub myhub

Command ‘kosi pull’

The kosi pull command downloads a specific KOSI package from the hub without installing it directly.

kosi pull --hub <hubname> <packagename> -o <desired name>

Note: kosi pull downloads the package to the current directory.

Note: The downloaded packages can be transferred to machines without internet access via USB, for example.

Note: The package name is case-sensitive and should be lowercase.

Example:

kosi pull --hub myhub donald/kosi-print-test:0.0.1 -o printpackage

Note: The -o option specifies a name that the package will have after download. The file automatically gets the .tgz extension. The -o option is not optional.

–hub flag

The --hub parameter is used to download KOSI packages to a specific hub, e.g. in this example we are pulling our KOSI package from the myhub hub.

kosi pull --hub myhub kubeops/harbor:1.1.0

-r flag

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note: kosi pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0   -o harborpackage -r 127.0.0.1:5000

Note: After the kosi pull --hub myhub kubeops/harbor:1.1.0 -o printpackage -r 127.0.0.1:5000 command you can use kosi install -p printpackage.tgz to use the docker image from your local docker registry.

Note: You can now install your packages including docker images without internet connection from your local machine.

-t flag

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry> -t <cluster.internal.registry>

Note: local.docker.registry is the same registry as cluster.internal.registry but with a different hostname.

Example:

kosi pull --hub myhub kubeops/harbor:1.1.0 -o harborpackage -r myregistry:5000 -t clusterregistry:5000

IMPORTANT: -t flag can only be used in combination with the -r flag.

Command ‘kosi search’

The kosi search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the creator of the package.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the description of the package.
The Install column contains a string consisting of the name of the creator, name and version of the package. This string can be copied and used for the kosi install command.

kosi search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

kosi search --hub donald

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |
| donald | livedemo     | 2.7.2   | welcome to kosi                  | donald/livedemo:2.7.1     |

–ps flag

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

kosi search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

kosi search --hub donald --ps private

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |

–hub flag

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the myhub hub.

kosi search --hub myhub

| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| kosi   | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi   | installation | 0.0.1   | kosi create example package.yaml | kosi/installation:0.0.1 |  
| donald | elk-kosi     | 0.0.1   | ELK installation                 | donald/elk-kosi:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |

The parameters --hub and --ps can be combined for a targeted search in the kosi hub:

kosi search --hub <hubname> --ps <package_name>

Example:
The user kosi wants to display all packages in the kosi hub with the term “lima”.

kosi search --hub kosi  --ps lima

| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| kosi | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi | lima         | 0.7.1   | installs LIMA                    | kosi/lima:0.7.1         |

Command ‘kosi encrypt’

The kosi encrypt command is used to encrypt YAML files with AES-256-CBC:

-f flag

The parameter -f must be used to use yaml files from the user.

This parameter is required.

kosi encrypt -f <user.yaml>

Note: The -f parameter can be specified any number of times to use any number of files.

kosi encrypt -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: Once your file is encrypted, you cannot decrypt it with KOSI to obtain a decrypted file. KOSI decrypts the file at runtime when it is used.

Command ‘kosi install’

The kosi install command installs a KOSI package:

kosi install --hub <hubname> <package>

The string of the column Install in the output of kosi search is required:

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

–hub flag

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

kosi install --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub Software Hub:

kosi install --hub myhub kosi/livedemo:2.7.1

-p flag

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

kosi install -p package.tgz

-f flag

The parameter f must be used to use .yaml files from the user.

kosi install <package> -f <user.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi install <package> --cf <encryptedUser.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and user specific encrypted files are to be used for the installation:

kosi install --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files.
Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi install --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

kosi install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a custom kubernetes namespace is used:

kosi install --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the namespace default will be used.

–dname flag

The parameter dname can be used to save the package under a specific name.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the myhub software hub and a deployment name is set:

kosi install --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Note: If no --dname parameter is specified, a random deployment name will be generated. Note: Deploymentnames are unique, the installation will stop if the deploymentname already exists.
Note: The deployment name is stored in the file /<user>/var/kubeops/kosi/deployment.yaml.

Command ‘kosi list’

The kosi list command lists all installed KOSI packages:

kosi list

 KOSI version: 2.10.0_preAlpha0
| Deployment       | Package                           | PublicHub | Hub    |
|------------------|-----------------------------------|-----------|--------|
| kosiinstallslima | kosi/lima:0.6.2                   |           | private|
| kosicreatetest   | kosi/kosi-create:0.0.1            |           | public |
| plugininstall    | local/kubeops-basic-plugins:0.4.0 |           | local  |

Command ‘kosi update’

The kosi update command updates an already installed KOSI package:

For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

kosi update --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is updated by a package from the myhub Software Hub from kosi.:

kosi update --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

kosi update --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi update --hub myhub kosi/livedemo:2.7.1

create:0.0.1

-p flag

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

kosi update -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi update --hub <hubname> <package> -f <user.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi update --hub <hubname> <package> --cf <encryptedUser.yaml>

kosi update --hub myhub kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files. Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi update --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

kosi update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi update --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to update the deployment by name.

kosi update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the myhub software hub and a deployment name is set:

kosi update --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi delete’

The kosi delete command deletes an already installed KOSI package:

For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

kosi delete --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is deleted by a package from the myhub Software Hub from kosi.:

kosi delete --hub myhub --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

kosi delete --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the myhub Software Hub:

kosi delete --hub myhub kosi/livedemo:2.7.1

create:0.0.1
-create:0.0.1

-p flag

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

kosi delete -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi delete --hub <hubname> <package> -f <user.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi delete --hub <hubname> <package> -f <encryptedUser.yaml>

kosi delete --hub myhub kosi/livedemo:2.7.1 -f encryptedUserfile1.yaml -f encryptedUserfile2.yaml -f encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files. Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi delete --hub myhub kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

kosi delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a custom kubernetes namespace is used:

kosi delete --hub myhub kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to delete the deployment by name.

kosi delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the myhub software hub and a deployment name is set:

kosi delete --hub myhub kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi remove’

The kosi remove command removes a KOSI package from the hub:

Note: Only logged users can delete there OWN packages on their OWN hubs.

kosi remove --hub <hubname> <package>

Note: the package you want to remove can be found in the output of the kosi search command, more precisely in the install column

Example: The package livedemo of the user kosi with version 2.7.1 will be removed from the myhub hub:

kosi remove --hub myhub kosi/livedemo:2.7.1

Note: If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

Command ‘kosi check’

The kosi check command is used to compare a local kosi package with a sha256 Checksum.

kosi check -p <localpackagename> <sha256 hash>

Example:

kosi check -p examplepackage c83f3db9639e175f82e7d07d342533866873e2d9ca2f0fd5ee607ea395417edb

File Formats

package.kosi

IMPORTANT: To get your package please enter a fully lowercase 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).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

languageversion = "1.0.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");
}

package.yaml

IMPORTANT: The apiversion has been changed from …/user/v2 to …/user/v3. The Image Key has been split into to separate Keys registry and image.

IMPORTANT: To get your package please enter a fully lowercase 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).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

# 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"

default.yaml

config.yaml

Location for: /var/kubeops/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.

apiversion: kubernative/kosi/config/v2           # Shows the supported API-Version
spec:                                            
  hub: https://hub.kubernative.net/dispatcher/     # Address to the KOSI online hub
  plugins: /kubeops/kosi/kosi-plugins/             # Location of the KOSI-Plugins
  registry: registry1.kubernative.net/             # Registry, where Docker-images will be pulled to (kosi pull)
  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 folders will be deleted), false (all temporary created folders won't be deleted)

KOSI uses Workspaces for processing the packages. These workspaces can be deleted if you using CLI-commands and setting the housekeeping to true. Plugins also will operate in this workspace.

Usage

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
rm -rf /var/kubeops/kosi
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins
rm -rf /var/kubeops/plugins

If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.kosi

This is an example of how templating in a package.kosi is working with kosi 2.10.x

First we need to create this 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 template plugin."');
    template(tmpl='{{package.includes.files.input}}';target='{{values.target}}');
}

update
{
    cmd(command='"touch ~/kosiExample2"');
    template(tmpl='{{package.includes.files.input}}';target='{{values.target}}');
}

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

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.example}}

Next we create a default.yaml:

example: example
target: target.yaml

Please make sure that you create all these files in the same directory.

Now we are ready to create a kosi package. For this we need the following command:

kosi build

Next we can run the installation section we have defined in the package.yaml with the following command:

kosi install -p package.tgz --dname example

We can check the result in the directory $KUBEOPSROOT/kosi/tmp.

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

Plugins

With the installation of KOSI a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References

7 - Full Documentation KOSI-2.11.x

KubeOps KOSI

How to use KOSI

This guide explains how to use KOSI with detailed instructions and examples.

General commands

Overview of all KOSI commands

kosi:
  Kosi is a SoftwareINstAller for kubernetes cluster

Usage:
  Kosi [options] [command]

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Commands:
  login                    logs you in
  search                   Shows you all the available packages on the softwarehub
  build                    Creates your final kosi.package
  push                     Push package.tgz to KubeOps Hub.
  pull <package>           Downloads an existing package from the hub without installing.
  install <packagename>    install a .tgz file and if it is required, download it
  update <packagename>     update a .tgz file and if it is required, download it
  delete <packagename>     run delete section of a .tgz file and if it is required, download it
  list                     List packages from storage
  lint                     lint your files for your .tgz package
  create                   Creates a package.kosi and a template.yaml for you to manipulate
  version                  Basic infos about KOSI
  logout                   Logout
  remove <package>         Gives you the possibility to remove packages from the hub, if you have write permissions.
  encrypt                  Gives you the possibility to encrypt your values with a password.
  check <hash>             check your local package hash

Command ‘kosi –help’

The command kosi --help gives you an overview of all available commands:

kosi --help

Alternatively, you can also enter kosi or kosi -? in the command line.

Command ‘kosi version’

The kosi version command shows you the current version of KOSI.

kosi version

The output should be:

[ 12/03/2021 10:13:20 Debug1  default ] Check OS Support...
[ 12/03/2021 10:13:20 Debug1  default ] set Loglevel info
Version: 2.11.3.0
This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
©KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2022

Command ‘kosi create’

Note: The command works in the current directory.

The command kosi create creates four files (package.kosi, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited by the user.

The template.yaml is required if the template engine Scriban is to be used.

The logo.png is a package-thumbnail with the size of 50x50px

The docs.tgz is a zipped directory with the documentation of the package. The documentation of the package is written down in markdown. The file for the documentation is called readme.md.

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

kosi create

Created files:

package.kosi
template.yaml
logo.png - For showing logo on the KubeOpsHub.
docs.tgz - For showing documentation on the KubeOpsHub.

Command ‘kosi build’

Note: The command works in the current working directory.

Note: If you have no package.kosi file in your current working directory, KOSI will pick a package.yaml file.

Note: Name your package in the package.kosi in full lower case.

Note: Don´t change the name for logo.png and docs.tgz

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

The kosi build command creates the necessary yaml files for building a package:

kosi build

All files specified in the package.kosi are combined together with the package.yaml to form a KOSI package.

The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

Command ‘kosi lint’

The kosi lint command is used to check whether the contents of the package.yaml or package.kosi files are valid:

kosi lint

The kosi login command logs on to the KubeOps services. The account name is required for this command.

Note: To push packages into the hub, you need to create an account here first. Note: We recommend lowercase usernames for your kubeops-accounts.

After the flag -u type your username. Afterwards you will be asked to enter your password.

kosi login -u <username>

kosi login -u <username> -p <password>

-u flag

The -u parameter is used to specify the user name.

kosi login -u

This parameter is required.

-p flag

The -p parameter is used to specify the password.

kosi login -p

This parameter is not required. We recommend to use this parameter only if it is absolutely necessary.

Command ‘kosi logout’

The kosi logout command logs out from the KubeOps services.

Note: To logout from the KubeOps services, you have to be logged in.

kosi logout

Command ‘kosi push’

The kosi push command uploads KOSI packages to the KubeOps Hub:

kosi push --hub <hubname>

Note: In order to upload KOSI packages, you first have to log in using the kosi login command.

Note: The package name is case-sensitive and should be lowercase.

–hub flag

The --hub parameter is used to upload KOSI packages to a specific hub, e.g. in this example we upload our KOSI package to the public hub.

kosi push --hub public

Command ‘kosi pull’

The kosi pull command downloads a specific KOSI package from the hub without installing it directly.

kosi pull --hub <hubname> <packagename> -o <desired name>

Note: kosi pull downloads the package to the current directory.

Note: The downloaded packages can be transferred to machines without internet access via USB, for example.

Note: The package name is case-sensitive and should be lowercase.

Example:

kosi pull --hub public donald/kosi-print-test:0.0.1 -o printpackage

Note: The -o option specifies a name that the package will have after download. The file automatically gets the .tgz extension. The -o option is not optional.

–hub flag

The --hub parameter is used to download KOSI packages to a specific hub, e.g. in this example we are pulling our KOSI package from the public hub.

kosi pull --hub public kubeops/harbor:1.1.0

-r flag

The parameter r can be used to pull the docker images which are included in the package to a given local docker registry.

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry>

Note: kosi pull downloads the package and pulls the required docker images to the given local docker registry.

Example:

kosi pull --hub public kubeops/harbor:1.1.0   -o harborpackage -r 127.0.0.1:5000

Note: After the kosi pull kubeops/harbor:1.1.0 -o printpackage -r 127.0.0.1:5000 command you can use kosi install -p printpackage.tgz to use the docker image from your local docker registry.

Note: You can now install your packages including docker images without internet connection from your local machine.

-t flag

kosi pull --hub <hubname> <packagename> -o <desired name> -r <local.docker.registry> -t <cluster.internal.registry>

Note: local.docker.registry is the same registry as cluster.internal.registry but with a different hostname.

Example:

kosi pull --hub public kubeops/harbor:1.1.0 -o harborpackage -r myregistry:5000 -t clusterregistry:5000

IMPORTANT: -t flag can only be used in combination with the -r flag.

Command ‘kosi search’

The kosi search command displays all available packages of your own private hub. Only the logged in user can see the packages on his private hub. The User column contains the name of the creator of the package.
The Name column contains the name of the package.
The Version column contains the version of the package.
The Description column contains the description of the package.
The Install column contains a string consisting of the name of the creator, name and version of the package. This string can be copied and used for the kosi install command.

kosi search --hub <hubname>

Example: User donald is logged in and wants to get the packets from his private hub:

kosi search --hub donald

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |
| donald | livedemo     | 2.7.2   | welcome to kosi                  | donald/livedemo:2.7.1     |

–ps flag

The --ps parameter can be used to filter for keywords that refer to all five columns. It is also possible to filter by individual word components:

kosi search --hub <hubname> --ps <name>

Example:
In this case, all packets containing the word private are displayed:

kosi search --hub donald --ps private

| User   | Name         | Version | Description                      |Install                    |
|--------|--------------|---------|----------------------------------|---------------------------|                  
| donald | private-kosi | 0.0.1   | private installation             | donald/private-kosi:0.0.1 |                                       
| donald | private-test | 0.0.1   | private package                  | donald/private-test:0.0.1 |

–hub flag

In addition, there is an option to search for packages on a specific hub using the --hub parameter. You need no login to search in the public hub.

kosi search --hub public

| User   | Name         | Version | Description                      |Install                  |
|--------|--------------|---------|----------------------------------|-------------------------|
| kosi   | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi   | installation | 0.0.1   | kosi create example package.yaml | kosi/installation:0.0.1 |  
| donald | elk-kosi     | 0.0.1   | ELK installation                 | donald/elk-kosi:0.0.1   |
| donald | prod-test    | 0.0.1   | test for prod                    | donald/prod-test:0.0.1  | 
| lima   | lima         | 0.6.0   | installs LIMA                    | lima/lima:0.6.0         |

The parameters --hub and --ps can be combined for a targeted search in the kosi hub:

kosi search --hub <hubname> --ps <package_name>

Example:
The user kosi wants to display all packages in the kosi hub with the term “lima”.

kosi search --hub kosi  --ps lima

| User | Name         | Version | Description                      |Install                  |
|------|--------------|---------|----------------------------------|-------------------------|
| kosi | lima         | 0.6.2   | installs LIMA                    | kosi/lima:0.6.2         |
| kosi | lima         | 0.7.1   | installs LIMA                    | kosi/lima:0.7.1         |

Command ‘kosi encrypt’

The kosi encrypt command is used to encrypt YAML files with AES-256-CBC:

-f flag

The parameter -f must be used to use yaml files from the user.

This parameter is required.

kosi encrypt -f <user.yaml>

Note: The -f parameter can be specified any number of times to use any number of files.

kosi encrypt -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Command ‘kosi install’

The kosi install command installs a KOSI package:

kosi install --hub <hubname> <package>

The string of the column Install in the output of kosi search is required:

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public Hub:

kosi install --hub public kosi/livedemo:2.7.1

–hub flag

The --hub parameter must be used to install packages from the software hub. Only the logged in user can install the packages from the software hub.

kosi install --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public Software Hub:

kosi install --hub public kosi/livedemo:2.7.1

-p flag

The “p” parameter must be used to install local packages. For “p” parameter you need no --hub:

kosi install -p package.tgz

-f flag

The parameter f must be used to use .yaml files from the user.

kosi install <package> -f <user.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public software hub and user specific files are to be used for the installation:

kosi install --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi install <package> --cf <encryptedUser.yaml>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public software hub and user specific encrypted files are to be used for the installation:

kosi install --hub public kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files.
Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi install --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a Kubernetes namespace in which the installation is to be performed.

kosi install --hub <hubname> <package> --namespace <namespace>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public software hub and a custom kubernetes namespace is used:

kosi install --hub public kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the namespace default will be used.

–dname flag

The parameter dname can be used to save the package under a specific name.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example: The package livedemo of the user kosi with version 2.7.1 is to be installed from the public software hub and a deployment name is set:

kosi install --hub public kosi/livedemo:2.7.1 --dname MyDeployment

Note: If no --dname parameter is specified, a random deployment name will be generated. Note: Deploymentnames are unique, the installation will stop if the deploymentname already exists.
Note: The deployment name is stored in the file /<user>/var/kubeops/kosi/deployment.yaml.

Command ‘kosi list’

The kosi list command lists all installed KOSI packages:

kosi list

 KOSI version: 2.10.0_preAlpha0
| Deployment       | Package                           | PublicHub | Hub    |
|------------------|-----------------------------------|-----------|--------|
| kosiinstallslima | kosi/lima:0.6.2                   |           | private|
| kosicreatetest   | kosi/kosi-create:0.0.1            |           | public |
| plugininstall    | local/kubeops-basic-plugins:0.4.0 |           | local  |

Command ‘kosi update’

The kosi update command updates an already installed KOSI package:

For update, the installation and the update package have to be the same name. Update will be defined in the package.yaml.

kosi update --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is updated by a package from the private Software Hub from kosi.:

kosi update --hub public --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to update packages from the software hub. Only the logged in user can update the packages from the software hub.

kosi update --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the public Software Hub:

kosi update --hub myhub kosi/livedemo:2.7.1

create:0.0.1

-p flag

The “p” parameter must be used to update the installation from a local package. For “p” parameter you need no --hub parameter:

kosi update -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi update --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the public software hub and user specific files are to be used for the update progress:

kosi update --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameters.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi update --hub <hubname> <package> --cf <encryptedUser.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the public software hub and user specific encrypted files are to be used for the update progress:

kosi update --hub public kosi/livedemo:2.7.1 --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml --cf encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files. Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi update --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which the update is to be performed.

kosi update --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the public software hub and a custom kubernetes namespace is used:

kosi update --hub public kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to update the deployment by name.

kosi update --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is updated by a package from the public software hub and a deployment name is set:

kosi update --hub public kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi delete’

The kosi delete command deletes an already installed KOSI package:

For delete, the installation and the update package have to be the same name. Delete will be defined in the package.yaml.

kosi delete --hub <hubname> --dname <deploymentname> <package>

The string of the column Install in the output of kosi search is required:

Example: The installation of the package lima from the user kosi with version 0.6.2 and deployment name kosiInstallsLima is deleted by a package from the public Software Hub from kosi.:

kosi delete --hub public --dname kosiInstallsLima kosi/kosi/lima:0.6.2

–hub flag

The --hub parameter must be used to use the delete section of packages from the software hub. Only the logged in user can use the delete section of packages from the software hub.

kosi delete --hub <hubname> <package>

Example: The package livedemo of the user kosi with version 2.7.1 is to be updated from the public Software Hub:

kosi delete --hub myhub kosi/livedemo:2.7.1

create:0.0.1
-create:0.0.1

-p flag

The “p” parameter must be used to delete the installation from a local package. For “p” parameter you need no --hub parameter:

kosi delete -p package.tgz

-f flag

The parameter f must be used to use yaml files from the user.

kosi delete --hub <hubname> <package> -f <user.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the public software hub and user specific files are to be used for the delete progress:

kosi delete --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml -f userfile3.yaml

Note: The -f parameter can be specified any number of times to use any number of files. Note: The -f parameter can also be combined with the --hub parameter.

–cf flag

The parameter --cf must be used to use encrypted yaml files from the user.

kosi delete --hub <hubname> <package> -f <encryptedUser.yaml>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the public software hub and user specific encrypted files are to be used for the delete progress:

kosi delete --hub public kosi/livedemo:2.7.1 -f encryptedUserfile1.yaml -f encryptedUserfile2.yaml -f encryptedUserfile3.yaml

Note: The --cf parameter can be specified any number of times to use any number of encrypted files. Note: The --cf parameter can also be combined with the --hub parameter.
Note: The --cf parameter can also be combined with the -f parameter.

IMPORTANT: If you combine -f with --cf, you must specify the -f parameter first before specifying --cf!

Example:

kosi delete --hub public kosi/livedemo:2.7.1 -f userfile1.yaml -f userfile2.yaml --cf encryptedUserfile1.yaml --cf encryptedUserfile2.yaml

–namespace flag

The namespace parameter can be used to specify a kubernetes namespace in which to perform the deletion.

kosi delete --hub <hubname> <package> --namespace <namespace>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the public software hub and a custom kubernetes namespace is used:

kosi delete --hub public kosi/livedemo:2.7.1 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

–dname flag

The parameter dname can be used to delete the deployment by name.

kosi delete --hub <hubname> <package> --dname <deploymentname>

Example: The installation of the package livedemo of the user kosi with version 2.7.1 is deleted by a package from the public software hub and a deployment name is set:

kosi delete --hub public kosi/livedemo:2.7.1 --dname MyDeployment

Command ‘kosi remove’

The kosi remove command removes a KOSI package from the hub:

Note: Only logged users can delete there own packages on their own hubs.

kosi remove --hub <hubname> <package>

Note: the package you want to remove can be found in the output of the kosi search command, more precisely in the install column

Example: The package livedemo of the user kosi with version 2.7.1 will be removed from the public hub:

kosi remove --hub public kosi/livedemo:2.7.1

Note: If your package already deleted, the command will try do delete your package successfully. Deleting non-existing packages does not cause any errors.

Command ‘kosi check’

The kosi check command is used to compare a local kosi package with a sha256 Checksum.

kosi check -p <localpackagename> <sha256 hash>

Example:

kosi check -p examplepackage c83f3db9639e175f82e7d07d342533866873e2d9ca2f0fd5ee607ea395417edb

File Formats

package.kosi

IMPORTANT: To get your package please enter a fully lowercase 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).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

languageversion = "1.0.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");
}

package.yaml

IMPORTANT: The apiversion has been changed from …/user/v2 to …/user/v3. The Image Key has been split into to separate Keys registry and image.

IMPORTANT: To get your package please enter a fully lowercase 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).

IMPORTANT: Please name your packages without docker tags (:v1.0.0).

# 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"

default.yaml

config.yaml

Location for: /var/kubeops/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.

apiversion: kubernative/kosi/config/v2           # Shows the supported API-Version
spec:                                            
  hub: https://hub.kubernative.net/dispatcher/     # Address to the KOSI online hub
  plugins: /kubeops/kosi/kosi-plugins/             # Location of the KOSI-Plugins
  registry: registry1.kubernative.net/             # Registry, where Docker-images will be pulled to (kosi pull)
  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 folders will be deleted), false (all temporary created folders won't be deleted)

Usage

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins and the config.yaml. To use the variable, the config.yaml and the plugins have to be copied manually.
So for example:

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
rm -rf /var/kubeops/kosi
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins
rm -rf /var/kubeops/plugins

If you want to use the config file and plugins with a user you have to go through these steps.

How to use templating within the package.kosi

This is an example of how templating in a package.kosi is working with kosi 2.10.x

First we need to create this 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 template plugin."');

    template
    (
        tmpl = '{{package.includes.files.input}}';
        target = '{{values.target}}';
    );
}

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

    template
    (
        tmpl = '{{package.includes.files.input}}';
        target = '{{values.target}}';
    );
}

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

Now we create a template.yaml:

package:
  file: {{package.includes.files.input}}
  uservalues: {{values.example}}

Next we create a default.yaml:

example: example
target: target.yaml

Please make sure that you create all these files in the same directory.

Now we are ready to create a kosi package. For this we need the following command:

kosi build

Next we can run the installation section we have defined in the package.yaml with the following command:

kosi install -p package.tgz --dname example

We can check the result in the directory $KUBEOPSROOT/kosi/tmp.

the content of target.yaml is:

package:
  file: template.yaml
  uservalues: example

Plugins

With the installation of KOSI a handful of plugins are included. Which plugins are included can be seen under “pre-installed plugins” in the Plugin References

8 - Software Bill of Materials (SBOM)

KubeOps publishes a Software Software Bill of Materials (SBOM) for the kosi command-line tooling that ships in the package repositories. It lists every bundled component with its exact version and license, in CycloneDX format. The published document is the authoritative source — link to it rather than copying its contents, so the list never drifts out of date.

Download

The SBOM is served at a fixed path in each package repository. Both repositories ship the same SBOM document, so the only difference is the retrieval URL for your platform.

curl -fsSLO https://packagerepo.kubeops.net/rpm/sbom/kosi-2.15.0.4_Beta0-0.x86_64.xml

You can checkout all SBOMs here sbom

curl -fsSLO https://packagerepo.kubeops.net/deb/pool/main/sbom/kosi-2.15.0.4_Beta0-0.x86_64.xml

You can checkout all SBOMs here sbom

Using the SBOM

The CycloneDX document can be fed directly into SBOM-aware vulnerability scanners and license-compliance tooling without re-resolving dependencies, for example:

grype sbom:./kosi-bom.xml   # vulnerability scan
trivy sbom ./kosi-bom.xml   # vulnerability scan

Scanner output reflects advisories at the time you run the scan, not at the time the SBOM was generated. Re-run scans regularly rather than relying on a single point-in-time result.

Reference

1 - Fileformats in KOSI

KOSI config.yaml

Example:

Note

KOSI values.yaml

Example:

values.yaml

package.kosi

KOSI template.yaml

Example:

KOSI package.kosi

KOSI package.yaml

Example:

KOSI package.tgz

2 - KOSI Language Reference

package.kosi File

Metadata

files

containers

install

3 - Full Documentation KOSI-2.15.x

KubeOps KOSI

How to use KOSI

General commands

Overview of all KOSI commands

Command ‘kosi –help’

Command ‘kosi version’

Command ‘kosi create’

Command ‘kosi build’

-o flag

-r flag

Command ‘kosi lint’

Command ‘kosi login’

-u flag

-p flag

Command ‘kosi logout’

Command ‘kosi push’

–hub flag

Command ‘kosi pull’

–hub flag

-r flag

-t flag

Command ‘kosi search’

–ps flag

–hub flag

Command ‘kosi encrypt’

-f flag

Command ‘kosi install’

–hub flag

-p flag

-f flag

–cf flag

–namespace flag

–dname flag

Command ‘kosi list’

Command ‘kosi update’

–hub flag

-p flag

-f flag

–cf flag

–namespace flag

–dname flag

Command ‘kosi delete’

–hub flag

-p flag

-f flag

–cf flag

–namespace flag

–dname flag

Command ‘kosi remove’

Command ‘kosi check’

Command ‘kosi manage add user’

–username [-u]

–action [-a]

–hub

–duration [-d]

Command ‘kosi manage add group’

–groupname [-g]

–action [-a]