Creating a Basic KOSI-Package and Deployment

In this quickstart you will learn about:

• how to get to know KOSI-packages
• add repositories and download helm charts
• create a KOSI-package
• configure a KOSI-package to deploy a demo WordPress page
• optional: install and deploy the KOSI-package to a cluster

Prerequisites

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

• KOSI is installed, see KOSI Installation Guide
• basic understanding of Kubernetes, network clusters and tools such as Helm or Podman
• basic understanding of Linux environments, bash / shell
• administrator privileges (root) are granted

Step 1 - Create a KOSI-Package

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

Login into the machine where KOSI is installed.

Create a new folder and use the command kosi create to create a default KOSI-package with pre-built files.

mkdir ~/kosi-demo
cd ~/kosi-demo

kosi create

Example output:

2024-08-07 13:49:00 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
2024-08-07 13:49:00 Info:      Write package.kosi to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write template.yaml to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write logo.png to /root/kosi-demo
2024-08-07 13:49:00 Info:      Write docs.tgz to /root/kosi-demo

Step 2 - Understand the Package Logic

The package.kosi file contains the „logic“ of the package. This file uses the kosi format which itself uses the highly expressive KOSI Language.

Among other things the package.kosi file defines:

• a preambel for meta data and descriptions
• a files section to - manages files, such as templates, to be included and target files
• a set of commands - for example „install“ or „upgrade“ which work as scripts within the kosi file

Templates make it possible to use variantes for your packages. For example, you want to reuse a package for different environments. Templates also allow to parse additional „value files“ as command line arguments.

Advanced templating makes it possible to split one large value files into smaller ones. In this case we use some of the defaultvalues but all values will be transfered.

Step 3 - Modify the Template File

For the transfer of values into a package, a valuestemplate.yaml file is needed.

Use an editor to edit the file:

nano ~/kosi-demo/valuestemplate.yaml

To get the most out of this guide, add the following lines:

{{values}}

This command will allow to parse the values of the file values.yaml. On installing, the file values.yaml will be automatically transcluded into the cluster. This is helpful to reuse a package for different environments.

Notice the exact same naming of the command with the file.

Step 4 - Add Necessary Repositories and Pull Charts

In this guide we want to create a KOSI-package containing a demo WordPress page. Therefore you need to add the necessary repository via helm. Afterwards you need to pull the latest version of the helm chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm pull bitnami/wordpress --version X.Y.Z

Step 5 - Configure the Package

Configure the package to inlucde the valuestemplate.yaml file. Also add commands for install, update, and delete.

Use an editor to edit the file:

nano ~/kosi-demo/package.kosi

To get the most out of this guide, overwrite the file with the following lines:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v3";
name = "wordpressdemo";
description = "Deploys a wordpress helm chart";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files =
{
    wordpressvaluestemplate= "valuestemplate.yaml";
    chart = "wordpress-X.Y.Z.tgz";
}


install
{
    template(tmpl="valuestemplate.yaml";target="wordpressvalues.yaml");
    helm(command="upgrade";tgz="wordpress-X.Y.Z.tgz";values="['wordpressvalues.yaml']";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--create-namespace',' --install']");
}

update
{
    template(tmpl="valuestemplate.yaml";target="wordpressvalues.yaml");
    helm(command="upgrade";tgz="wordpress-X.Y.Z.tgz";values="['wordpressvalues.yaml']";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--create-namespace',' --install']");
}

delete
{
    cmd(command="echo delete wordpressdemo helm deployment.");
    helm(command="delete";deploymentName="wordpressdemo";namespace="wordpressdemo";flags="['--wait']");
    cmd(command="echo delete wordpressdemo namespace.");
    cmd(command="kubectl delete namespace wordpressdemo");
}

Step 6 - Create Package Documentation

It is always a good practice to document your packages.

Within your package folder, create a docs folder:

mkdir -p ~/kosi-demo/docs

Create a simple README file (for example markdown format) and write some helpful descriptions. For example:

echo „My first KOSI-package. Contains a demo WordPress page.“ > ~/kosi-demo/docs/README.md

Afterwards you need to compress the whole docs folder using the tgs format.

cd ~/kosi-demo/
tar -cvzf docs.tgz docs/

These docs will be included when building the deployable package file.

Step 7 - Build the Package

When the package.kosi is finished and the documentation is done, the KOSI-package can be built. Navigate to the package folder and simply use the kosi build command.

cd ~/kosi-demo/
kosi build

During the build process, the files package.tgz and package.yaml are created.

Step 8 - Setting Values for the Package

To install the package.tgz, you need the package itself and some values. Among other things, you need to define the nodePorts for http at 30123. This node port will be needed to access and test your WordPress page.

In a previous step we made the package reuseable by using the valuestemplate.yaml file. This files expects a values.yaml file as command line argument.

Use an editor to edit the file:

nano ~/kosi-demo/values.yaml

To get the most out of this guide, add the following lines:

global:
    storageClass: rook-cephfs
service:
    type: NodePort
    nodePorts:
        http: 30123
mariadb:
    enabled: true
    auth:
        rootPassword: topsecretChangeMe
        password: secretChangeMe
    primary:
        persistence:
            enabled: true
            storageClass: rook-cephfs
            accessModes:
                - ReadWriteOnce
persistence:
    enabled: true
    storageClass: rook-cephfs

Optional Step 9 - Installing the Package and Deploy to Cluster

As recommended you need a running Kubernetes cluster to install and deploy your new KOSI-package. You must also be logged in to the Admin machine where you have created the KOSI-package. To set up a cluster easily and conveniently, you can use kubeopsctl (see kubeopsctl documentation).

Navigate to your built KOSI-package. Install the package and pass the prepared values.yaml file as command line argument.

cd ~/kosi-demo
kosi install -p package.tgz -f values.yaml

Optional Step 10 - Test the WordPress Page

After you deployed the KOSI-package you can test the access via your cluster to the WordPress page.

Depending on your setup you need the following:

• the IP or hostname of a master node
• tunneling or expossing of ports according to the nodePorts as set in values.yaml

In this guides we set 30123 as nodePort. For example, in your browser navigate to:

http://master1:30123