KubeOpsDoku – KOSI

Kosi: auditLog-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

Kosi Plugin auditLog Version 2.2.0

Summary

The auditLog plugin enables or disables audit logging for your Kubernetes cluster. This plugin allows you to control logging settings and define paths for policy and log storage.

Keys

Key		Description
state	Mandatory	Set to on to enable or off to disable audit logging for the cluster.
policyPath	Mandatory	Specifies the directory where the policy.yaml file is stored.
logPath	Mandatory	Defines the directory where the audit.log file will be saved.

Example 1 - enable auditLog

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

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

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

install
{
    auditLog
    (
        state = "on"; 
        policyPath = "/root/test/policyDir/";
        logPath = "/root/test/logging/";
    );
}

Example 2 - disable auditLog

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

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

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

install
{
    auditLog
    (
        state = "off"; 
        policyPath = "/root/test/policyDir/";
        logPath = "/root/test/logging/";
    );
}

Kosi: KOSI Versions

Mon, 01 Jan 0001 00:00:00 +0000

KOSI versions and deprecation dates

Here are the current supported KOSI Versions. The list contains: The KOSI version, Supported KOSI language version, Supported KOSI plugins and the Deprecation date of all KOSI versions. X of the versions must be X of the plugins

KOSI	Supported KOSI language	Supported KOSI plugins	Deprecation date
KOSI 2.15.X	v1.0.0	Plugins 2.2.X	01.07.2027
KOSI 2.14.X	v1.0.0	Plugins 2.0.X	[not supported]
KOSI 2.13.X	v1.0.0	Plugins 2.0.X	13.04.2027
KOSI 2.12.X	v1.0.0	Plugins 1.7.X	01.10.2026
~~KOSI 2.11.X~~	~~v1.0.0~~	~~Plugins 1.6.X~~	~~01.11.2025~~
~~KOSI 2.10.X~~	~~v0.1.0~~	~~Plugins 1.5.X~~	~~12.03.2025~~

Kosi: bash-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin bash Version 2.2.0

Summary

The bash plugin allows users to execute shell commands within a Bash environment. It is useful for running system commands, scripting automation tasks, or performing custom operations that require command-line execution within a KOSI package. This plugin ensures that commands are executed inside a Bash shell, which provides compatibility with shell scripting syntax and built-in commands. Supports command chaining using ;.

Keys

Key		Description
command	Mandatory	Contains a string representing a bash command or a sequence of commands to be executed. Multiple commands can be specified, separated by a semicolon (`;`).

Examples

Example 1

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

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

install
{
    cmd(command = "echo Using the bash plugin.");

    bash(command = "echo Hello World!");
}

Output

2025-02-26 15:17:00 Info:      use plugin bash if available
2025-02-26 15:17:00 Info:      Executing with non sudo privilegs
2025-02-26 15:17:00 Info:      Using the bash plugin.

2025-02-26 15:17:00 Info:      Executing with non sudo privilegs
2025-02-26 15:17:00 Info:      Hello World!

2025-02-26 15:17:00 Info:      Installation successful.

Example 2

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

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

install
{
    cmd(command = "echo Using the bash plugin.");

    bash(command = "echo 1.Hello;echo 2.World;echo 3.Hello World.");
}

Output

2025-02-26 15:18:28 Info:      run cmd plugin
2025-02-26 15:18:28 Info:      use plugin bash if available
2025-02-26 15:18:28 Info:      Executing with non sudo privilegs
2025-02-26 15:18:28 Info:      Using the bash plugin.

2025-02-26 15:18:28 Info:      Executing with non sudo privilegs
2025-02-26 15:18:28 Info:      1.Hello
2.World
3.Hello World.

2025-02-26 15:18:28 Info:      Installation successful.

Example 3

Using bash with the set and if plugins

This example shows the interaction of several plug-ins. In this example, we use the bash plugin together with the set and if plugins to check a condition (which is set before) before executing a bash command:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-bash-if";
description = "Example using bash with set and if";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

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

install
{
    set
    (
        variable = "myVar";
        value = "Hello";
    );

    if (condition = "$vars.myVar$ = 'Hello'") then
    {
        bash(command = "echo Variable is 'Hello'");
    }
    else
    {
        bash(command = "echo Variable is not 'Hello'");
    }
}

Expected Output

If myVar is Hello:

2025-02-26 15:18:28 Info:      Variable is 'Hello'

If myVar is not Hello:

2025-02-26 15:18:28 Info:      Variable is not 'Hello'

Kosi: chmod-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin chmod Version 2.2.0

Summary

The chmod plugin allows you to modify access permissions for a specified file or directory. By defining a path, state, and mode, you can change file permissions using the Linux chmod command.

The state value can be either file or directory. If directory is specified, the plugin applies permissions recursively.
The mode value represents the permission settings in the standard numerical format used in Linux.
If necessary, you can run chmod with sudo, requiring a password set by the root user.

Keys

Key		Description
path	Mandatory	Absolute path of the file or directory whose permissions you want to change.
state	Mandatory	Set to file or directory depending on whether the path is a file or directory.
mode	Mandatory	Permission mode using the Linux numeric syntax (supports three-digit and four-digit octal representation).
sudo	optional	Set to true to use sudo for the chmod command.
sudoPassword	optional	Password for executing sudo commands. A root user must assign this password to a non-root user beforehand.

Note: If you’re not yet familiar with Linux permissions, check out this short introduction from RedHat.

Example 1 - Changing file permissions

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

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

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

install
{
    cmd(command = "echo Changing file permissions using the chmod-plugin");
    chmod
    (
        path = "/user/myuser/myUserApp.sh";
        state = "file";
        mode = "777"
    );
}

Example 2 - Changing directory permissions with sudo

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

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

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

install 
{
    cmd(command = "echo Changing directory permissions using the chmod-plugin");
    chmod
    (
        path = "/root"; 
        state = "directory"; 
        mode = "777"; 
        sudo = "true"; 
        sudoPassword = "myPassword";
    );
    bash(command = "ls -la /root");
}

Example 3 - Restricting permissions to read-only

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

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

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

install 
{
    cmd(command = "echo Restricting file permissions using chmod-plugin");
    chmod
    (
        path = "/user/myuser/myUserApp.sh"; 
        state = "file"; 
        mode = "444";
    );
}

Kosi: cmd-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin cmd Version 2.2.0

Summary

The cmd plugin allows execution of Linux shell commands within a deployment configuration. It relies on either the bash or sh plugin to process commands, depending on availability. If the bash plugin is present, it will be used; otherwise, the sh plugin will handle execution.

Plugin dependencies

If you want to use the plugin cmd you need one of following plugins:

Why is the bash or sh Plugin Required?

The cmd plugin itself does not execute commands directly. Instead, it acts as a wrapper, passing the specified command to a shell environment. Since bash and sh are the most common shell interpreters in Linux, the plugin requires at least one of them to function properly.

Note: Each cmd call is executed in its own shell instance. Changes to the shell environment (e.g., cd, export, etc.) do not persist across multiple cmd calls. If multiple commands depend on a shared shell context, they should be combined into a single cmd call.
For example: cmd(command="cd /root/test-cmd-Plugin && pwd && ls -lah")

Keys

Key		Description
command	Mandatory	set this to a command for the bash or the sh terminal .

Note: The command has to be surrounded by double quotes, otherwise it will not be recognized.

Usage

Example 1 - Executing a single commands

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

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

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

install
{
    cmd(command = "echo Using the cmd-plugin");
    cmd(command = "echo Hello World");
}

Expected Output

This will be printed to the console:

2023-12-01 10:44:30 Info:      use plugin bash if available
Using the cmd-plugin
Hello World

Example 2 - Multiple commands

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

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

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

install
{
    cmd(command = "echo Using the cmd-plugin");
    cmd(command = "echo Hello World! '>' test.txt");
    cmd(command = "cat test.txt");
}

Expected Output

A file named test.txt is created and “Hello World!” is written to the file.
The second command outputs the contents of the file.

2023-12-01 11:06:17 Info:      run cmd plugin
Using the cmd-plugin
2023-12-01 11:06:17 Info:      run cmd plugin
Hello World!

Example 3 - Creating and listing a directory

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

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

containers =
{
    example = ["docker.io", "nginx", "latest"];
}
install
{
    cmd(command = "mkdir -p /tmp/mydirectory");
    cmd(command = "ls -la /tmp/mydirectory");
}

Kosi: containerd-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin containerd Version 2.2.0

Summary

The containerd plugin allows you to manage your container runtime efficiently. It provides options to execute commands with or without flags and enables gathering information about the current container runtime status.

Keys

Key		Description
command	Mandatory	The command you want to execute inside the container.
containerName	-	The name of the container or the temporary name of a created cluster.*1
destImage	-	The new image name for tagging srcImage.
execID	-	The ID or name of your execution.*2
flag	-	Stores information on enabled options. Examples include -a or –all for listing all containers, or -n or –last for the last container in the list. Multiple flags can be appended.
sudo	-	Can be true or false. If true, the plugin executes with sudo privileges.
sudoPassword	-	The password for executing the command with sudo privileges.
srcImage	-	The image you want to pull, push, or tag.
option	Mandatory	Specifies the operation to execute (e.g., run, ps, images, exec).

Available Operations:

ps - Lists all existing containers.
images - Lists all existing images.
run - Starts a container.
status - Displays the state of the container runtime (e.g., active).
exec - Executes a command inside a running container.
tag - Renames an image (e.g., docker tag ).
pull - Pulls a specified image.
push - Pushes a specified image.
stop - Stops a given container.
start - Starts a given container.
deleteCon - Deletes a specified container.

*1:Note: For containerd, containers do not have names, only IDs. When using startTask, stopTask, or deleteTask, containerName is treated as the task name.

*2:Note: Only required for execution commands with containerd.

Example 1 - List Running Containers (ps)

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

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

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

