How to build a KOSI package

Building a KOSI package is an easy and efficient way to build your own packages. This guide outlines the essential steps and commands to help you successfully build your KOSI package.
Tags:

  5 minute read  

How to build your own KOSI package

This guide shows you how to create a KOSI package. KOSI can be downloaded only from our official website.

Prerequisites

Before you begin, check the following prerequisites:

  1. A machine with any of the following operating systems
    • RHEL 8
  2. A text editor (Vi, VIM, Nano, etc.)
  3. An internet connection for downloading images or Helm charts
  4. All prerequisites for the KOSI installation

The package base

Using the kosi create command, all base components for building your package are generated.

kosi create

Output:

2024-08-07 13:29:40 Info:      KOSI version: 2.11.0.11_Beta0_1723014878
2024-08-07 13:29:41 Info:      Write package.kosi to /root/demo
2024-08-07 13:29:41 Info:      Write template.yaml to /root/demo
2024-08-07 13:29:41 Info:      Write logo.png to /root/demo
2024-08-07 13:29:41 Info:      Write docs.tgz to /root/demo

The package logic

The core of your package is defined in the package.kosi file. To build the package, you need additional files such as a Helm chart and a valuestemplate.yaml file. In this example, default values from the Bitnami WordPress Helm chart are used. A simple valuestemplate.yaml is required to build the package.

A valuestemplate.yaml

{{values}}

A Helm chart is required as well. Download the Bitnami WordPress Helm chart from ArtifactHub and prepare your values.yaml based on the default values. You can get both here.

A helm chart and values

helm repo add bitnami https://charts.bitnami.com/bitnami
helm pull bitnami/wordpress --version 21.0.6

Note: This chart is not for production. It is only for demo purposes.

In the following example, the chart and the valuestemplate.yaml are added to the package.kosi. To convert the values, you need to call the template plugin, there you have to set the tmpl file and a target. Advanced templating makes it possible to split one large value file into smaller ones. In this case we use some of the default values but all values will be transfered.
To execute the helm install/upgrade operation, the helm plugin has to be called and for the target file is needed for the values.
You can also write update and remove operations for your package like in the example.
A clean is done in the remove section. With the helm plugin the helm deployment is removed and the cmd plugin call will remove the namespace.

A package.kosi example

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

files =
{
    wordpressvaluestemplate = "valuestemplate.yaml";
    chart = "wordpress-21.0.6.tgz";
}

install
{
    template
    (
        tmpl = "valuestemplate.yaml";
        target = "wordpressvalues.yaml";
    );

    helm
    (
        command = "upgrade";
        tgz = "wordpress-21.0.6.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-21.0.6.tgz";
        values = "['wordpressvalues.yaml']";
        deploymentName = "wordpressdemo";
        namespace = "wordpressdemo";
        flags = "['--create-namespace ', '--install']";
    );
}

delete
{
    cmd(command = "echo delete worpressdemo helm deployment.");

    helm
    (
        command = "delete";
        deploymentName = "worpressdemo";
        namespace = "wordpressdemo";
        flags="['--wait']";
    );

    cmd(command="echo delete worpressdemo namespace.");

    cmd(command="kubectl delete namespace worpressdemo");
}

Note: For more information about the package.kosi file, click here.

Build the package

When the package.kosi file is complete, build the package. During the build process, a package.tgz archive and a package.yaml file are created. To build your KOSI package, simply use the following command:

kosi build

Note: The package.yaml file is generated only once. If a package.yaml already exists, KOSI will not generate a new one.

Install the package

To install your package, you need both the package.tgz and a values.yaml file containing the necessary configuration values. Typically, values are derived from the chart’s default values.

A values.yaml example

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

To install the package, use the kosi install command.
The -p parameter is set for a local package.
The -f parameter is set to hand over value files to the package.

kosi install -p package.tgz -f values.yaml

In this case, the output of the chart will describe your next steps:

kosi install -p package.tgz -f values1.yaml
2024-08-07 13:47:34 Info:      KOSI version: 2.11.0.11_Beta0_1723014878
2024-08-07 13:47:35 Info:      template write to /var/kubeops/kosi/e628d035-4700-4f55-a9ac-ab9217b8e79f/wordpressvalues.yaml
2024-08-07 13:47:35 Info:      run cmd plugin
2024-08-07 13:47:35 Info:      use plugin bash if available
2024-08-07 13:47:35 Info:      Executing with non sudo privilegs
2024-08-07 13:47:36 Info:      Release "wordpressdemo" does not exist. Installing it now.
NAME: wordpressdemo
LAST DEPLOYED: Tue Mar 26 10:47:35 2024
NAMESPACE: wordpressdemo
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: wordpress
CHART VERSION: 21.0.6
APP VERSION: 6.4.3

** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    wordpressdemo.wordpressdemo.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

   export NODE_PORT=$(kubectl get --namespace wordpressdemo -o jsonpath="{.spec.ports[0].nodePort}" services wordpressdemo)
   export NODE_IP=$(kubectl get nodes --namespace wordpressdemo -o jsonpath="{.items[0].status.addresses[0].address}")
   echo "WordPress URL: http://$NODE_IP:$NODE_PORT/"
   echo "WordPress Admin URL: http://$NODE_IP:$NODE_PORT/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace wordpressdemo wordpressdemo -o jsonpath="{.data.wordpress-password}" | base64 -d)

WARNING: There are "resources" sections in the chart not set. Using "resourcesPreset" is not recommended for production. For production installations, please set the following values according to your workload needs:
  - resources
+info https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

2024-08-07 13:47:36 Info:      Helm upgrade successfully.
2024-08-07 13:47:36 Info:      Installation successful