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.