install
{
    containerd
    (
        option = "ps"; 
        flag = "--last";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 2 - List All Images

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

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

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

install
{
    containerd
    (
        option = "images"; 
        flag = "--all";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 3 - Run a Container

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

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

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

install
{
    containerd
    (
        option = "run"; 
        flag = "-w /path/to/dir/ -i -t";
        srcImage = "registry.kubernative.net/lima:v0.8.0";
        containerName = "myFirstContainer";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 4 - Check Container Runtime Status

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

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

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

install
{
    containerd
    (
        option = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 5 - Execute a Command in a Running Container

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

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

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

install
{
    containerd
    (
        option = "exec"; 
        execID = "exec1";
        containerName = "registry.kubernative.net/lima:v0.8.0";
        command = "mkdir /tmp/testdir";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 6 - Tag an Image

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

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

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

install
{
    containerd
    (
        option = "tag"; 
        srcImage = "registry.kubernative.net/lima:v0.8.0";
        destImage = "yourRegistry/yourName:v0.8.0";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 7 - Pull or Push an Image

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

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

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

install
{
    containerd
    (
        option = "pull/push"; 
        srcImage = "registry.kubernative.net/lima:v0.8.0";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 8 - Delete a Container

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

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

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

install
{
    containerd
    (
        option = "deleteCon"; 
        containerName = "myFirstContainer";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 9 List Running Tasks (psTask)

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

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

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

install
{
    containerd
    (
        type = "containerd"; 
        option = "psTask";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 10 Manage Tasks (stopTask / startTask / deleteTask)

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

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

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

install
{
    containerd
    (
        option = "stopTask / startTask / deleteTask"; 
        containerName = "task1";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Notes

Ensure that all required parameters are provided for each operation.
Using sudo=true requires sudoPassword to be set.
The containerName for containerd may refer to a container ID or task name, depending on the operation.

Kosi: containerRuntime-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin containerRuntime Version 2.2.0

Summary

The ContainerRuntime plugin allows you to manage container runtimes efficiently. It provides options to execute commands with or without flags and retrieve runtime status information. Supported runtimes include Docker, CRI-O, and containerd.

Plugin requirements

To use the ContainerRuntime plugin, you need the following dependencies installed:

Docker
CRI-O
Contianerd

Keys

Key		Description
command	Mandatory	Specifies the command to execute inside the container.
containerConfig	-	Configuration file (JSON or YAML) for container creation. Example: containerConfiguration.json or containerConfiguration.yaml.
containerName	-	Name of the container in which the command will be executed.
destImage	-	New image name when tagging an existing image.
execID	-	ID or name of the execution (only for containerd execution commands).
flag	-	Options to enable specific command behaviors (e.g., -a or –all). Multiple flags can be used.
runtime	-	Temporarily stores the runtime type when the key containerRuntime is set to status.
srcImage	-	Source image for pull, push, or tag operations.
sudo	-	If true, the plugin executes with sudo privileges.
sudoPassword	-	Mandatory if sudo is set to true.
type	-	Specifies the container runtime type. If unspecified, the plugin detects the running runtime automatically. Docker is preferred if multiple runtimes are active.
option	Mandatory	Specifies the operation to execute.

Supported option Values

Option	Description
ps	Lists all existing containers.
images	Lists all available container images.
run	Starts a container.
status	Displays the runtime state (e.g., “active” if running).
exec	Executes a command within a running container.
tag	Renames an image (e.g., docker tag oldImage newImage).
pull	Pulls a specified image.
push	Pushes a specified image. (Not available in CRI-O.)
stop	Stops a specified container.
start	Starts a specified container.
deleteCon	Deletes a specified container.

ContainerD-Specific Commands

Option	Description
psTask	Lists all existing tasks for containerd.
startTask	Starts a task from a given container.
stopTask	Stops a specified task.
deleteTask	Deletes a specified task.

podConfig and containerConfig

These keys specify JSON or YAML configuration files required for pod creation (e.g., podConfiguration.json or podConfiguration.yaml).

Example 1 - List Running Containers (ps)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / containerd"; 
        option = "ps";
        flag = "--last";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 2 - List Images (images)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / containerd"; 
        option = "images";
        flag = "--all";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 3 - Run a Container (run)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / containerd"; 
        option = "run";
        flag = "-w /path/to/dir/ -i -t";
        srcImage = "registry.kubernative.net/lima:v0.8.0";
        containerName = "myFirstContainer";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 4 - Run a CRI-O Pod

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

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

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

install
{
    containerruntime
    (
        type = "crio"; 
        option = "run";
        containerConfig = "/root/podConfig.json / .yaml";
        podConfig = "/root/podConfig.json / .yaml";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 5 - Check Runtime Status (status)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / contianerd"; 
        option = "status";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 6 - Execute a Command in Containerd (exec)

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

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

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

install
{
    containerruntime
    (
        type = "contianerd"; 
        option = "exec";
        execID = "exec1";
        containerName = "registry.kubernative.net/lima:v0.8.0";
        command = "mkdir /tmp/testdir";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 7 - Execute a Command in Docker / CRI-O (exec)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio"; 
        option = "exec";
        containerName = "registry.kubernative.net/lima:v0.8.0";
        command = "mkdir /tmp/testdir";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 8 - Tag an Image (tag)

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

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

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

install
{
    containerruntime
    (
        type = "docker / containerd"; 
        option = "tag";
        srcImage = "registry.kubernative.net/lima:v0.8.0"; 
        destImage = "yourRegistry/yourName:v0.8.0";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 9 Start, Stop, or Delete a Container (deleteCon, start, stop)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / containerd"; 
        option = "deleteCon / start / stop";
        containerName = "myFirstContainer";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 10 - Pull or Push an Image (pull, push)

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

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

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

install
{
    containerruntime
    (
        type = "docker / crio / containerd"; 
        option = "pull / push";
        srcImage = "registry.kubernative.net/lima:v0.8.0";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Note: CRI-O does not support the push and tag operations.

ContainerD-Specific Commands

Example 11 List Tasks (psTask)

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

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

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

install
{
    containerruntime
    (
        type = "containerd"; 
        option = "psTask";
        flag = "--all";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 12 Start, Stop, or Delete a Task

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

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

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

install
{
    containerruntime
    (
        type = "containerd"; 
        option = "startTask /stopTask / deleteTask";
        flag = "--null-io";
        containerName = "myFirstTask";
        runtime = "status";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Kosi: copy-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin copy Version 2.2.0

Summary

The copy plugin allows you to copy either a single file or an entire directory, including all its contents, recursively. It provides options to control overwriting behavior when files already exist in the destination.

Keys

Key		Description
src	Mandatory	Specifies the absolute path of the source file or directory to be copied.
dest	Mandatory	Specifies the absolute path of the destination file or directory where the source will be copied.
overwrite	true/false	Controls whether existing files in the destination should be replaced.

If set to true, any file in the destination with the same name will be replaced.
If set to false, an error will be thrown if the file already exists in the destination.
If no file with the same name exists, the file will be copied normally, regardless of the overwrite setting.

⚠️ Warning: Overwritten data will be permanently lost and cannot be recovered! Proceed with caution. ⚠️

Usage

Example 1 - Copy file

The following example demonstrates how to copy a single file from a source location to a destination.

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

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

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

install
{
    copy
    (
        src = "/absolute/path/to/file"; 
        dest = "/absolute/path/to/the/dest/file";
        overwrite = "true/false";
    );
}

Note: Copying a file will not change its name. The destination file will retain the same name as the source file unless explicitly changed in the dest parameter.

Example 2 - Copy folder

The following example demonstrates how to copy a folder from a source location to a destination.

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

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

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

install
{
    copy
    (
        src = "/absolute/path/to/folder"; 
        dest = "/absolute/path/to/the/dest/folder";
        overwrite = "true/false";
    );
}

Example 3 - Copying multiple files with a specific extension

The following example copies all .txt files from the source directory to the destination directory.

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

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

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

install
{
    cmd(command = "echo Copying all .txt files from source to destination");
    copy
    (
        src = "/absolute/path/to/source/*.txt"; 
        dest = "/absolute/path/to/destination/"; 
        overwrite = "true/false";
    );
}

Kosi: editFile-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin editFile Version 2.2.0

Summary

The editFile plugin allows automated modifications to YAML and plain text files by supporting three main operations: add, overwrite, and delete. It enables precise targeting by allowing users to specify YAML keys or line numbers for text files.

Keys

Key	Required	Description
`operation`	Yes	Defines the type of modification: `add`, `overwrite`, or `delete`.
`filePath`	Yes	Absolute path to the file being edited.
`fileType`	Yes	File type: `yaml` or `text`.
`key`	Required for fileType `yaml`	Specifies the YAML key to be modified (dot-separated path format).
`line`	Required for fileType `text`	Line number for the operation (1-based indexing).
`value`	Required for operation `add` and `overwrite`	The content to insert or replace. Escaped linebreaks (`\\n`) and tabs (`\\t`) are supported in text files.

Notes:

For YAML files, only the key field is used to identify the node.

For text files, only the line field is required to specify the line position.

For value in text: Double escaping (\\n, \\t) is required because the configuration parser interprets strings literally.

If using overwrite operation, ensure the file has enough lines, otherwise you may get an IndexOutOfRange error.

Examples

YAML File Examples

Sample YAML File

Shown as /root/KosiPlugin/config.yaml in the examples below

spec:
  clusterMaster:
    existingText: this is an example
    toBeOverwritten: this will be replaced

Example 1 - Add a new value

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

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

install
{
    editFile
    (
        operation = "add";
        fileType = "yaml";
        filePath = "/root/KosiPlugin/config.yaml";
        key = "spec.clusterMaster.newEntry";
        value = "new value added";
    );
}

Expected Result:

spec:
  clusterMaster:
    existingText: this is an example
    toBeOverwritten: this will be replaced
    newEntry: new value added

Example 2 - Overwrite an existing value

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

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

install
{
    editFile
    (
        operation = "overwrite";
        fileType = "yaml";
        filePath = "/root/KosiPlugin/config.yaml";
        key = "spec.clusterMaster.toBeOverwritten";
        value = "this text has been replaced";
    );
}

Expected Result:

spec:
  clusterMaster:
    existingText: this is an example
    toBeOverwritten: this text has been replaced

Example 3 - Delete a YAML key

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

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

install
{
    editFile
    (
        operation = "delete";
        fileType = "yaml";
        filePath = "/root/KosiPlugin/config.yaml";
        key = "spec.clusterMaster.toBeOverwritten";
    );
}

Expected Result:

spec:
  clusterMaster:
    existingText: this is an example

Text File Examples

Sample Text File

Shown as /root/KosiPlugin/todo.txt in the examples below

To-do List:
 - Buy groceries
 - Clean house
 - Pay bills

Example 1 - Add a new line

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

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

install
{
    editFile
    (
        operation = "add";
        fileType = "text";
        filePath = "/root/KosiPlugin/todo.txt";
        line = "'4'";
        value = " - Call the bank";
    );
}

Expected Result:

To-do List:
 - Buy groceries
 - Clean house
 - Pay bills
 - Call the bank

Example 2 - Overwrite an existing line

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

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

install
{
    editFile
    (
        operation = "overwrite";
        fileType = "text";
        filePath = "/root/KosiPlugin/todo.txt";
        line = "'3'";
        value = " - Pay insurance";
    );
}

Expected Result:

To-do List:
 - Buy groceries
 - Clean house
 - Pay insurance

Example 3 - Delete a line

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

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

install
{
    editFile
    (
        operation = "delete";
        fileType = "text";
        filePath = "/root/KosiPlugin/todo.txt";
        line = "'2'";
    );
}

Expected Result:

To-do List:
 - Clean house
 - Pay bills

Advanced Text Example - Multiline Overwrite

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

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

install
{
    editFile
    (
        operation = "overwrite";
        fileType = "text";
        filePath = "/root/KosiPlugin/script.txt";
        line = "'3'";
        value = "Cluster Configuration:\\n  clusterName: exampleCluster\\n  hosts:\\n    nodes:\\n      - 192.168.79.130";
    );
}

Expected Behavior:

The plugin replaces lines 3 to 7 with the specified text.
The target file must have at least 5 lines from line 3 onward. Otherwise, an IndexOutOfRange error will be thrown.

Hint: Always ensure the file has enough lines when using multiline value with overwrite on text files.
Escape Rule: When using special characters in value, escape them as \\n (newline), \\t (tab) in text files.

Kosi: firewall-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Firewall Version 2.2.0

Required Plugins

osCheck
firewallD
IPTables

Summary

The Firewall Plugin allows you to manage your firewall settings efficiently. You can open or close ports, enable or disable the firewall, and retrieve the current firewall status. The plugin currently supports two firewall types:

Keys

Key		Description
type	Mandatory	Specifies the firewall type to which actions will be applied (`firewalld` or `iptables`).
action	Mandatory	Defines the action to be performed (e.g., `enable`, `disable`, `open`, or `close` ports).
ports	Mandatory	Required when opening or closing ports. Accepts a list of ports in the format: “ports” or “ports-range”/protocol.
getFirewallStatus	Mandatory	Stores the firewall status, which can be either “running” or “not running”. If both firewalld and iptables are running, firewalld is selected.

Example

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

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

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

install
{
    firewall
    (
        type = "firewalld";
        action = "close / open / disable";
        ports = "['5555/tcp','6666/tcp','8888-9999/udp']";
        getFirewallStatus = "status";
    );

    fprint
    (
        message = "The firewall is {0}"; 
        variables = "['status']";
    );
}

Kosi: firewallD-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin FirewallD Version 2.2.0

Required Plugins

firewallD

Summary

The FirewallD Plugin allows you to manage your firewall settings efficiently. You can open or close ports, enable or disable the firewall, and retrieve the current firewall status. The plugin currently supports two firewall types:

Keys

Key		Description
action	Mandatory	Defines the action to be performed (e.g., `enable`, `disable`, `open`, or `close` ports).
ports	Mandatory	Required when opening or closing ports. Accepts a list of ports in the format: “ports” or “ports-range”/protocol.
getFirewallStatus	Mandatory	Stores the firewall status, which can be either “running” or “not running”. If both firewalld and iptables are running, firewalld is selected.

Example

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

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

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

install
{
    firewallD
    (
        action = "open";
        ports = "['5555/tcp','6666/tcp','8888-9999/udp']";
        getFirewallStatus = "status";
    );
}

Kosi: fprint-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin fprint Version 2.2.0

Summary

The fprint plugin functions similarly to the print plugin by allowing messages to be displayed as key-value pairs. However, fprint extends this functionality by enabling the inclusion of variables from other plugins, which are also printed as part of the message.

For details on handling variables from other plugins, see the loop-plugin Reference.

Keys

Key		Description
message	Mandatory	A string that represents the command-line output message.
variables	-	A list of strings representing variable names. If these variables were created by other plugins, fprint will retrieve and include their values in the message.

Example

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

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

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

install
{
    set
    (
        variable = "name";
        value = "root";
    );

    set
    (
        variable = "ips";
        value = "0.0.0.0";
    );

    fprint
    (
        message = "Hello {0} with the ips {1}"; 
        variables = "['vars.name','vars.ips']";
    );
}

Kosi: helm-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Helm Version 2.2.0

Summary

The Helm Plugin allows users to manage Helm packages. It enables the installation, upgrade, and deletion of Helm charts via KOSI package.

The Key Features are:

Install Helm charts with custom values and additional flags.
Upgrade existing Helm deployments.
Delete Helm deployments.
Supports namespace customization.
Allows the use of multiple values files for configuration.

Keys

Key	Required	Description
`command`	Yes	Defines the operation to perform. Possible values: `install`, `upgrade` or `delete`.
`tgz`	Yes (only for `install` and `upgrade`)	The filename of the Helm chart archive (`.tgz`).
`values`	Optional	A list of YAML files containing configuration values for the Helm chart.
`flags`	Optional	Additional Helm command flags.
`namespace`	Optional, Default: `default`	The Kubernetes namespace in which to deploy the chart.
`deploymentName`	Yes (only for `upgrade` and `delete`)	Specifies the name of the Helm release. If omitted during installation, a random name will be generated.

Important Notes:

A helmvalues.yaml file must be present in the execution directory when running KOSI install commands.

The Helm .tgz package (Helm chart) must be included in the files tree inside the includes tree.

KOSI’s --dname argument is not related to Helm’s deploymentName parameter. --dname in KOSI is used to define a KOSI deployment name, whereas deploymentName in the Helm plugin specifies the Helm release name.

Helm charts and values files (.tgz and .yaml) can be obtained from sources like ArtifactHub, or you can package your own Helm chart using helm package. Knowledge of Helm is required here.

Examples

Example 1 - Helm Install

This command deploys a Helm chart to a Kubernetes cluster.

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

files =
{
    guestbook = "guestbook.tgz";
    values1 = "gbValues.yaml";
    values2 = "values2.yaml";
}

install
{
    cmd(command="echo Installing Helm chart...");

    helm
    (
        command = "install";
        tgz = "guestbook.tgz";
        values = "['gbValues.yaml','values2.yaml']";
        deploymentName = "guestbook";
        namespace = "dev";
    );
}

Explanation

The guestbook.tgz Helm chart is installed.
Values files (gbValues.yaml and values2.yaml) customize the deployment.
The Helm release is named guestbook in the dev namespace.
The cmd plugin ensures a status message is displayed before execution.

Example 2 - Helm Upgrade

Upgrades an existing Helm release to a new version or updates its values.

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

files =
{
    guestbook = "guestbook.tgz";
    values1 = "gbValues.yaml";
    values2 = "values2.yaml";
}

update
{
    cmd(command = "echo Upgrading Helm chart...");

    helm
    (
        command = "upgrade";
        tgz = "guestbook.tgz";
        values = "['gbValues.yaml','values2.yaml']";
        deploymentName = "guestbook";
        namespace = "dev";
    );
}

Explanation

Upgrades the existing guestbook Helm release using an updated guestbook.tgz chart.
New configuration values are applied from gbValues.yaml and values2.yaml.

Example 3 - Helm Delete

Deletes a Helm release from the Kubernetes cluster.

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

files =
{
    guestbook = "guestbook.tgz";
    values1 = "gbValues.yaml";
    values2 = "values2.yaml";
}

delete
{
   cmd(command = "echo Deleting Helm chart...");

   helm
   (
      command = "delete";
      deploymentName = "guestbook";
      namespace = "dev";
      flags = "['--wait']";
  );
}

Explanation

Deletes the guestbook release from the dev namespace.
The --wait flag ensures the command waits for all resources to be fully removed.

Kosi: hostname-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin hostname Version 1.7.0

Summary

The hostname plugin for KOSI allows users to manage and modify the hostname of a machine dynamically. It provides functionalities to:

Retrieve and store the current hostname in an internal variable.
Permanently set a new hostname.
Use a previously stored hostname variable to restore the hostname.
Optionally execute hostname changes with elevated privileges (sudo).

This plugin is particularly useful in automated deployments, system provisioning, or scenarios where hostnames need to be dynamically managed during a KOSI package installation.

Keys

Key	Required	Description
`get`	Optional*	Retrieves the current hostname and saves it in a variable for later use. This variable remains accessible until the KOSI session ends.
`set`	Optional*	Sets the machine’s hostname to the specified value.
`setVar`	Optional*	Sets the hostname using a previously stored variable from the internal storage.
`sudo`	Optional	If set to `true`, the plugin will execute commands with `sudo` privileges.
`sudoPassword`	Yes if `sudo` is `true`	The password required for executing `sudo` commands.

Note:

* One of the keys must be present. (Either get, set or setVar)

The sudoPassword is mandatory if sudo is enabled, ensuring the required privileges for modifying system settings.

Examples

Example 1 - Retrieve and Store the Current Hostname

This example retrieves the current hostname and saves it in the internal variable oldHostname. The variable can be used later within the same KOSI session.

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

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

install
{
    hostname
    (
        get = "oldHostname";
        sudo = "true";
        sudoPassword = "YourSecurePassword";
    );
}

Example 2 - Set a New Hostname

This example sets the machine’s hostname to master permanently.

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

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

install
{
    hostname
    (
        set = "master";
        sudo = "true";
        sudoPassword = "YourSecurePassword";
    );
}

After execution, the system’s hostname will be permanently changed to master.

Example 3 - Restore a Previously Stored Hostname

If a hostname was previously retrieved and stored in oldHostname, this example restores it.

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

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

install
{
    hostname
    (
        setVar = "oldHostname";
        sudo = "true";
        sudoPassword = "YourSecurePassword";
    );
}

This is particularly useful in rollback scenarios where a hostname needs to be reverted to its original value after temporary changes.

Example 4 - Using hostname Plugin with other plugins

Using hostname with the if and print plugins

This example shows the interaction of several plugins. In this example, we use the hostname plugin together with the if and print plugins to check whether it is the correct hostname and to output a specific message and perform a corresponding action:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-hostname-if-print";
description = "Example using hostname with if and print";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

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

install
{
    hostname(get = "oldHostname");

    if (condition = "$oldHostname$ = 'myHostname'") then
    {
        print(message = "The hostname myHostname should not be taken, so the hostname is changed to myVeryVeryNewHostname..");

        hostname
        (
            set = "myVeryVeryNewHostname";
            sudo = "true";
            sudoPassword = "SecurePassword";
        );
    }
    else
    {
        print(message = "The hostname is OK, do not make any changes.");
    }
}

Expected Behavior

If hostname is myHostname:

2025-02-26 15:18:28 Info:      The hostname myHostname should not be taken, so the hostname is changed to myVeryVeryNewHostname..

The hostname is changed to myVeryVeryNewHostname.

Otherwise:

2025-02-26 15:18:28 Info:      The hostname is OK, do not make any changes.

As we have not specified anything else in the else part of the if plugin, nothing else happens in the else part.

Kosi: if-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin if Version 2.2.0

Summary

The ‘if’ Plugin for KOSI packages enables the introduction of conditional control flow into your workflow. This plugin allows you to define logic that executes specific actions based on whether a given condition is met. It functions similarly to traditional programming if-else statements, where:

If the specified condition evaluates to true, a designated block of actions is executed.
Else (optional): If the condition evaluates to false, an alternative set of actions can be executed instead.

This functionality provides greater flexibility and decision-making capabilities within KOSI packages, allowing workflows to dynamically adapt based on real-time conditions.

Keys

Key		Description
condition	Mandatory	set to a string that will be evaluated as an expression. Condition is based on net5.0 DataColumn expressions and follows almost the same syntax. The only difference are plugin variables can also be used in the condition
then	Mandatory	defines the block of commands that execute if the ‘condition’ evaluates to true. Commands inside the then block will run sequentially when the condition holds true.
else	Optional	defines an alternative block of commands that execute if the ‘condition’ evaluates to false. If omitted, no alternative actions will take place when the condition is false.

Syntax to access plugin variables inside condition :

When using the set plugin:

condition = "$vars.variableName$"

When using other plugins that set variables (for example osCheck):

condition = "$variableName$"

Syntax to access KOSI templating of values.yaml inside condition :

condition = '{{values.variable}}'

Example

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

files =
{
    guestbook = "guestbook.tgz";
    gbValues = "gbValues.yaml";
    values2 = "values2.yaml";
}

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

install
{
    cmd(command = "echo Using the if plugin.");

    if(condition = "'{{values.myVar}}' < 0") then
    {
        print(message = "myVar is less than 0.");
    }
    else
    {
        print(message = "myVar is equal or greater than 0.");
    }
    
    print(message = "This will always print.");
}

Result

[ 06/22/2021 16:56:54 Info    default ] myVar is equal or more than 0 
[ 06/22/2021 16:56:54 Info    default ] this will always print

[ 06/22/2021 16:57:37 Info    default ] myVar is less than 0 
[ 06/22/2021 16:57:37 Info    default ] this will always print

All expressions are expected to evaluate to either ‘True’ or ‘False’ otherwise the ‘if’ plugin will exit with an error.

Kosi: ipTables-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin IPTables Version 2.2.0

Required Software

iptables

Summary

With this plugin you can manage iptables. You can either open/close ports or disable/enable it. Additionally it is possible to gather information about the iptables status.

Keys

Key		Description
action	Mandatory	Similiar to the service Plugin you can `enable` and `disable` iptables as well as `open` and `close` ports.
ports	–	If you want to open or close any ports the key ports which requires a list (`"ports" or "ports-range"/protocol`) is mandatory. Any ports like in the schema above are valid.
getFirewallStatus	–	set to a variable name in which status of the iptables will be stored. The status will be either: `"running" / "not running"`

Example

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

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

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

install
{
    iptables
    (
        action="close / open / disable";
        ports="['5555/tcp','6666/tcp','8888-9999/udp']";
        getFirewallStatus="status"
    );
}

Kosi: kosi-2.15.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin kosi Version 2.15.0

Summary

The kosi plugin provides a means to use features of kosi within a kosi plugin. It enables automation of various package operations, such as logging into a registry, pulling packages, installing, updating, and deleting them within a Kubernetes cluster.

With the kosi plugin, you can:

Automatically authenticate to a package registry (hub)
Install packages
Update already installed packages
Delete deployed packages
Pull packages for offline usage or custom deployment scenarios

This plugin is particularly useful for automating deployment workflows, ensuring that Kubernetes resources are managed efficiently.

Keys

Depending on the command being executed, different keys must be set. Below is a list of available keys:

Key	Required	Default Value	Description
`command`	Yes	-	Specifies the KOSI command to execute (`login`, `install`, `update`, `delete`, `pull`).
`userVar`	Yes (for `login`)	-	The username for authentication.
`passwordVar`	Yes (for `login`)	-	The password in plain text for authentication.
`userHub`	Yes	-	The user hub (registry) to interact with. Use `public` for public repositories.
`sourcePath`	Yes (for `install`, `delete`, `update`)	-	The package name or path to install, update, or delete.
`sourceRegistry`	Yes (for `install`, `delete`, `update`)	-	The registry where the package is located.
`local`	Optional (for `install`, `delete`, `update`)	`false`	Either a package from a hub or a local KOSI package.
`deploymentName`	Optional	Package name	Name assigned to the deployed package in the cluster. Required for updates.
`nameSpace`	Optional	`default`	Kubernetes namespace where the package is deployed.
`package`	Yes (for `pull`)	-	Name of the package to pull.
`packageDestinationPath`	Yes (for `pull`)	-	Path where the pulled package should be saved.
`destinationRegistry`	Optional (for `pull`)	-	Destination registry if retagging is enabled.
`targetRegistry`	Optional (for `pull`)	-	Target registry for retagged images.
`retag`	Optional	`false`	Whether to retag images when pulling.
`values`	Optional	-	A list of values equivalent to the `-f` option in KOSI CLI.

Features

Login enables you to log in to your KubeOps user account. This is required to upload packages to a hub and to download packages from a private hub.
Both the username and password must be entered in plain text in package.yaml.

Install

The install command can be used to download and install packages from any registry. If this is a public package you have to set your userHub to “public”. Otherwise you have to set the userHub, where the package is located. In addition, the namespace in which the package is to be installed can be specified and the name of the deployed package in the cluster can be changed.

Update

The 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 (example 3 - Update). If this is a public package you have to set your userHub to “public”. Otherwise you have to set the userHub, where the package is located

Delete

The delete command can be used to delete packages from any registry. The command delete expected parameters like sourcePath, sourceRegistry and deploymentName, which are also marked as required. If this is a public package you have to set your userHub to “public”. Otherwise you have to set the userHub, where the package is located

The nameSpace parameter can be used to specify the name of the package to be deleted.

Pull

The pull command can be used to pull packages from any registry. The command pull expected parameters like package, packageDestinationPath and userHub, which are also marked as mandatory. If you want to pull your images in your own registry you can use the destinationRegistry parameter. If you want to pull your images in your own registry and change your deployment automatically you can use destinationRegistry and targetRegistry. In both scenarios you have to use the retag parameter.

Examples

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    kosi
    (
        command = "login";
        userVar = "exampleUser";
        passwordVar = "examplePW";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
    );
}

Example 2 - Install

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    kosi
    (
        command = "install";
        sourcePath = "kosi/kubeops-kubernetes-plugins:0.0.1";
        sourceRegistry = "registry1.kubeops.net";
        deploymentName = "kubernetes-plugins";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
        nameSpace = "kosi";
        values = "['values.yaml']";
        userHub = "public";
        local = "false";
    );
}

Example 3 - Install local package

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    kosi
    (
        command = "install";
        sourcePath = "/root/kosi-test/package.tgz";
        sourceRegistry = "registry1.kubeops.net";
        deploymentName = "kubernetes-plugins";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
        nameSpace = "kosi";
        values = "['values.yaml']";
        userHub = "public";
        local = "true";
    );
}

Example 4 - Update

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

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

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

update
{
    kosi
    (
        command = "update";
        sourcePath = "/root/kosi-test/package.tgz";
        sourceRegistry = "registry1.kubeops.net";
        deploymentName = "kubernetes-plugins";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
        nameSpace = "kosi";
        values = "['values.yaml']";
        userHub = "public";
        local = "true";
    );
}

Example 5 - Delete

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

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

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

delete
{
    kosi
    (
        command = "delete";
        sourcePath = "/root/kosi-test/package.tgz";
        sourceRegistry = "registry1.kubeops.net";
        deploymentName = "kubernetes-plugins";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
        nameSpace = "kosi";
        values = "['values.yaml']";
        userHub = "public";
        local = "true";
    );
}

Example 6 - Pull with retag

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    kosi
    (
        command = "pull";
        hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
        package = "lima/kubernetes:1.24.7";
        packageDestinationPath = "/root/kubernetes-1.24.7/package.tgz";
        destinationRegistry = "localhost:5000/myimages";
        targetRegistry = "myregistry.net/myimages";
        retag = "true";
    );
}

Example 7 - Using Kosi Plugin with other plugins

Using kosi with the osCheck, if and print plugins

This example shows the interaction of several plugins. In this example, we use the kosi plugin together with the osCheck, if and print plugins to check whether it is the correct operating system and to output a specific message as well as to execute a corresponding Kosi install operation with the kosi plugin:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-kosi-oscheck-if-print";
description = "Example using kosi with oscheck and if and print";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files = 
{
    inputRhel = "rhel8.yaml";
    inputOtherOS = "otherOs.yaml";
}

install
{
    osCheck
    (
        getOSVar = "os";
        getOSVersionVar = "version";
    );

    if (condition = "$os$ = 'Red Hat Enterprise Linux'") then
    {
        print(message = "Performing Kosi install for RHEL 8..");
        kosi
        (
            command = "install";
            sourcePath = "/root/kosi-test/rhel8/package.tgz";
            sourceRegistry = "registry1.kubeops.net";
            deploymentName = "rhel8-kosi";
            hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
            nameSpace = "kosi";
            values = "['rhel8.yaml']";
            userHub = "public";
            local = "true";
        );
    }
    else
    {
        print(message = "Other OS recognized instead of RHEL 8, performing alternative Kosi install..");
        kosi
        (
            command = "install";
            sourcePath = "/root/kosi-test/otherOs/package.tgz";
            sourceRegistry = "registry1.kubeops.net";
            deploymentName = "otherOs-kosi";
            hub = "https://dispatcher.kubeops.net/v4/dispatcher/";
            nameSpace = "kosi";
            values = "['otherOs.yaml']";
            userHub = "public";
            local = "true";
        );
    }
}

Expected Behavior

If os is Red Hat Enterprise Linux:

2025-02-26 15:18:28 Info:      Performing Kosi install for RHEL 8..

The local Kosi package /root/kosi-test/rhel8/package.tgz is installed with the values rhel8.yaml.

Otherwise:

2025-02-26 15:18:28 Info:      Other OS recognized instead of RHEL 8, performing alternative Kosi install..

The local Kosi package /root/kosi-test/otherOs/package.tgz is installed with the values otherOs.yaml.

Kosi: kubeadm-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin kubeadm Version 2.2.0

Summary

This plugin can be used to execute kubeadm commands.

Keys

Key		Description
action	-	Action performed when upgrade is used as an operation.
kubeadmVersion	-	Any offical verb supported by Kubernetes is allowed when you try the operation “config” or “can-i”
outputVar	Mandatory	Save the output of the executed command in the offered variable.
sudo	-	Can be true or false. If it is true the Plugin will be executet with sudo privileges.
sudoPassword	-	If you use sudo, sudoPassword will be mandatory.
phase	-	Phase which will be initialized when using init phase as an operation.
token	-	Save the token of the token create command in the offered variable.
operation	-	The operations shown above are currently supported when using the kubeadm plugin. Depending on the operation the following inputs are required:

Operation “version” requires kubeadmVersion to save the output kubeadmVersion. It’s recommended to use the flag -o short to get only the Version as output.
Operation “init phase” requires a phase. E.g certs or kubeconfig.
Operation “token create” requires a token to save the created token into a variable.
Operation “upgrade” requires an action. E.g plan oder apply.

action

Action performed when upgrade is used as an operation.

kubeadmVersion

Any offical verb supported by Kubernetes is allowed when you try the operation “config” or “can-i”

operation

The operations shown above are currently supported when using the kubeadm plugin. Depending on the operation the following inputs are required:

Operation “version” requires kubeadmVersion to save the output kubeadmVersion. It’s recommended to use the flag -o short to get only the Version as output.
Operation “init phase” requires a phase. E.g certs or kubeconfig.
Operation “token create” requires a token to save the created token into a variable.
Operation “upgrade” requires an action. E.g plan oder apply.

Example

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

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

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

install
{
    kubeadm(
      operation="version"/"reset"/"init"/"init phase"/"token create"/"upgrade";
      kubeadmVersion="version";
      phase="kubelet-start"/"certs"/"kubeconfig"/"control-plane"/"...";
      action="plan"/"apply"/"node"/"apply v1.22.x"/"...";
      flag="-f PathToYAML -n kube-system -o wide"/"...";
      outputVar="outputStorage";
      token="kubeadmToken";
      sudo="true";
      sudoPassword="Drowssap");
}

Kosi: kubectl-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Kubectl Version 2.2.0

Summary

The kubectl plugin allows to interact with Kubernetes clusters by executing kubectl commands within a KOSI package. This plugin provides a convenient way to manage Kubernetes resources, retrieve information and execute administrative tasks directly within a KOSI package. It supports various kubectl operations, including retrieving, creating, updating, and deleting Kubernetes resources.

The plugin integrates seamlessly with Kubernetes by supporting all official resource types and their associated subcommands. Additionally, it allows users to save command outputs as variables or files and provides the option to execute commands with elevated privileges using sudo.

Keys

Key	Required	Description
operation	Yes	Specifies the `kubectl` subcommand to execute, such as `get`, `apply`, `delete`, etc.
resource	Yes (for most operations)	Defines the type of Kubernetes resource being operated on (e.g., `pod`, `service`, `deployment`).
resourceName	Optional	Specifies the name(s) of the resource(s) to target. Names are case-sensitive. If omitted, the command applies to all resources of the given type.
flags	Optional	Additional flags for the `kubectl` command. If using `-f`, an absolute file path must be provided. Multiple flags should be separated by spaces. Example: `"-f /path/to/file.yaml -A -o wide"`.
verb	Optional	Specifies an additional action supported by Kubernetes, such as `can-i` for checking permissions. Used in combination with relevant operations.
outputVar	Optional	Stores the command output in a variable for use in subsequent operations within the KOSI package.
outputFile	Optional	Saves the output of the command to a specified absolute file path.
sudo	Optional	Set to `true` to execute the command with sudo privileges.
sudoPassword	Yes (if sudo is enabled)	Specifies the password required for sudo execution.

Notes:

Ensure that the Kubernetes cluster is accessible from the system where KOSI is running.

When using sudo, ensure the correct password is provided, or configure NOPASSWD for the executing user in the system’s sudoers file.

The plugin supports all standard Kubernetes resources and their associated operations.

Use outputVar or outputFile to capture command outputs for further processing.

Examples

Example 1 - Retrieving Information About a Specific Pod

This example retrieves details about a specific pod called testDeployment in the kube-system namespace. The output is stored in a variable and saved to a file.

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

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

install
{
    kubectl
    (
        operation = "get";
        resource = "pods";
        resourceName = "testDeployment";
        flags = "-n kube-system -o wide";
        outputVar = "outputGet";
        outputFile = "/root/outputKubectlGet.txt";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 2 - Checking User Permissions

This example checks whether the current user has permission to list pods in the cluster using the can-i command.

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

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

install
{
    kubectl
    (
        operation = "auth";
        verb = "can-i";
        flags = "list pods";
        outputVar = "permissionCheck";
    );
}

Example 3 - Applying a Configuration File

This example applies a Kubernetes manifest file located at /home/user/deployment.yaml.

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

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

install
{
    kubectl
    (
        operation = "apply";
        flags = "-f /home/user/deployment.yaml";
    );
}

Example 4 - Deleting Multiple Pods

This example deletes two specific pods named example-pod1 and example-pod2 with sudo privileges.

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

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

install
{
    kubectl
    (
        operation = "delete";
        resource = "pod";
        resourceName = "example-pod1 example-pod2";
        sudo = "true";
        sudoPassword = "Drowssap";
    );
}

Example 5 - Saving Output to a File

This example retrieves a list of all services and saves the output to a file at /var/log/kubectl_services.log.

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

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

install
{
    kubectl
    (
        operation = "get";
        resource = "services";
        flags = "-A";
        outputFile = "/var/log/kubectl_services.log";
    );
}

Kosi: loop-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin loop Version 2.2.0

Summary

The loop plugin enables repeated execution of specific parts of your KOSI package YAML while iterating over a list. It functions similarly to a “for each” loop in other programming languages. During each iteration, an iterator variable holds the current element from the list, allowing dynamic access within the looped section.

Keys

Key		Description
iterator	Mandatory	Specifies the variable name that will hold the current item in the list during each loop iteration. Must be a valid string representing a variable name.
list	Mandatory when listVar is not set	Defines an inline list in YAML format that will be iterated over. Cannot be used together with listVar.
listVar	Mandatory when list is not set	Specifies a pre-defined variable (set by another plugin) that contains a list. Allows looping over dynamic lists instead of hardcoded values.

Example 1 - Iterating Over a List

In this example, the loop iterates over a predefined list [1,2,3], and the number iterator variable holds the current item in each iteration.

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

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

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


install 
{  
    loop
    (
        iterator = "number";
        list = "[1,2,3]";
    )
    {
        fprint
        (
            message = "Hello {0}";
            variables ="[number]";
        );
    }
}

[ 06/18/2021 13:04:29 Info    default ] Hello 1
[ 06/18/2021 13:04:29 Info    default ] Hello 2
[ 06/18/2021 13:04:29 Info    default ] Hello 3

Kosi: merge-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Merge Version 2.2.0

Summary

The Merge plugin for KOSI enables the merging of XML files, allowing users to combine multiple XML sources into a single target file within a KOSI package.

The plugin supports merging a single XML file into another or merging all XML files within a specified directory into a target file. Additionally, users can create a backup of the original target file before applying the merge, ensuring data safety.

Features

Merges XML files: Supports merging one or multiple XML source files into a target XML file.
Directory merging support: Merges all XML files from a specified directory into the target file.
Backup creation: Optionally stores a backup of the target file before merging.

Keys

Key	Required	Description
`file1`	Yes	The target XML file where the merge operation will be applied.
`file2`	Yes	The source XML file or directory containing multiple XML files to be merged into `file1`.
`backupPath`	Optional	If specified, a backup of `file1` will be created in this location before merging.

Notes

If file2 is a single file, that file will be merged into file1.

If file2 is a directory, all XML files within that directory will be merged into file1.

The plugin only supports XML files at this time. Other file formats are not supported.

Examples

Example 1 - Merging a single XML file into another

This example merges /root/config-update.xml into /root/config.xml, while keeping a backup of /root/config.xml in the /root/backup/ directory.

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

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

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

install
{  
    merge
    (
      file1 = "/root/config.xml";
      file2 = "/root/config-update.xml";
      backupPath = "/root/backup/";
    );
}

Example 2 - Merging all XML files from a directory into a target file

In this case, the plugin merges all XML files located in /root/xml-updates/ into /root/main-config.xml. A backup of /root/main-config.xml is created in /root/backup/ before applying the merge.

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

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

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

install
{  
    merge
    (
        file1 = "/root/main-config.xml";
        file2 = "/root/xml-updates/";
        backupPath = "/root/backup/";
    );
}

Example 3 - Merging without backup

This example merges /root/new-settings.xml into /root/settings.xml without creating a backup.

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

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

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

install
{  
    merge
    (
        file1 = "/root/settings.xml";
        file2 = "/root/new-settings.xml";
    );
}

Kosi: osCheck-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin osCheck Version 2.2.0

Summary

The osCheck plugin is used to detect the operating system name and version on which the plugin is executed. This information is stored in temporary variables, making it available for use by other plugins, such as fPrint. By utilizing osCheck, users can dynamically access OS details within their KOSI packages, enabling better system-specific configurations and logging.

Keys

Key		Description
getOSVar	Mandatory	Set a variable name in which the OS name should be stored.
getOSVersionVar	Mandatory	Set a variable name in which the OS version should be stored.

Examples

Example 1

In the example below, the OS name will be stored in the temporary variable os, and the version name in the variable version. The fprint plugin has been added to generate console output, displaying the detected OS name and version.

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

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

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

install 
{  
    osCheck
    (
        getOSVar = "os";
        getOSVersionVar = "version";
    );

    fprint
    (
        message = "The OS system is {0} in version {1}.";
        variables = "[os,version]"
    );
}

Expected Output

2025-01-31 16:56:23 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2025-01-31 16:56:24 Info:      The OS system is Red Hat Enterprise Linux in version 8.9.
2025-01-31 16:56:24 Info:      Installation successful.

Example 2

Using osCheck with the if and print plugins

This example shows the interaction of several plug-ins. In this example, we use the osCheck plugin together with the if and print plugins to check the condition whether it is the correct operating system and output a message accordingly:

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

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

install
{
    osCheck
    (
        getOSVar = "os";
        getOSVersionVar = "version";
    );

    if (condition="$os$ = 'Red Hat Enterprise Linux'") then
    {
        print(message = "This is the expected OS.");
    }
    else
    {
        print(message = "Wrong OS.");
    }
}

Expected Output

If os is ‘Red Hat Enterprise Linux’:

2025-02-26 15:18:28 Info:      This is the expected OS.

Otherwise:

2025-02-26 15:18:28 Info:      Wrong OS.

Kosi: packagemanager-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Packagemanager Version 2.2.0

Summary

The Packagemanager Plugin provides a possibility for managing software packages on supported Linux distributions within a KOSI package. With this plugin users can:

Install new software packages.
Update installed packages to the latest versions.
Remove software packages that are no longer needed.
List installed packages.
Search for available packages in the package repository.

Supported Linux Distributions

Currently, this plugin supports only CentOS and uses the YUM package manager for executing package-related operations.

Keys

Key	Mandatory	Description
`operation`	Yes	Defines the action to be performed. Acceptable values: `install`, `update`, `remove`, `list`, `search`.
`packages`	Yes	Specifies the package(s) to be managed. Multiple packages can be specified as a space-separated string.
`flags`	Optional	Optional flags for the package manager (e.g., `-y` for automatic confirmation, `-v` for verbose output).
`sudo`	Optional	Set to `true` to execute the command with elevated privileges. Default is `false`.
`sudoPassword`	Yes (if `sudo` is `true`)	Required if `sudo` is set to `true`. Specifies the password for executing commands with elevated privileges.

Examples

The following examples demonstrate different package management tasks using the Package Manager Plugin on a CentOS system.

Example 1 - Install a Package or Multiple Packages

Installs nano and containerd-1.4.10 using yum.

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

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

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

install
{  
    packagemanager
    (
        operation = "install";
        packages = "nano containerd-1.4.10";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 2 - Update a Package or Multiple Packages

Updates docker and containerd to the latest versions.

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

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

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

install
{  
    packagemanager
    (
        operation = "update";
        packages = "docker containerd";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 3 - Remove a Package

Removes nano from the system.

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

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

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

install
{  
    packagemanager
    (
        operation = "remove";
        packages = "nano";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 4 - List Installed Packages

Lists all installed packages related to containerd.

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

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

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

install
{  
    packagemanager
    (
        operation = "list";
        packages = "containerd";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 5 - Search for a Package

Searches for available kubernetes packages in the YUM repository.

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

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

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

install
{  
    packagemanager
    (
        operation = "search";
        packages = "kubernetes";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 6 - Consecutive Operations with Different Flags

Performs consecutive list operations on kubeadm, one with default settings and another with additional flags.

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

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

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

install
{  
    packagemanager
    (
        operation = "list";
        packages = "kubeadm";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );

    packagemanager
    (
        operation = "list";
        packages = "kubeadm";
        flags = "-y -v";
        sudo = "true";
        sudoPassword = "mySecurePassword";
    );
}

Example 7 - Using Packagemanager Plugin with other plugins

Using packagemanager with the osCheck, if and print plugins

This example shows the interaction of several plugins. In this example, we use the packagemanager plugin together with the osCheck, if and print plugins to check whether it is the correct operating system and to output a specific message and execute a corresponding Packagemanager operation with the packagemanager plugin:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-packagemanager-oscheck-if-print";
description = "Example using packagemanager with oscheck and if and print";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

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

install
{
    osCheck
    (
        getOSVar = "os";
        getOSVersionVar = "version";
    );

    if (condition = "$os$ = 'CentOS 7'") then
    {
        print(message="Performing Packagemanager operation for CentOS 7..");

        packagemanager
        (
            operation = "install";
            packages = "nano containerd-1.4.10";
            sudo = "true";
            sudoPassword = "mySecurePassword";
        );
    }
    else
    {
        print(message="Other OS recognized instead of CentOS 7, skipping");
    }
}

Expected Behavior

If os is CentOS 7:

2025-02-26 15:18:28 Info:      Performing Packagemanager operation for CentOS 7..

The nano and containerd-1.4.10 software packages are installed on the machine.

Otherwise:

2025-02-26 15:18:28 Info:      Other OS recognized instead of CentOS 7, skipping

As we have not specified anything else in the else part of the if plugin, nothing else happens in the else part.

Kosi: pia-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin PIA Version 2.2.0

Summary

The PIA plugin (Plugin-based Infrastructure Administrator) is designed to automate administrative tasks in Kubernetes clusters by enabling remote command execution and file transfers. It operates in two modes:

SSH Mode: Executes commands and transfers files via SSH, requiring a specified user with appropriate permissions.
K8s Mode: Uses the Kubernetes Mode (kubectl) to create and deploy custom resources for execution by the PIA operator.

This plugin simplifies managing multiple nodes, making it useful for executing system configurations, software deployments, and maintenance tasks across a cluster.

Keys

Key	Required	Description
`mode`	Yes	Defines how PIA operates. Possible values: `ssh` or `k8s`.
`nodes`	Yes (or only `labels`)	Specifies target nodes where commands should be executed. Either `nodes` or `labels` must be set.
`labels`	Yes (or only `nodes`)	Defines node selection via labels instead of explicit node names. Either `nodes` or `labels` must be set.
`files`	Optional	Lists files to be uploaded before executing the command. Files in `ssh` mode are uploaded to `PIAROOT`, located at `KUBEOPSROOT/pia`.
`command`	Yes	Specifies the command to be executed on the target nodes.
`user`	Yes in `ssh` mode	Defines the user for SSH connections. Typically requires root privileges.

Notes:

The user key is only applicable in SSH mode.

The default path for KUBEOPSROOT is /var/kubeops - in this case the PIAROOT is in /var/kubeops/pia.

Examples

Example 1 - SSH Mode

In this example, the PIA plugin transfers template.yaml to specified nodes and executes a command under the root user.

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    pia
    (
        mode = "ssh";
        nodes = "['cluster2master1', 'cluster2master2']";
        files = "['template.yaml']";
        command = "echo Hello World";
        user = "root";
    );
}

Expected Behavior

The template.yaml file is uploaded to PIAROOT, located at KUBEOPSROOT/pia on cluster2master1 and cluster2master2.
The command echo Hello World is executed on each node using SSH.
The connection is established under the root user.

Recommendation: The specified user should have root privileges to execute administrative commands effectively.

Example 2 - K8s Mode

In Kubernetes mode, the PIA plugin deploys a custom resource that gets processed by the PIA operator.

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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
{
    pia
    (
        mode = "k8s";
        nodes = "['cluster2master1','cluster2master2']";
        files = "['template.yaml']";
        command = "echo Hello World";
    );
}

Expected Behavior

The plugin generates a customresource.yaml in the KUBEOPSROOT/pia directory.
The template.yaml file is uploaded.
A Kubernetes Custom Resource is deployed, which the PIA operator processes.

Sample installation log:

[root@cluster2admin1 Test_Pia-Plugin]# kosi install -p package.tgz
2024-01-24 12:12:03 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2024-01-24 12:12:05 Info:      template.yaml start uploading to webserver.
2024-01-24 12:12:05 Info:      template.yaml successfully uploaded to webserver.
pia.kubeops.net/example-pia created
2024-01-24 12:12:08 Info:      Installation successful

Example 3 - Using PIA Plugin with other plugins

Using pia with the osCheck, if and print plugins

This example shows the interaction of several plugins. In this example, we use the pia plugin together with the osCheck, if and print plugins to check whether it is the correct operating system and to output a specific message and execute a corresponding PIA operation with the pia plugin:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-pia-oscheck-if-print";
description = "Example using pia with oscheck and if and print";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files = 
{
    inputRhel = "rhel8.yaml";
    inputOtherOS = "otherOs.yaml";
}

install
{
    osCheck(getOSVar = "os"; getOSVersionVar = "version");

    if (condition = "$os$ = 'Red Hat Enterprise Linux'") then
    {
        print(message = "Performing PIA operation for RHEL 8..");
        pia
        (
            mode = "ssh";
            nodes = "['cluster2master1']";
            files = "['rhel8.yaml']";
            command = "echo Hello RHEL 8";
            user = "rhel8User";
        );
    }
    else
    {
        print(message = "Other OS recognized instead of RHEL 8, performing alternative PIA operation..");
        pia
        (
            mode = "ssh";
            nodes = "['cluster2master1']";
            files = "['otherOs.yaml']";
            command = "echo Hello other OS";
            user = "otherUser";
        );
    }
}

Expected Behavior

If os is Red Hat Enterprise Linux:

2025-02-26 15:18:28 Info:      Performing PIA operation for RHEL 8..

The rhel8.yaml file is uploaded to cluster2master1.
The command echo Hello RHEL 8 is executed on each node using SSH.
The connection is established under the rhel8User user.

Otherwise:

2025-02-26 15:18:28 Info:      Other OS recognized instead of RHEL 8, performing alternative PIA operation..

The otherOs.yaml file is uploaded to cluster2master1.
The command echo Hello other OS is executed on each node using SSH.
The connection is established under the otherUser user.

PIA Operator (Plugin-based Infrastructure Administrator)

Additional Information

The PIA operator processes Kubernetes-based PIA tasks by handling deployed Custom Resources.

Note: The following information does not refer directly to the PIA plug-in, but to the CRD via PIA operator and serves as additional information on the functionality of PIA and as a possible alternative use.

Installation

Create values.yaml with registry credentials:

pullsecretRegistry: "https://registry.kubernative.net"
pullsecretUser: "<username>"
pullsecretPassword: "<userpassword>"
piaWebserverNodePort: 31213

Explanation:

pullsecretUser and pullsecretPassword are authentication credentials for the image registry.

piaWebserverNodePort defines the NodePort service for the PIA web server, which is used to manage uploaded files.

Install the PIA operator:

kosi install --hub public kubeops/piaoperator:0.1.0 -f values.yaml

Verifying Deployment

After installation, check if the operator is running:

kubectl get pods -n pia-test

Using the PIA Operator

There are two ways to use the operator:

Via the PIA plugin (as shown in the examples above).
By manually deploying a Custom Resource Definition (CRD).

Example: Pia Custom Resource

apiVersion: kubeops.net/v1alpha1
kind: Pia
metadata:
  name: hello-world
  namespace: pia-test
spec:
  command: "echo Hello world; sleep 60;"
  jobId: abcdef
  nodes:
  - cluster2worker1
  - cluster2worker3
  labels:
  #- kubeops-zone=zone2
  files:
  #- file1

Kosi: print-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Print Version 2.2.0

Summary

The Print plugin for KOSI allows users to display messages on the command line during a KOSI package operation. It is particularly useful for debugging, logging, or providing status updates within a KOSI package. You can print multiple messages in succession if needed.

Best Practices

Use the Print plugin to make your KOSI packages more user-friendly by providing status updates and progress messages.
Avoid excessive printing, which may clutter the terminal output; focus on critical information.
Messages are logged with timestamps, making them useful for debugging and tracking execution flow.

Keys

Key	Mandatory	Description
`message`	Yes	The text message to be displayed on the command line.

Examples

Example 1 - Printing a single message

This example demonstrates how to print a single message to the command line.

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

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

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

install
{
    cmd(command = "echo Starting the KOSI install package execution...");

    print(message = "Execution has started successfully.");
}

Output

Starting the KOSI install package execution...
2023-12-01 13:38:14 Info: Execution has started successfully.

Example 2 - Printing multiple messages

In this example, multiple messages are printed during different stages of execution.

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

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

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

install
{
    cmd(command = "echo Initializing installation process...");

    print(message = "Step 1: Checking prerequisites...");

    print(message = "Step 2: Downloading required files...");

    print(message = "Step 3: Installation in progress...");

    print(message = "Installation completed successfully.");
}

Output

Initializing installation process...
2023-12-01 13:41:20 Info: Step 1: Checking prerequisites...
2023-12-01 13:41:21 Info: Step 2: Downloading required files...
2023-12-01 13:41:23 Info: Step 3: Installation in progress...
2023-12-01 13:41:25 Info: Installation completed successfully.

Note: The example above does not download and install anything, it only shows a best practice example with the print plugin.

Kosi: service-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Service Version 2.2.0

Summary

The Service plugin allows you to manage system services by starting, stopping, restarting and checking their status. It acts as a wrapper for the systemctl command, which is commonly used on Linux-based systems to control services.

This plugin is particularly useful for managing important services such as web servers (e.g. nginx, httpd), databases (e.g. mysql, postgresql) and other system daemons within a KOSI package, if the desired service is available on your system.

With the Service plugin, you can:

Start a service to ensure it is running.
Stop a service to terminate its execution.
Restart a service to apply configuration changes.
Check the status of a service to verify its current state.

Keys

Key	Required	Description
`name`	Yes	Specifies the name of the service to be managed.
`state`	Yes	Defines the operation to perform on the service. Supported values: `start`, `stop`, `restart`, `status`.
`sudo`	Optional	If set to `true`, the command will be executed with elevated privileges.
`sudoPassword`	Yes if `sudo` is `true`	Provides the password for sudo authentication.

Examples

Note: The services in the following examples assume that the corresponding services exist in the system.

Example 1 - Start a Service

This example starts the Apache HTTP Server (httpd).

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

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

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

install
{
    service
    (
        name = "httpd";
        state = "start";
        sudo = "true";
        sudoPassword = "securePassword";
    );
}

Example 2 - Stop a Service

This example stops the Apache HTTP Server.

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

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

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

install
{
    service
    (
        name = "httpd";
        state = "stop";
        sudo = "true";
        sudoPassword = "securePassword";
    );
}

Example 3 - Restart a Service

Restarting a service can be useful after configuration changes.

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

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

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

install
{
    service
    (
        name = "httpd";
        state = "restart";
        sudo = "true";
        sudoPassword = "securePassword";
    );
}

Example 4 - Check Service Status

This command checks whether the httpd service is currently running.

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

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

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

install
{
    service
    (
        name = "httpd";
        state = "status";
        sudo = "true";
        sudoPassword = "securePassword";
    );
}

Example 5 - Using Service Plugin with other plugins

Using service with the osCheck, if and print plugins

This example shows the interaction of several plugins. In this example, we use the service plugin together with the osCheck, if and print plugins to check whether it is the correct operating system and to output a specific message and execute a corresponding operation with the service plugin:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-service-oscheck-if-print";
description = "Example using service with oscheck and if and print";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

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

install
{
    osCheck
    (
        getOSVar = "os";
        getOSVersionVar = "version";
    );

    if (condition = "$os$ = 'Red Hat Enterprise Linux'") then
    {
        print(message = "Performing stop service for RHEL 8..");

        service
        (
            name = "rhelService";
            state = "stop";
            sudo = "true";
            sudoPassword = "securePassword";
        );
    }
    else
    {
        print(message = "Other OS recognized instead of RHEL 8, performing stop for an alternative service..");
      
        service
        (
            name = "differentService";
            state = "stop";
            sudo = "true";
            sudoPassword = "securePassword";
        );
    }
}

Expected Behavior

If os is Red Hat Enterprise Linux:

2025-02-26 15:18:28 Info:      Performing stop service for RHEL 8..

The rhelService service has been stopped.

Otherwise:

2025-02-26 15:18:28 Info:      Other OS recognized instead of RHEL 8, performing stop for an alternative service..

The differentService service has been stopped.

Kosi: set-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Set Version 2.2.0

Summary

The ‘set’ Plugin allows you to set variables inside a KOSI process to get access for other plugin calls.

Keys

Key		Description
variable	Mandatory	The variable name for accessing the variable.
value	Mandatory	The value of the variable.

Syntax to access plugin variables inside KOSI:

{{ vars.myvariable }}

values.yaml

usecase: "user" #or "kubeops"

Example Package

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

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

install
{
    set
    (
        variable = "kubeopsvariable";
        value = "Hello KubeOps";
    );

    set
    (
        variable = "uservariable";
        value = "Hello User, you use the set-plugin";
    );

    set
    (
        variable = "ifcondition";
        value = "{{ values.usecase }}";
    );

    if(condition = "$vars.ifcondition$ = 'user'";) then
    {
        print(message = "Your ifcondition-variable: {{ vars.ifcondition }}");
        print(message = "Your usecase-values: {{ values.usecase }}");
        print(message = "Your user-variable: {{ vars.uservariable}}");
    } else
    {
        print(message = "Your ifcondition-variable: {{ vars.ifcondition }}");
        print(message = "Your usecase-values: {{ values.usecase }}");
        print(message = "Your kubeops-variable:{{ vars.kubeopsvariable }}");
    }
    print(message = "This will always print.");
}

Result

[root@localhost]# kosi install -p package.tgz -f values.yaml
2025-03-10 11:30:56 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2025-03-10 11:30:57 Info:      Your ifcondition-variable: user
2025-03-10 11:30:57 Info:      Your usecase-values: user
2025-03-10 11:30:57 Info:      Your user-variable: Hello User, you use the set-plugin
2025-03-10 11:30:57 Info:      This will always print.
2025-03-10 11:30:57 Info:      Installation successful.

or with usecase => kubeops

[root@localhost]# kosi install -p package.tgz -f values.yaml
2025-03-10 11:22:04 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2025-03-10 11:22:05 Info:      Your ifcondition-variable: kubeops
2025-03-10 11:22:05 Info:      Your usecase-values: kubeops
2025-03-10 11:22:05 Info:      Your kubeops-variable:Hello KubeOps
2025-03-10 11:22:05 Info:      This will always print.
2025-03-10 11:22:05 Info:      Installation successful.

Kosi: sh-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin sh Version 2.2.0

Summary

The sh plugin is used to execute shell commands. It allows users to define commands that will be executed in a shell environment during the execution of a kosi package. This plugin is useful for automating system administration tasks, configuring environments, or executing necessary shell operations within a controlled setup.

It supports executing single commands as well as multiple commands separated by a semicolon (;). Additionally, the plugin provides an option to execute commands with elevated privileges (sudo).

Keys

Key		Description
command	Mandatory	Contains a string representing a shell command or a sequence of commands to be executed. Multiple commands can be specified, separated by a semicolon (`;`).
sudo	Optional	Set to `true` to execute the plugin with sudo privileges.
sudoPassword	Mandatory if you use sudo	Set sudo password. Only required, if the key `sudo` is set to `true`.

Examples

Example 1 - Execute a single command

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

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

install
{
    sh(command = "echo hello world");
}

Example 2 - Execute multiple commands

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

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

install
{
    sh(command = "echo foo; echo bar");
}

Example 3 - Execute command with sudo

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

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

install 
{
    sh(
        command = "reboot now";
        sudo = "true";
        sudoPassword = "password";
    );
}

Example 4 - Using `sh` with the `set` and `if` plugins

This example shows the interaction of several plug-ins. In this example, we use the sh plugin together with the set and if plugins to check a condition (which is set before) before executing a shell command:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-shell-if";
description = "Example using sh with set and if";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

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

install
{
    set
    (
        variable = "myVar";
        value = "Hello";
    );

    if (condition = "$vars.myVar$ = 'Hello'") then
    {
        sh(command = "echo Variable is 'Hello'");
    }
    else
    {
        sh(command = "echo Variable is not 'Hello'");
    }
}

Expected Output

If myVar is Hello:

2025-02-26 15:18:28 Info:      Variable is 'Hello'

If myVar is not Hello:

2025-02-26 15:18:28 Info:      Variable is not 'Hello'

Kosi: sudo-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin sudo Version 2.2.0

Summary

The sudo plugin allows executing commands with elevated (sudo) rights within a KOSI package. This is necessary for operations that require administrative privileges, such as modifying system files or managing users.

The sudo plugin wraps other plugin calls that need elevated permissions. When using sudo, commands inside its block are executed with superuser privileges.

The sudo plugin requires a sudo password unless NOPASSWD is configured for the executing user. The NOPASSWD option can be set in the /etc/sudoers file to allow password-less sudo execution for specific users or commands.

Keys

Key		Description
password	Mandatory if `NOPASSWD` is not set	Set sudo password.

Examples

Example 1

The following example demonstrates how to use the sudo plugin to create a new user with administrative privileges:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
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 the sudo plugin. ---");

    sudo(password = "myPassword")
    {
        bash(command = "echo The password is correct, the new user is now created!");
        cmd(command = "useradd newuser");
    }

    cmd(command = "echo --- End. ---");
}

Where to Set `NOPASSWD`

The NOPASSWD option can be set in the /etc/sudoers file or in a separate file under /etc/sudoers.d/. To allow a user to run sudo commands without entering a password, add the following line:

username ALL=(ALL) NOPASSWD: ALL

Replace username with the actual user’s name.

Supported Plugins

The sudo plugin can be used with the following plugins that often require elevated privileges:

Kosi: template-2.2.0

Mon, 01 Jan 0001 00:00:00 +0000

KOSI Plugin Template Version 2.2.0

Summary

The KOSI Template Plugin allows users to process and generate configuration files based on predefined templates. By specifying a template file (tmpl) and a target file (target), the plugin dynamically replaces placeholders with actual values retrieved from various sources, such as the KOSI package itself or user-defined values.

This plugin is particularly useful when you need to create configuration files dynamically by integrating predefined values into a structured template. It enables flexibility and automation in generating configuration files for different environments.

How It Works

The template file (tmpl) consists of placeholders enclosed in double curly braces ({{ }}). These placeholders reference values from configuration files such as the KOSI package itself or user-defined .yaml files. When the plugin processes the template, it replaces these placeholders with the actual values and saves the result in the specified target file.

The plugin utilizes the Scriban templating engine to replace placeholders. Try Scriban Online.

You can use dot notation to navigate through the YAML structure:

The root keyword for the KOSI package itself is package.
The root keyword for user-defined YAML files is values.

Keys

Key	Mandatory	Description
`tmpl`	Yes	Specifies the template file (YAML format) that contains placeholders.
`target`	Yes	Defines the output file where the processed template will be saved. This can be a relative or absolute path.

Examples

Example 1 - Basic Usage

This example demonstrates how to use the template plugin to generate a configuration file from a template.

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

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

install
{
    template
    (
        tmpl = "template.yaml";
        target = "result.yaml";
    );
}

Example 2 - Using the Template Engine

Consider the following template.yaml file:

api: {{package.apiversion}}
package:
  name: {{package.name}}
  version: {{package.version}}
  input_file: {{package.includes.files.input}}
  container_registry: {{package.includes.containers.example.registry}}
values:
  primary_ip: {{values.ipNormal}}
  first_listed_ip: {{values.IPList[0]}}

Corresponding package.kosi Example:

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

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

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

install
{
    template
    (
        tmpl = "template.yaml";
        target = "/user/output/result.yaml";
    );
}

Corresponding values.yaml Example:

IPList:
  - "127.0.0.1"
  - "192.128.16.1"
  - "192.128.18.14"
ipNormal: "12.10.45.23"

After we have built the KOSI package with kosi build, we install the created package and include the values.yaml by executing kosi install -p package.tgz -f values.yaml.

Expected Output in `result.yaml`

After executing the KOSI install command, result.yaml would contain:

api: kubernative/kubeops/sina/user/v4
package:
  name: kosi-example-packagev3
  version: 0.1.0
  input_file: template.yaml
  container_registry: docker.io
values:
  primary_ip: 12.10.45.23
  first_listed_ip: 127.0.0.1

As already explained in the summary, you can use dot notation to navigate through the YAML structure.

To access values from the KOSI package itself (package.kosi):

name: {{package.name}}

To reference a deeply nested value, use dot notation:

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

The input-element in the KOSI package is accessible with package.includes.files.input, because the input element is nested inside the files tree, which itself is part of the includes hierarchy.

Kosi: writeplugin

Mon, 01 Jan 0001 00:00:00 +0000

how to write a plugin

A plugin is a task a task that can be executed in a kosi package. The Plugins are selsected in the tasks tree in the batch.yaml. The plugin gets passed a parameter tree, which can be read in the plugin.

classes in the plugin

There are two important classes: the version class and the info class. An overview of the versions of the plugins is in the info class. The class must inherit from the iplugininfo class. a forwarding to the individual version classes is important: Also there is a function which returns a list with all versions of the plugin.

The Logic of the plugin lies in run method in the version class.
The run method gets a sandbox and the parameter-tree passed.

public void Run(ISandbox sandbox, ITree parameter) {

the lint function of the version class checks the tree for the plugin if the parameter-tree is correct. A function for returning the name and version of The plugin is also obligatory.

Sandbox is a class which contains data for the plugin. An example would be the storage space of the package.yaml, which defines the kosi package. You can also set variables in the sandbox.

ITree config = sandbox.GetVariable("config");

You can also get an instance of the logger from the sandbox. with the getlogginmanager() method you can access the logger.

sandbox.GetLoggingManager().Debug1("plugin-template", $"run template plugin");

The method after get logging menager determines the logging level. There are four logging levels:

info
debug1
debug2
debug3

The first parameter determines the channel. It is recommended that you name it after your plugin. The message for the logging is the second parameter.

The sandbox can create a instance of a fio file, which can be written on hard disk. This fio file has a Tree, which can be modified with the fio-tool.

IFile templateYaml = sandbox.NewFio();

the element of the tree can be accessed with the fio-tool. Fio is included in the toolchain.dll. These Tree have elements and/or subtrees. A element in Fio has only one key and an associated value.

string kosiFileName = (string)templateyaml.GetElement($"apiversion").Value;

when you want to access a subtree, you can use a point structure.

string kosiFileName = (string)templateyaml.GetElement($"import.files.{fileElement}").Value;

In contrast, a subtree can have multiple elements with associated values. “Value” is the keyword for using the value of the element-key.

ITree mergeduservalues = config.GetSubTree("mergedFioFiles");

You have to possibility to use other plugins, the sandbox has also the runPLugin() function. In this example we use the print plugin with a tree as a parameter for the print plugin. The tree have to be the same as the tree you use within the run tree in the batch.yaml for the plugin.

sandbox.RunPlugin("print", parameter);

the parameter-tree can be created with fio. the name of the plguin does not have to be within the parameter-tree. Fio has the option to set parameters, so for example the creation of the parameter-tree for the print-plugin can be like that:

Itree parameter = new Tree();
parameter.setElement("message","now the print plugin can be run!");
sandbox.RunPlugin("print", parameter);

Kosi: How to manually push images to your KubeOps-Registry project space

Mon, 01 Jan 0001 00:00:00 +0000

How to manually push images to your KubeOps-Registry project space

To manually push container images into your KubeOps-Registry project space, you need to use your Harbor CLI secret for authentication when using podman.

How to get your CLI secret

Click on your username and select User Profile.
On the User Profile page, you can copy or change your CLI secret if needed.

Now you can push your image using the CLI secret:

podman login registry.kubeops.net -u <username> -p <CLI_secret>

Note: Replace <username> with your KubeOps username and <CLI_secret> with your actual CLI secret.

How to push your image

After logging in, tag your image with the registry path of your KubeOps-Registry project space:

Important: In most cases, you do not need to push images manually. You can specify a local or remote image directly in your KOSI package, for example docker.io/library/nginx:latest or my-app:v1.12.1. When KOSI pushes the package, it rewrites the image reference in the package to the pushed registry image under registry.kubeops.net. After that, you can use the rewritten and pushed image in your KOSI package.

Note: Replace <local_image>, <project>, <image> and <tag> with your actual values.

podman tag <local_image>:<tag> registry.kubeops.net/<project>/<image>:<tag>

Example:

podman tag my-app:v1.12.1 registry.kubeops.net/my-project/my-app:v1.12.1

Then push the image to your project space:

podman push registry.kubeops.net/<project>/<image>:<tag>

Example:

podman push registry.kubeops.net/my-project/my-app:v1.12.1

Kosi: KOSI

Mon, 01 Jan 0001 00:00:00 +0000

Try KOSI

Follow quickstart guides to learn how to securely deploy packages to clusters, nodes and other machines.

Kosi: About Kosi

Mon, 01 Jan 0001 00:00:00 +0000

What is KOSI

KOSI is a professional software installation tool tailored for Kubernetes clusters. Its primary function is to streamline the process of defining, installing, and managing self-contained packages within Kubernetes environments. These packages are versatile and can be adapted to suit various requirements and configurations.

By packaging applications and their associated Kubernetes resources into KOSI packages, developers can easily share and distribute their applications. Users can then use KOSI to install, upgrade, and manage these packages, making it easier to deploy complex applications in Kubernetes environments.

KOSI uses a quick-to-learn command line interface (CLI).

Why use KOSI?

KOSI, drawing inspiration from Helm’s user-friendly design, empowers software developers to craft comprehensive packages. These packages can include multiple artifacts and essential dependencies, consolidated into a single KOSI package.

When deploying software into your environments, you simply retrieve this package from the KubeOps hub. KOSI efficiently manages all relevant dependencies, ensuring smooth installation processes.

This makes the process of installing software with KOSI into your cluster simplified, secure and flawless.

Highlights

Supports Images and Artifacts in one Package
OSI stands out among other package managers because of its distinctive capability to package container images alongside other artifacts within the same package.
Self-Contained Packages
KOSI’s ability to generate a single, self-contained package reduces the risk of human errors that can result from manual steps during software deployment.
Customizable Plugins
KOSI offers pre-built plugins that facilitate the execution of several common tasks directly through KOSI packages. Additionally, you can easily access more plugins via our KubeOps hub.
Scalable and Secure
KOSI supports software distribution in complex environments, including those where outgoing proxies restrict broad internet access.
Integration and Support of other Tools KOSI seamlessly integrates with Helm, Podman and Docker, ensuring compatibility across various containerized environments. This compatibility allows users to leverage the strengths of Helms package management capabilities and Dockers containerization technology within the KOSI ecosystem. By supporting these widely used tools, KOSI enhances flexibility and efficiency in deploying and managing software across diverse infrastructure setups.

Click here to download and get started with KOSI now.

Kosi: Fileformats in KOSI

Mon, 01 Jan 0001 00:00:00 +0000

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.

Kosi: How to install KOSI as a user

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to install KOSI as a user. KOSI can only be downloaded from our official website.

Prerequisites

Operating System: A machine running RHEL 9.
Helm: Helm Must be installed on your machine. Refer to the Helm Official Documentation.
Podman:
KOSI requires Podman to be installed on your machine.

Note If you are a non-root user, ensure that the number of user namespaces (max_user_namespaces) is configured correctly. For more details, refer to this GitHub tutorial.

Install on RHEL9:
```
sudo dnf install podman
```
⚠ Caution KOSI supports only secure registries. If you use an insecure registry, you must explicitly add it as an insecure registry in registries.conf (/etc/containers/registries.conf).

Installation Steps

Download the KOSI RPM:
- Log in to your KubeOps account.
- Download your desired version of the KOSI RPM from the official download page.
Install the KOSI RPM on your admin node:
Run the following commands:
```
echo 'export KUBEOPSROOT=/home/<user>/kubeops' >> $HOME/.bashrc
source $HOME/.bashrc
sudo dnf install <path_to_rpm>/<kosi_file_name>.rpm
```
Note
- Replace <path_to_rpm> with the directory path where the file is located.
- Replace <kosi_file_name> with the exact RPM file name (including the .rpm extension).

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable defines the location of the KOSI plugins, deployment.yaml, and config.yaml.
If you change the KUBEOPSROOT variable after installation, you must manually copy the updated deployment.yaml, config.yaml, and plugins.

Run the following commands to update them:

echo 'export KUBEOPSROOT=/home/<user>/kubeops' >> $HOME/.bashrc
source $HOME/.bashrc
cp -r /var/kubeops/kosi/config.yaml $KUBEOPSROOT/kosi/config.yaml
cp -r /var/kubeops/kosi/deployment.yaml $KUBEOPSROOT/kosi/deployment.yaml
cp -r /var/kubeops/plugins $KUBEOPSROOT/

For a clean installation, it is not necessary to move the deployment.yaml.

Check Installation

To verify that KOSI is installed correctly on your machine, run:

kosi version

A successful installation will display version details, it will look similar like this:

2024-08-07 13:49:00 Info:      KOSI version: 2.15.0.0_XXXXXXXXXX
2024-08-07 13:49:00 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).
2024-08-07 13:49:00 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2023

Kosi: Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

Kosi: About KOSI Licences

Mon, 01 Jan 0001 00:00:00 +0000

For KOSI, two licence types are available: KOSI Essential and KOSI Enterprise.

When you create an account, you receive a free 30 day trial version of our licences.

Functions	KOSI-Essential	KOSI-Enterprise
Push Packages	✓	✓
Pull Packages	✓	✓
List Packages	✓	✓
Install Packages	✓	✓
Update Packages	✓	✓
Delete Packages	✓	✓
Remove Packages	✓	✓
Encrypt Value files	✓	✓
Lint Packages	✓	✓
Use private registry space	✓	✓
Use private hub	✓	✓
Build *basic packages	✓	✓
Build **advanced packages	✗	✓
Price	FREE	Contact Sales

*Basic packages: The package build process is limited to the basic plugins. Click here

Advanced packages: The package build process has full access to all plugins. Click here**

Kosi: How to use Variables in KOSI Packages

Mon, 01 Jan 0001 00:00:00 +0000

KOSI plugins can produce internal variables during execution, which you can reference in subsequent steps of your package (for example in conditions or output messages). The following guide explains how to use variables set by various KOSI plugins and how to consume them using e.g. the if and fprint plugins (which allow conditional logic and formatted output, respectively).

Plugins that set Variables

Several plugins store their results in named variables. These include:

Firewall / Firewalld / IPTables – All three firewall plugins support a key like getFirewallStatus = "<var>". For example:
```
firewall
(
    type = "firewalld";
    action = "enable";
    getFirewallStatus = "status";
);
```
This stores the firewall status ("running" or "not running") into the variable status. You can then reference this status variable in later steps.
Hostname – The hostname plugin can get the current hostname into a variable or set a new hostname from a variable. Its keys are: get = "<var>" to save the current hostname and setVar = "<var>" to restore from a saved variable. For example:
```
hostname(get = "oldHostname");
```
This saves the machine’s current hostname into the variable oldHostname.
kubeadm – The kubeadm plugin runs kubeadm commands. Its outputVar = "<var>" option captures the command’s output into a variable. For example:
```
kubeadm
(
    operation = "version";
    kubeadmVersion = "version";
    outputVar = "kubeadmVersionOutput";
);
```
This saves the output of kubeadm version into the variable kubeadmVersionOutput.
kubectl – The kubectl plugin executes kubectl commands. Its outputVar = "<var>" captures the command output. For example:
```
kubectl
(
    operation = "get";
    resource = "pods";
    flags = "-n kube-system -o wide";
    outputVar = "podsOutput";
    outputFile = "/root/output.txt";
);
```
This saves the kubectl get pods output into podsOutput. You can then use podsOutput in subsequent steps.
osCheck – The osCheck plugin detects the OS name and version. It has two keys: getOSVar="<var>" for the OS name and getOSVersionVar="<var>" for the OS version. For example:
```
osCheck(getOSVar="osName"; getOSVersionVar="osVersion");
```
This stores the OS name in osName and the version in osVersion.
set – The set plugin lets you define arbitrary variables. Use variable="<name>"; value="<something>" to create a variable. For example:
```
set(variable = "envType"; value = "production");
```
This creates a variable named envType with value "production". Variables set by the set plugin are accessed via vars.<variableName>.

Referencing Plugin Variables

KOSI provides two main ways to use these variables:

Conditional checks with the if plugin: The if plugin evaluates an expression and branches accordingly. In the condition string, you can include plugin variables by name, enclosed in $...$ . For example:
```
if(condition = "$oldHostname$ = 'myHost'") then {
    # ... do something ...
}
```
For variables set via the set plugin, access them as $vars.<name>$ , e.g. $vars.envType$ .

Formatted output with the fprint plugin: The fprint plugin prints a message and can include plugin-variable values. You provide a list of variable names in its variables key and placeholders {0}, {1}, etc. in the message. For example:

fprint
(
    message = "Firewall status is {0}";
    variables = "['status']";
);

For variables from the set plugin:

set(variable="userName"; value="Alice");
set(variable="userIP"; value="10.0.0.1");
fprint
(
    message = "User {0} has IP {1}";
    variables = "['vars.userName','vars.userIP']";
);

Example Workflow

Set or retrieve a variable:

hostname(get = "myHostname");
osCheck(getOSVar = "osName"; getOSVersionVar = "osVersion");

Conditionally act on it:

 if(condition = "$myHostname$ = 'expectedHost'") then {
     fprint
     (
         message = "Got expected hostname: {0}";
         variables = "['myHostname']";
     );
 }

Output or log values:

fprint
(
    message = "Running on {0} version {1}";
    variables = "['osName','osVersion']";
);

Plugins mentioned in this How to Guide that set or use variables

Kosi: KOSI Language Reference

Mon, 01 Jan 0001 00:00:00 +0000

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

Kosi: Full Documentation KOSI-2.15.x

Mon, 01 Jan 0001 00:00:00 +0000

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_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

Kosi: Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Kosi: Installation Guide

Mon, 01 Jan 0001 00:00:00 +0000

In this quickstart you will learn about:

KOSI system requirements
how to install KOSI
how to use the official KubeOps Website to download KOSI
how to install required software

KOSI seamlessly integrates with other package management software such as Helm and Podman. To ensure compatibility across different containerized environments, KOSI requires the installation of this software.

After the installation, KOSI is available as command line interface.

Note We recommend to install KOSI onto the admin machine of a cluster.

Prerequisites

To get the most out of this guide, the following requirements should be met:

basic understanding of Linux environments, bash / shell
sudo privileges (root) to install packages

Step 1 - System Requirements

Make sure you have prepared the listed requirements before installing KOSI.

KOSI is designed to work with the latest versions of the following operating systems:

OS	Diskspace
Red Hat Enterprise Linux 9.6 and 9.7	500 MB
Ubuntu 24.04.02	500 MB
OpenSUSE MicroOS 20260630 (rolling release)	500 MB

⚠ Warning Only RHEL 9.6 and 9.7 are supported. Make sure the OS version is pinned to prevent accidental updates to an unsupported version, as this may break the cluster.

Important

By default Red Hat Enterprise Linux restricts package management such as installing or updating. Before installing any software, you may need to register and subscribe with the Red Hat Customer Portal.

To register and subscribe, run the command subscription-manager register.

⚠ Warning Only RHEL 9.6 and 9.7 are supported. Make sure the OS version is pinned to prevent accidental updates to an unsupported version, as this may break the cluster.

Step 2 - Include Package Repo

To easily install the kosi package you should add the kubeops package repo to your operating system’s package manager.

wget https://packagerepo.kubeops.net/pgp-key.public
cat pgp-key.public | sudo gpg --dearmor -o /usr/share/keyrings/kubeops.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/kubeops.gpg] https://packagerepo.kubeops.net/deb stable main' | sudo tee /etc/apt/sources.list.d/kubeops.list
sudo apt update

sudo dnf config-manager --add-repo https://packagerepo.kubeops.net/rpm/kubeops.repo

# Only the standard OpenSUSE Microos repos in /etc/zypp/repos.d are used
# You have to download the KOSI package manually

Step 3 - Install KOSI

There are two ways to install kosi.

a) quick via the package repo of your operating system’s package manager.

sudo apt update
sudo apt install -y kosi=2.14*

sudo dnf install -y --disableexcludes=kubeops-repo kosi-2.14.0.0-0

# KOSI installation via package repo is not supported
# Please install it manually

b) manual download the kosi package from the official KubeOps Website and install it.

Downloading KOSI

Login into your KubeOps account. If you don‘t have an account, you can create one by following the instructions for Create a KOSI account (with SSO).

Download your desired version of the KOSI package file (.rpm or .deb) from the official download page.

# download kosi deb manually and install with
sudo dpkg --install kosi_2.14.0.0-1_amd64.deb

# download kosi rpm manually and install with
sudo rpm --install kosi-2.14.0.0-0.x86_64.rpm

# Download KOSI rpm manually and install with
sudo transactional-update pkg install --no-confirm --allow-unsigned-rpm --force kosi-2.15.0.4_Beta0-0.x86_64.rpm

# Need reboot after transactional update!
sudo reboot now 

# Copy plugins and KOSI config from last snapshot
sudo mkdir -p /var/kubeops/plugins
sudo cp -r /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/plugins/ /var/kubeops/
sudo cp -r /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/kosi/ /var/kubeops/

Step 4 - Set the KUBEOPSROOT env var

Set KUBEOPSROOT and XDG_RUNTIME_DIR in ~/.bashrc

⚠ Warning Adapt /home/<yourUser>/kubeops with your value before usage.

Remove existing KUBEOPSROOT and XDG_RUNTIME_DIR entries before setting your values.

sed -i '/^export KUBEOPSROOT=/d' ~/.bashrc
sed -i '/^export XDG_RUNTIME_DIR=/d' ~/.bashrc

Then add your values:

# file ~/.bashrc
# Add these values to the end of your ~/.bashrc file
export KUBEOPSROOT=/home/<yourUser>/kubeops
export XDG_RUNTIME_DIR=$KUBEOPSROOT

Source .bashrc to apply the values

source ~/.bashrc
echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

Both commands should return your KUBEOPSROOT path, for example:

/home/<yourUser>/kubeops
/home/<yourUser>/kubeops

Step 5 - Adjust KOSI Configuration

This creates a kubeops directory in your home directory and transfers all necessary files, e.g., the kosi-config and the plugins, to it.

mkdir ~/kubeops
cd ~/kubeops
cp -R /var/kubeops/kosi/ .
cp -R /var/kubeops/plugins/ .

The config.yaml is in your KUBEOPSROOT-path (typically in ~/kubeops/kosi)

Set hub in your kosi config to hub: https://dispatcher.kubeops.net/v4/dispatcher/

⚠ Warning This file entry has to be adapted to your values before usage.

Set the “plugins”-entry in your kosi config to plugins: /home/<yourUser>/kubeops/plugins, where is changed to your username

⚠ Warning This file has to be adapted to your values before usage.

# file $KUBEOPSROOT/kosi/config.yaml
apiversion: kubernative/sina/config/v3

spec:
  hub: https://dispatcher.kubeops.net/v4/dispatcher/ # <-- set hub url
  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/
  logging: info
  housekeeping: false
  proxy: false
  checkforupdates: false

Step 6 - Install KOSI enterprise plugins

kosi install --hub kosi-enterprise kosi/enterprise-plugins:2.0.0

Step 7 - Install Podman

To ensure compatibility across different containerized environments, KOSI requires the installation of Podman (latest version).

Install Podman using the inbuilt package manager.

sudo apt update
sudo apt install -y podman

sudo dnf install -y podman

# Podman is already installed by default

Step 8 - Install Helm

Many KOSI packages use helm. Therefore, it is recommended to install helm.

Install Helm using the KubeOps package repo.

sudo apt update
sudo apt install -y helm

sudo dnf install -y helm

sudo transactional-update pkg install --no-confirm helm
sudo reboot now

Verify your Installation

To verify the installation of KOSI on your system, use the command kosi version.

kosi version

The output displays the KOSI version along with relevant information. It confirms the successful installation of KOSI.

2026-01-23 16:09:55 Info:      KOSI version: 2.14.0.0
2026-01-23 16:09:55 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-01-23 16:09:55 Info:      Latest KOSI-lanugage-version is: 1.0.0
2026-01-23 16:09:55 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 16:09:55 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Check if you can log in with the command kosi login.

kosi login -u <yourUser>

The output confirms that you are successfully loged in.

2026-01-23 16:11:40 Info:      KOSI version: 2.14.0.0
2026-01-23 16:11:47 Info:      Login Succeeded to Hub.
2026-01-23 16:11:48 Info:      The login to registry was successful. You are now logged in as kubeops and can use the public and private registry.

Kosi: Full Documentation KOSI-2.14.x

Mon, 01 Jan 0001 00:00:00 +0000

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

Kosi: How to install and access the Plugins from the Hub

Mon, 01 Jan 0001 00:00:00 +0000

How to access the Plugins

Note: Be sure you have a supported KOSI version 2.12.X or higher.

All plugins are available as KOSI packages in the KubeOpsHub. Our plugins are grouped into several KOSI packages. To view the available packages, use the command:

KOSI Basic Plugins Version 1.6.X

kosi search --hub kosi-basic

2024-08-07 13:47:02 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name          | Version     | Description        | Install                        |
|------|---------------|-------------|--------------------|--------------------------------|
| kosi | basic-plugins | 1.5.0_beta0 | KOSI Basic Plugins | kosi/basic-plugins:1.5.0_beta0 |
| kosi | basic-plugins | 1.5.0       | KOSI Basic Plugins | kosi/basic-plugins:1.5.0       |
| kosi | basic-plugins | 1.4.0       | KOSI Basic Plugins | kosi/basic-plugins:1.4.0       |
| kosi | basic-plugins | 1.6.0_Beta0 | KOSI Basic Plugins | kosi/basic-plugins:1.6.0_Beta0 |
| kosi | basic-plugins | 1.4.2       | KOSI Basic Plugins | kosi/basic-plugins:1.4.2       |
| kosi | basic-plugins | 1.4.1       | KOSI Basic Plugins | kosi/basic-plugins:1.4.1       |

This package contains the following plugins:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0

KOSI Professional Plugins Version 1.6.X

kosi search --hub kosi-professional

2024-08-07 13:47:36 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name                 | Version     | Description               | Install                               |
|------|----------------------|-------------|---------------------------|---------------------------------------|
| kosi | professional-plugins | 1.5.0_beta0 | KOSI Professional Plugins | kosi/professional-plugins:1.5.0_beta0 |
| kosi | professional-plugins | 1.4.0       | KOSI Professional Plugins | kosi/professional-plugins:1.4.0       |
| kosi | professional-plugins | 1.5.0       | KOSI Professional Plugins | kosi/professional-plugins:1.5.0       |
| kosi | professional-plugins | 1.4.2       | KOSI Professional Plugins | kosi/professional-plugins:1.4.2       |
| kosi | professional-plugins | 1.4.1       | KOSI Professional Plugins | kosi/professional-plugins:1.4.1       |
| kosi | professional-plugins | 1.6.0_Beta0 | KOSI Professional Plugins | kosi/professional-plugins:1.6.0_Beta0 |

This are the plugins which the packages contains:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0
kubectl	1.6.0
bash	1.6.0
cmd	1.6.0
sh	1.6.0
editfile	1.6.0
fprint	1.6.0
if	1.6.0
loop	1.6.0
kosi	2.11.0.10
merge	1.6.0
exit	1.6.0
setfact	1.6.0

KOSI Enterprise Plugins Version 1.6.X

kosi search --hub kosi-enterprise

2024-08-07 13:47:59 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name               | Version     | Description                  | Install                             |
|------|--------------------|-------------|------------------------------|-------------------------------------|
| kosi | enterprise-plugins | 1.5.0       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.5.0       |
| kosi | piaoperator        | 1.4.0       | Pia Operator Install Package | kosi/piaoperator:1.4.0              |
| kosi | enterprise-plugins | 1.4.2       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.2       |
| kosi | enterprise-plugins | 1.5.0_beta0 | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.5.0_beta0 |
| kosi | enterprise-plugins | 1.4.0       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.0       |
| kosi | enterprise-plugins | 1.6.0_Beta0 | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.6.0_Beta0 |
| kosi | enterprise-plugins | 1.4.1       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.1       |

This package contains the following plugins:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0
kubectl	1.6.0
bash	1.6.0
cmd	1.6.0
sh	1.6.0
editfile	1.6.0
fprint	1.6.0
if	1.6.0
loop	1.6.0
kosi	2.11.0.10
merge	1.6.0
exit	1.6.0
setfact	1.6.0
auditlog	1.6.0
chmod	1.6.0
copy	1.6.0
firewall	1.6.0
firewallD	1.6.0
containerd	1.6.0
containerruntime	1.6.0
hostname	1.6.0
iptables	1.6.0
kubeadm	1.6.0
osCheck	1.6.0
packagemanager	1.6.0
pia	1.6.0
service	1.6.0
sudo	1.6.0

How to install the Plugins

After installing the plugins with our KOSI install command, the plugins are automatically placed in the associated directory ($KUBEOPSROOT/plugins) and can be used directly.

kosi install --hub=<pluginhub> user/packagename:version

Example: The package enterprise-plugins of the user kosi with the version 1.6.0_Beta0 is to be installed from the kosi-enterprise hub.

kosi install --hub=kosi-enterprise kosi/enterprise-plugins:1.6.0_Beta0

Note: You can also use the Install Tab from the output to help with installation.

Kosi: Full Documentation KOSI-2.13.x

Mon, 01 Jan 0001 00:00:00 +0000

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

Kosi: Register an Account

Mon, 01 Jan 0001 00:00:00 +0000

How to register an Account

You can register a KubeOps account either via the website or directly via the KubeOps-Registry.

Register account via the Website

You can create an account on our website.

This will redirect you to our login page:

At the bottom of the form, you will find the REGISTRATION button. Click it to open the registration form, enter your details, and create your account.

Activate your account to use KOSI

After successful registration:

You must first log in once to the KubeOps-Registry.
Then log in once with KOSI to activate your account for KOSI usage. After that, you can use KOSI as normal.

Kosi: Creating a Basic KOSI-Package and Deployment

Mon, 01 Jan 0001 00:00:00 +0000

In this quickstart you will learn about:

how to get to know KOSI-packages
add repositories and download helm charts
create a KOSI-package
configure a KOSI-package to deploy a demo WordPress page
optional: install and deploy the KOSI-package to a cluster

Notice

The intent of this guide is to setup a demo WordPress page on your cluster or your machine.

We do not recommend this guide for production environments.

Important To get the most out of this guide, we recommend to create your first demo KOSI-package on the admin machine of a basic cluster. For a helpful guide, see Set up a Basic cluster using kubeopsctl.

Prerequisites

To get the most out of this guide, the following requirements should be met:

KOSI is installed, see KOSI Installation Guide
basic understanding of Kubernetes, network clusters and tools such as Helm or Podman
basic understanding of Linux environments, bash / shell
administrator privileges (root) are granted

Step 1 - Create a KOSI-Package

After the installation, KOSI is available as command line interface.

Create a new folder and use the command kosi create to create a default KOSI-package with pre-built files.

mkdir ~/kosi-demo
cd ~/kosi-demo

kosi create

Example output:

2024-08-07 13:49:00 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2024-08-07 13:49:00 Info:      Write package.kosi to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write template.yaml to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write logo.png to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write docs.tgz to /root/kosi-demo

File	Description
`package.kosi`	Contains the „logic“ of the package.
`template.yml`	A template file for configurations and the templating engine.
`logo.png`	A logo for the package. replace this with your desired logo (png format).
`docs.tgz`	Contains your documentaion of your package.

Step 2 - Understand the Package Logic

The package.kosi file contains the „logic“ of the package. This file uses the kosi format which itself uses the highly expressive KOSI Language.

Among other things the package.kosi file defines:

a preambel for meta data and descriptions
a files section to - manages files, such as templates, to be included and target files
a set of commands - for example „install“ or „upgrade“ which work as scripts within the kosi file

Templates make it possible to use variantes for your packages. For example, you want to reuse a package for different environments. Templates also allow to parse additional „value files“ as command line arguments.

Advanced templating makes it possible to split one large value files into smaller ones. In this case we use some of the defaultvalues but all values will be transfered.

Step 3 - Modify the Template File

For the transfer of values into a package, a valuestemplate.yaml file is needed.

Use an editor to edit the file:

nano ~/kosi-demo/valuestemplate.yaml

To get the most out of this guide, add the following line:

{{values}}

This command will allow to parse the values of the file values.yaml. On installing, the file values.yaml will be automatically transcluded into the cluster. This is helpful to reuse a package for different environments.

Notice the exact same naming of the command with the file.

Step 4 - Add Necessary Repositories and Pull Charts

In this guide we want to create a KOSI-package containing a demo WordPress page. Therefore you need to add the necessary repository via helm. Afterwards you need to pull the latest version of the helm chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm pull bitnami/wordpress --version X.Y.Z

Step 5 - Configure the Package

Configure the package to inlucde the valuestemplate.yaml file. Also add commands for install, update, and delete.

Use an editor to edit the file:

nano ~/kosi-demo/package.kosi

To get the most out of this guide, overwrite the file with the following lines:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "wordpressdemo";
description = "Deploys a wordpress helm chart";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files =
{
    wordpressvaluestemplate= "valuestemplate.yaml";
    chart = "wordpress-X.Y.Z.tgz";
}

containers = 
{
    wordpress =
    [
        "registry-1.docker.io",
        "bitnami/wordpress",
        "latest"
    ];

    mariadb =
    [
        "registry-1.docker.io",
        "bitnami/mariadb",
        "latest"
    ];
}

install
{
    template(tmpl="valuestemplate.yaml";target="wordpressvalues.yaml");
    helm(command="upgrade";tgz="wordpress-X.Y.Z.tgz";values="['wordpressvalues.yaml']";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--create-namespace',' --install']");
}

update
{
    template(tmpl="valuestemplate.yaml";target="wordpressvalues.yaml");
    helm(command="upgrade";tgz="wordpress-X.Y.Z.tgz";values="['wordpressvalues.yaml']";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--create-namespace',' --install']");
}

delete
{
    print(message="delete wordpressdemo helm deployment.");
    helm(command="delete";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--wait']");
    print(message="echo delete wordpressdemo namespace.");
    print(message="kubectl delete namespace wordpressdemo");
}

Step 6 - Create Package Documentation

It is always a good practice to document your packages.

Within your package folder, create a docs folder:

mkdir -p ~/kosi-demo/docs

Create a simple README file (for example markdown format) and write some helpful descriptions. For example:

echo „My first KOSI-package. Contains a demo WordPress page.“ > ~/kosi-demo/docs/README.md

Afterwards you need to compress the whole docs folder using the tgs format.

cd ~/kosi-demo/
tar -cvzf docs.tgz docs/

These docs will be included when building the deployable package file.

Step 7 - Build the Package

When the package.kosi is finished and the documentation is done, the KOSI-package can be built. Navigate to the package folder and simply use the kosi build command.

cd ~/kosi-demo/
kosi build

During the build process, the files package.tgz and package.yaml are created.

Step 8 - Setting Values for the Package

To install the package.tgz, you need the package itself and some values. Among other things, you need to define the nodePorts for http at 30123. This node port will be needed to access and test your WordPress page.

In a previous step we made the package reuseable by using the valuestemplate.yaml file. This files expects a values.yaml file as command line argument.

Use an editor to edit the file:

nano ~/kosi-demo/values.yaml

To get the most out of this guide, add the following lines:

global:
    storageClass: rook-cephfs
service:
    type: NodePort
    nodePorts:
        http: 30123
mariadb:
    enabled: true
    auth:
        rootPassword: topsecretChangeMe
        password: secretChangeMe
    primary:
        persistence:
            enabled: true
            storageClass: rook-cephfs
            accessModes:
                - ReadWriteOnce
persistence:
    enabled: true
    storageClass: rook-cephfs

Optional Step 9 - Installing the Package and Deploy to Cluster

As recommended you need a running Kubernetes cluster to install and deploy your new KOSI-package. You must also be logged in to the Admin machine where you have created the KOSI-package. To set up a cluster easily and conveniently, you can use kubeopsctl (see kubeopsctl documentation).

Navigate to your built KOSI-package. Install the package and pass the prepared values.yaml file as command line argument.

cd ~/kosi-demo
kosi install -p package.tgz -f values.yaml

Important This command works with any running Kubernetes cluster.

Optional Step 10 - Test the WordPress Page

After you deployed the KOSI-package you can test the access via your cluster to the WordPress page.

Depending on your setup you need the following:

the IP or hostname of a master node
tunneling or expossing of ports according to the nodePorts as set in values.yaml

In this guides we set 30123 as nodePort. For example, in your browser navigate to:

http://master1:30123

Kosi: Full Documentation KOSI-2.12.x

Mon, 01 Jan 0001 00:00:00 +0000

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

Kosi: How to update KOSI

Mon, 01 Jan 0001 00:00:00 +0000

This guide shows you how to update KOSI. KOSI can be updated via the package repository, updated automatically, or downloaded from our official website for manual installation.

Prerequisites

Before you begin, make sure the following prerequisites are met:

KOSI is designed to work with the latest versions of the following operating systems:

OS Diskspace

Red Hat Enterprise Linux 9.6 and 9.7 500 MB

Ubuntu 24.04.02 500 MB

OpenSUSE MicroOS 20260630 (rolling release) 500 MB

⚠ Warning Only RHEL 9.6 and 9.7 are supported. Make sure the OS version is pinned to prevent accidental updates to an unsupported version, as this may break the cluster.

Helm must be installed on your machine.

Refer to the Helm Official Documentation for the Installation Guide.

For KOSI versions, you must have Podman installed on your machine.

Note

Before installing Podman, make sure that the number of user namespaces (max_user_namespaces) is specified on your system if you are a non-root user.

For more information, follow this GitHub link.

To install Podman, run the following command:
```
sudo dnf install podman
```
⚠ Caution

KOSI supports only secure registries. If you use an insecure registry, you must explicitly add it as an insecure registry in registries.conf (/etc/containers/registries.conf).

Update Methods

You have multiple options to update KOSI, depending on your system setup and preferences.

Method 1: Automatic Update Check via Config

With KOSI config v3, a new update check feature is introduced. By default, it is disabled (checkforupdates: false).

Important: This feature is not currently supported by OpenSUSE MicroOS.

If you set checkforupdates: true, KOSI will automatically check the kubeops-repo package repository for new versions after every successful KOSI command. If a new version is available, KOSI will prompt you and ask if you want to proceed with the update.

Here is the complete config.yaml:

# file $KUBEOPSROOT/kosi/config.yaml
apiversion: kubernative/sina/config/v3

spec:
  hub: https://dispatcher.kubeops.net/v4/dispatcher/ # <-- set hub url
  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/
  logging: info
  housekeeping: false
  proxy: false
  checkforupdates: false # <-- set to 'true' to enable update checks

Method 2: Update via Package Repository

If you have included the KubeOps package repository in your OS, you can quickly update KOSI using the standard package manager.

sudo apt update
sudo apt install -y kosi

sudo dnf install -y --disableexcludes=kubeops-repo kosi

# KOSI update via package repo is not supported
# Please update it manually

Method 3: Manual Update via Download

Each KOSI release includes an RPM/DEB file for manual installation. To download the package, you must log in to your KubeOps account.

Create a KubeOps Account:
If you haven’t already, create a KubeOps account on the KubeOps website and log in to your account.
Download the Package:
Download your desired version of the KOSI package file (.rpm or .deb) from the official download page:
https://kubeops.net/products/downloads/kosi-downloads-en

Update the KOSI Package:
On your admin node, update KOSI by installing the new package. This will replace the existing version. Run the following command:

# download kosi deb manually and install with
sudo dpkg --install kosi-2.15.0.4_Beta0_amd64.deb # <- Replace the file with the one you downloaded.

# download kosi rpm manually and install with
sudo rpm --install kosi-2.15.0.4_Beta0-0.x86_64.rpm # <- Replace the file with the one you downloaded.

A direct update on OpenSUSE MicroOS is not possible, so you have to repeat the installation steps.

1. Install KOSI

# download kosi rpm manually and install with
sudo transactional-update pkg install --no-confirm --allow-unsigned-rpm --force kosi-2.15.0.4_Beta0-0.x86_64.rpm # <- Replace the file with the one you downloaded.

sudo reboot now # need reboot after transactional update!

sudo mkdir -p /var/kubeops/plugins
sudo cp /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/plugins/*.dll /var/kubeops/plugins/
sudo mkdir -p /var/kubeops/kosi
sudo cp /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/kosi/config.yaml /var/kubeops/kosi/

2. Set the KUBEOPSROOT env var

Set KUBEOPSROOT and XDG_RUNTIME_DIR in ~/.bashrc

Note These are not console commands. The following entries must be added to the end of your ~/.bashrc file.

# file ~/.bashrc
# Append these values to the end of your ~/.bashrc file
export KUBEOPSROOT=/home/<yourUser>/kubeops
export XDG_RUNTIME_DIR=$KUBEOPSROOT

Source .bashrc to apply the values

source ~/.bashrc
echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

As a result you should see your KUBEOPSROOT-path two times.

3. Adjust KOSI Configuration

This creates a kubeops directory in your home directory and transfers all necessary files, e.g., the kosi-config and the plugins, to it.

mkdir ~/kubeops
cd ~/kubeops
cp -R /var/kubeops/kosi/ .
cp -R /var/kubeops/plugins/ .

Important The config.yaml is in your KUBEOPSROOT-path (typically in ~/kubeops/kosi)

Set hub in your kosi config to hub: https://dispatcher.kubeops.net/v4/dispatcher/</a>.
Set the “plugins”-entry in your kosi config to plugins: /home/<yourUser>/kubeops/plugins, where is changed to your username.

Note Replace the file name with the exact file name of the package (including the .rpm or .deb extension).

Verify your Installation

To verify the installation of KOSI on your system, use the command kosi version.

kosi version

The output displays the KOSI version along with relevant information. It confirms the successful installation of KOSI.

2026-07-28 13:57:39 Info:      KOSI version: 2.15.0.4_Beta0_1785144578
2026-07-28 13:57:40 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-07-28 13:57:40 Info:      Latest KOSI-language-version is: 1.0.0
2026-07-28 13:57:40 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-07-28 13:57:40 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Check to see if the environment variables are still set correctly. They may be being overwritten.

echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

Check to see if the config.yaml file is still correct. It may have been overwritten.

cat $KUBEOPSROOT/kosi/config.yaml