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

Return to the regular view of this page.

Plugins

Here you will find a detailed list and description of all our Kosi plugins.

1: auditLog-1.7.0
2: bash-1.7.0
3: chmod-1.7.0
4: cmd-1.7.0
5: containerd-1.7.0
6: Plugin References
7: containerRuntime-1.7.0
8: copy-1.7.0
9: editFile-1.7.0
10: firewall-1.7.0
11: firewallD-1.7.0
12: fprint-1.7.0
13: helm-1.7.0
14: hostname-1.7.0
15: if-1.7.0
16: ipTables-1.7.0
17: kosi-2.12.0
18: kubeadm-1.7.0
19: kubectl-1.7.0
20: loop-1.7.0
21: merge-1.7.0
22: osCheck-1.7.0
23: packagemanager-1.7.0
24: pia-1.7.0
25: print-1.7.0
26: service-1.7.0
27: set-1.7.0
28: sh-1.7.0
29: sudo-1.7.0
30: template-1.7.0
31: writeplugin

Plugin References

How to access the plugins

All plugins are available as KOSI packages in the KubeOpsHub. Our plugins are grouped into several KOSI packages described below. To see our KOSI packages in the KubeOpsHub use the command:

Search for kubeops-plugins

kosi search --ps kubeops --hub public

Install for kubeops-plugins

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

The plugins are automatically placed in the associated directory($KUBEOPSROOT/plugins) and can be used directly.

Plugin packages

In this section you can find the plugin packages and the documentation for each plugin.

1 - auditLog-1.7.0

Kosi Plugin auditLog Version 1.7.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/kosi/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/kosi/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/";
    );
}

2 - bash-1.7.0

KOSI Plugin bash Version 1.7.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'

3 - chmod-1.7.0

KOSI Plugin chmod Version 1.7.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";
    );
}

4 - cmd-1.7.0

KOSI Plugin cmd Version 1.7.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.

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

5 - containerd-1.7.0

KOSI Plugin containerd Version 1.7.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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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 / seleteTask"; 
        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.

6 - Plugin References

Plugin References

How to access the plugins

All plugins are available as KOSI packages in the KubeOpsHub. Our plugins are grouped into several KOSI packages described below. To see our KOSI packages in the KubeOpsHub use the command:

KOSI 2.4.0 or higher

kosi search --ps kubeops --hub public

KOSI 2.4.0 or higher

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

The plugins are automatically placed in the associated directory($KUBEOPSROOT/plugins) and can be used directly.

Plugin packages

In this section you can find the plugin packages and the documentation for each plugin.

kubeops-basic-plugins

These plugins are part of the kubeops-basic-plugins package.

[Plugin copy]( “Plugin copy”)

[Plugin editFile]( “Plugin editFile”)

[Plugin fPrint]( “Plugin fPrint”)

[Plugin hostname]( “Plugin hostname”)

[Plugin if]( “Plugin if”)

[Plugin loop]( “Plugin loop”)

[Plugin osCheck]( “Plugin osCheck”)

[Plugin packagemanager]( “Plugin packagemanager”)

[Plugin service]( “Plugin service”)

[Plugin sudo]( “Plugin sudo”)

kubeops-kubernetes-plugins

These plugins are part of the kubeops-kubernetes-plugins package.

[Plugin auditLog]( “Plugin auditLog”)

[Plugin kubeadm]( “Plugin kubeadm”)

[Plugin kubectl]( “Plugin kubectl”)

pre-installed plugins

These plugins are installed with the installation of KOSI.

[Plugin bash]( “Plugin bash”)

[Plugin chmod]( “Plugin chmod”)

[Plugin cmd]( “Plugin cmd”)

[Plugin helm]( “Plugin helm”)

[Plugin print]( “Plugin print”)

[Plugin sh]( “Plugin sh”)

[Plugin template]( “Plugin template”)

[Plugin kosi]( “Plugin kosi”)

7 - containerRuntime-1.7.0

KOSI Plugin containerRuntime Version 1.7.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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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/kosi/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";
    );
}

8 - copy-1.7.0

KOSI Plugin copy Version 1.7.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/kosi/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/kosi/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/kosi/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";
    );
}

9 - editFile-1.7.0

KOSI Plugin editFile Version 1.7.0

Summary

The editFile Plugin enables modifications to YAML and text files by allowing users to add, overwrite, or delete specific content. It provides precise control over file edits by targeting YAML keys or specific line numbers in text files.

Keys

operation (required)

Defines the type of modification to be performed. This key accepts one of the following three modes:

Key	Description
add	Inserts a new value at the specified key (YAML) or line (text).
overwrite	Replaces the value of a specified key (YAML) or line (text).
delete	Removes a key (YAML) or deletes an entire line (text).

add

Adds a value to a specified key in a YAML file or a specific line in a text file.

For YAML files: You must specify the key where the new value should be added.
For text files: You must specify the line number where the new text should be inserted.

For example:

- editFile:
    operation: add
    fileType: text
    filePath: "/root/KosiPlugin/script.text"
    key: "spec.clusterMaster.toAdd"
    value: Hier steht ein Text

The key toAdd will be created / written into the file as a subtree of clusterMaster with the given value.

overwrite

Replaces the existing value at a specified key (YAML) or line (text).

Note: add and overwrite work the same for yaml.

delete

Removes a key (YAML) or deletes an entire line (text).

For YAML files: The key and its associated value will be removed.
For text files: The specified line will be deleted, and subsequent lines will shift up.

