Kosi: Creating a Basic KOSI-Package and Deployment

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

In this quickstart you will learn about:

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

Notice

The intent of this guide is to setup a demo WordPress page on your cluster or your machine.

We do not recommend this guide for production environments.

Important To get the most out of this guide, we recommend to create your first demo KOSI-package on the admin machine of a basic cluster. For a helpful guide, see Set up a Basic cluster using kubeopsctl.

Prerequisites

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

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

Step 1 - Create a KOSI-Package

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

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

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

kosi create

Example output:

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

File	Description
`package.kosi`	Contains the „logic“ of the package.
`template.yml`	A template file for configurations and the templating engine.
`logo.png`	A logo for the package. replace this with your desired logo (png format).
`docs.tgz`	Contains your documentaion of your package.

Step 2 - Understand the Package Logic

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

Among other things the package.kosi file defines:

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

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

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

Step 3 - Modify the Template File

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

Use an editor to edit the file:

nano ~/kosi-demo/valuestemplate.yaml

To get the most out of this guide, add the following 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

Important This command works with any running Kubernetes cluster.

Optional Step 10 - Test the WordPress Page

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

Depending on your setup you need the following:

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

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

http://master1:30123

KubeOpsDoku – kosi package

Kosi: Creating a Basic KOSI-Package and Deployment

Prerequisites

Step 1 - Create a KOSI-Package

Step 2 - Understand the Package Logic

Step 3 - Modify the Template File

Step 4 - Add Necessary Repositories and Pull Charts

Step 5 - Configure the Package

Step 6 - Create Package Documentation

Step 7 - Build the Package

Step 8 - Setting Values for the Package

Optional Step 9 - Installing the Package and Deploy to Cluster

Optional Step 10 - Test the WordPress Page