How to Guides

• 1: How to install KOSI as a user
• 2: How to build a KOSI package
• 3: How to install and access the Plugins from the Hub
• 4: How to update KOSI
• 5: How to template within the package.kosi

1 - How to install KOSI as a user

How to install KOSI as a user

This guide shows you how to install KOSI as a user. 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 or SUSE Linux Enterprise Server Version 15 SP3

2. You must have Helm installed on your machine.

   Refer Helm Official Documentation for Installation Guide.

3. For KOSI versions you must have installed Podman on your machine.

   Note : Before installing podman, make sure that The number of user namespaces (max_user_namespaces) is specified on your system if you are a non root-user.
   For more information, follow this Github link

To install podman on your OS use command:

• OS:
• RHEL8
• OpenSuse

dnf install podman

zypper install podman

Important: Only supports secure registries. If you use an insecure registry, it is important to list your registry as an insecure registry in registry.conf (/etc/containers/registries.conf).

Installation Steps

Every release of KOSI provides a rpm file for manual installation. You need to login into your KubeOps account to download the file.

1. Create an KubOps account on the KubeOps website if you don’t have already and login into your account.

2. Download your desired version of KOSI .rpm file from our official download page https://kubeops.net/products/downloads/kosi-downloads-en

3. Install the KOSI rpm on master node or admin node (recommended).

   • OS:
   • RHEL8
   • OpenSuse

   dnf install <path to rpm>/<kosi file name>

   zypper install <path to rpm>/<kosi file name>

path to rpm : the directory path in which the file is available.
kosi file name : the exact file name of the file with .rpm extension.

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable stores the location of the KOSI plugins, deployment.yaml and the config.yaml. To use the variable,the deployment.yaml, the config.yaml and the plugins have to be copied manually.
So for example:

echo 'export KUBEOPSROOT=/<home folder of user>/kubeops' >> $HOME/.bashrc
source $HOME/.bashrc

cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/config.yaml
cp -r /var/kubeops/kosi/config.yaml /home/<user>/kubeopsrootdir/kosi/deployment.yaml
rm -rf /var/kubeops/kosi
cp -r /var/kubeops/plugins /home/<user>/kubeopsrootdir/plugins
rm -rf /var/kubeops/plugins

For a clean installation it is not neccessary to move the deployment.yaml

Check Installation

You can check if the kosi is installed correctly on your machine simply with command kosi version.

kosi version

If the output indicates kosi version and relative information, KOSI is installed successfully. For example the output should look like

KOSI version: 2.9.0_Alpha0_1701852856
This work is licensed under Creative Commons Attribution - NoDerivatives 4.0 International License(see https://creativecommons.org/licenses/by-nd/4.0/legalcode for more details).
©KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2022

2 - 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

3 - How to install and access the Plugins from the Hub

How to access the Plugins

Note : Be sure you have a supported KOSI version 2.4.0 or higher.

KOSI Basic Plugins Version 1.4.0

kosi search --hub kosi-basic

[root@cluster2admin1 ~]# kosi search --hub kosi-basic
2024-04-09 10:01:40 Info:      KOSI version: 2.9.1_1709213374
| User | Name          | Version | Description        | Install                  |
|------|---------------|---------|--------------------|--------------------------|
| kosi | basic-plugins | 1.4.0   | KOSI Basic Plugins | kosi/basic-plugins:1.4.0 | 

This are the plugins which the packages contains:

KOSI Professional Plugins Version 1.4.0

kosi search --hub kosi-professional

[root@cluster2admin1 ~]# kosi search --hub kosi-professional
2024-04-09 10:04:13 Info:      KOSI version: 2.9.1_1709213374
| User | Name                 | Version | Description               | Install                         |
|------|----------------------|---------|---------------------------|---------------------------------|
| kosi | professional-plugins | 1.4.0   | KOSI Professional Plugins | kosi/professional-plugins:1.4.0 |

This are the plugins which the packages contains:

KOSI Enterprise Plugins Version 1.4.0

kosi search --hub kosi-professional

[root@cluster2admin1 ~]# kosi search --hub kosi-professional
2024-04-09 10:04:13 Info:      KOSI version: 2.9.1_1709213374
| User | Name                 | Version | Description               | Install                         |
|------|----------------------|---------|---------------------------|---------------------------------|
| kosi | professional-plugins | 1.4.0   | KOSI Professional Plugins | kosi/professional-plugins:1.4.0 |

This are the plugins which the packages contains:

How to install the Plugins

After installing the plugins with our kosi install Command, the plugins are automatically placed in the associated directory ($KUBEOPSROOT/plugins) and can be used directly.

kosi install --hub=<pluginhub> user/packagename:version

Example: The package basic-plugins of the user kosi with the version 1.4.0 is to be installed from the kosi-basic hub.

kosi install --hub=kosi-basic kosi/basic-plugins:1.4.0 

Note: You can also use the Install Tab from the Output to Help with Installation.

4 - How to update KOSI

How to update KOSI

This guide shows you how to update KOSI. 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 or SUSE Linux Enterprise Server Version 15 SP3

2. You must have Helm installed on your machine.

   Refer Helm Official Documentation for Installation Guide.

3. For KOSI versions you must have installed Podman on your machine.

   Note : Before installing podman, make sure that The number of user namespaces (max_user_namespaces) is specified on your system if you are a non root-user.
   For more information, follow this Github link

To install podman on your OS use command:

• OS:
• RHEL8
• OpenSuse

dnf install podman

zypper install podman

Important: Only supports secure registries. If you use an insecure registry, it is important to list your registry as an insecure registry in registry.conf (/etc/containers/registries.conf).

Update Steps

Every release of KOSI provides a rpm file for manual installation. You need to login into your KubeOps account to download the rpm.

1. Create an KubOps account on the KubeOps website if you don’t have already and login into your account.

2. Download your desired version of KOSI .rpm file from our official download page https://kubeops.net/products/downloads/kosi-downloads-en

3. Update the KOSI rpm on master node or admin node (recommended). You can it simply install the rpm and override the existan version.
   

   Caution

   If you do this as a user you have to set your $KUBEOPSROOT new and copy the files.

   Set $KUBEOPSROOT as a user.

   • OS:
   • RHEL8
   • OpenSuse

   dnf install <path to rpm>/<kosi file name>

   zypper install <path to rpm>/<kosi file name>

path to rpm : the directory path in which the file is available.
kosi file name : the exact file name of the file with .rpm extension.

5 - How to template within the package.kosi

How to template within the package.kosi"

TBA