filePath (required)

Set the absolute pathe to the file to be edited as the value of this key.

fileType (required)

Defines the type of file being edited.

Set to “yaml” for YAML files.
Set to “text” for plain text files.

key

This is a mandatory key for yaml files.

This key allows you to specify the key you want to add, overwrite or delete in your yaml file.
Key is based on JSON Path.

For example:

key: "spec.clusterName"

This example shows the value of key, if you want to edit the key clusterName with the parent spec.

Note: If you have a list the key would be as followd:

key: "spec.clusterName.list.[0].Name"

line

This is a mandatory key for text files.

Allows you to set the line number where the operation gets executed.

value (required)

Defines the new value to be written into the file.

For text files, use \n to indicate a new line and \t for indentation.
For YAML files, this is the value assigned to the specified key.

For example:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "overwrite"; 
        fileType = "text";
        filePath = "/root/KosiPlugin/script.txt";
        line = "3";
        value = "Hier steht ein Text \n
                 \t clusterName: hier steht ein Name \n
                 \t hostips: \n
                 \t \t ips: \n
                 \t \t \t - 192.168.79.130";
    );
}

For yaml files, the whole string is set as the value for the given key.

For text files, when using add, the text will inserted beginning at line. For every newline in value a new line will be added to te file.
When using overwrite, the value will be split into multiple lines and every line in the input will replace one line in the old file starting at line.

Make sure that there are enough lines to overwrite

Examples for yaml files

example file

spec:
  clusterMaster:
    someText: this is an example
    toOverwrite: this will be gone

Example 1 - add new text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "add"; 
        fileType = "text";
        filePath = "/root/KosiPlugin/example.yaml";
        key = "spec.clusterMaster.toAdd";
        value = "this is ne text";
    );
}

Result:

spec:
  clusterMaster:
    someText: this is an example
    toOverwrite: heir steht text
    toAdd: this is new text

Example 2 - overwrite text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "overwrite"; 
        fileType = "yaml";
        filePath = "/root/KosiPlugin/example.yaml";
        key = "spec.clusterMaster.toOverwrite";
        value = "this replaced the old text";
    );
}

Result:

spec:
  clusterMaster:
    someText: this is an example
    toOverwrite: this replaced the old text

Example 3 - delete text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "delete"; 
        fileType = "yaml";
        filePath = "/root/KosiPlugin/example.yaml";
        key = "spec.clusterMaster.toOverwrite";
    );
}

Result:

spec:
  clusterMaster:
    someText: this is an example

Examples for text files

example file

bucket list:
 - item 1
 - item 2
 - item 3

Example 1 - add new text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "add"; 
        fileType = "text";
        filePath = "/root/KosiPlugin/example.txt";
        line = '"5"';
        value = '" - item 4"';
    );
}

Result:

bucket list:
 - item 1
 - item 2
 - item 3
 - item 4

Example 2 - overwrite text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "overwrite"; 
        fileType = "text";
        filePath = "/root/KosiPlugin/example.txt";
        line = "4";
        value = " - item 3";
    );
}

Result:

bucket list:
 - item 1
 - item 2
 - new item 3

Example 3 - delete text

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/kosi/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
{
    editFile
    (
        operation = "delete"; 
        fileType = "text";
        filePath = "/root/KosiPlugin/example.txt";
        line = "3";
    );
}

Result:

bucket list:
 - item 1
 - item 3

10 - firewall-1.7.0

KOSI Plugin Firewall Version 1.7.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']";
    );
}

11 - firewallD-1.7.0

KOSI Plugin FirewallD Version 1.7.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";
    );
}

12 - fprint-1.7.0

KOSI Plugin fprint Version 1.7.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']";
    );
}

13 - helm-1.7.0

KOSI Plugin Helm Version 1.7.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.

14 - hostname-1.7.0

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.

15 - if-1.7.0

KOSI Plugin if Version 1.7.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.

16 - ipTables-1.7.0

KOSI Plugin IPTables Version 1.7.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"
    );
}

17 - kosi-2.12.0

KOSI Plugin kosi Version 2.12.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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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 = "http://dispatcher.kubeops.net/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.

18 - kubeadm-1.7.0

KOSI Plugin kubeadm Version 1.7.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/kosi/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");
}

19 - kubectl-1.7.0

KOSI Plugin Kubectl Version 1.7.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";
    );
}

20 - loop-1.7.0

KOSI Plugin loop Version 1.7.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

21 - merge-1.7.0

KOSI Plugin Merge Version 1.7.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";
    );
}

22 - osCheck-1.7.0

KOSI Plugin osCheck Version 1.7.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.11.3.0_1734015070
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.

23 - packagemanager-1.7.0

KOSI Plugin Packagemanager Version 1.7.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.

24 - pia-1.7.0

KOSI Plugin PIA Version 1.7.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.9.0_Beta0_1704450448
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.preprod.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

25 - print-1.7.0

KOSI Plugin Print Version 1.7.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.

26 - service-1.7.0

KOSI Plugin Service Version 1.7.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.

27 - set-1.7.0

KOSI Plugin Set Version 1.7.0

Changelog Plugin set 1.7.0

New

set variables inside a KOSI process

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

28 - sh-1.7.0

KOSI Plugin sh Version 1.7.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 = "topsecret";
    );
}

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'

29 - sudo-1.7.0

KOSI Plugin sudo Version 1.7.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:

30 - template-1.7.0

KOSI Plugin Template Version 1.7.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.

31 - writeplugin

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