How to build a KOSI package

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
   • openSUSE
2. Vi, VIM, Nano or other text editors
3. An internet-connection for downloading images or helmcharts.
4. All Prerequisits for the KOSI installation

The package base

With kosi create - command we generate all base components for building our own package.

kosi create

Output:

2024-03-25 13:29:40 Info:      KOSI version: 2.9.1_1709213374
2024-03-25 13:29:41 Info:      Write package.kosi to /root/demo
2024-03-25 13:29:41 Info:      Write template.yaml to /root/demo
2024-03-25 13:29:41 Info:      Write logo.png to /root/demo
2024-03-25 13:29:41 Info:      Write docs.tgz to /root/demo

The package logic

The logic of the package is in the package.kosi. For building the package you need some additional files like a helm chart and a valuestemplate.yaml - file. In this case all defaultvalues from the bitnami helmchart of wordpress are used. For the transfer into the package, a simple valuestemplate.yaml is needed.

A valuestemplate.yaml

{{values}}

A helm chart is needed as well. Download the bitnami worpress helm chart from the ArtifactHUB and prepare your values.yaml from the defaultvalues. You get both here.

A helmchart and values

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

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. For transfering 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 files into smaller ones. In this case we use some of the defaultvalues but all values will be transfered.
For executing the helm install/upgrade operation, the helm plugin has to be called and for the values the target-file is needed.
You can also write update and remove operations for your package like in the example.
In the remove section a clean is done. with the helm plugin the helm deployment is removed and the cmd plugin call will remove the namespace.

A package.kosi example

languageversion = "0.1.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-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 wordpressdemo"');
}

For more information about the package.kosi Click here.

Build the package

If the package.kosi is finished, the package can be built. In the build process a package.tgz and package.yaml are created. For building a kosi-package simply use the kosi build command.

kosi build

The package.yaml is only generated once, if it is not available. If the package.yaml already exists the package.yaml will not be generated.

Install the package

To install the package.tgz you need the package itself and some values. In this case some values from the defaultvalues of the chart are used. For this a values.yaml is created.

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

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

In this case the output of the chart describe your next steps.

kosi install -p package.tgz -f values1.yaml
2024-03-26 10:47:34 Info:      KOSI version: 2.9.2
2024-03-26 10:47:35 Info:      template write to /var/kubeops/kosi/e628d035-4700-4f55-a9ac-ab9217b8e79f/wordpressvalues.yaml
2024-03-26 10:47:35 Info:      run cmd plugin
2024-03-26 10:47:35 Info:      use plugin bash if available
2024-03-26 10:47:35 Info:      Executing with non sudo privilegs
2024-03-26 10: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-03-26 10:47:36 Info:      Helm upgrade successfully.
2024-03-26 10:47:36 Info:      Installation successful