How to update KOSI

Updating KOSI is a straightforward process that ensures you have the latest features and security enhancements. Follow this guide to update KOSI automatically, via the package repository, or by downloading the appropriate RPM/DEB file manually.

Prerequisites

Before you begin, make sure the following prerequisites are met:

KOSI is designed to work with the latest versions of the following operating systems:

OS Diskspace

Red Hat Enterprise Linux 9.6 and 9.7 500 MB

Ubuntu 24.04.02 500 MB

OpenSUSE MicroOS 20260630 (rolling release) 500 MB

OS	Diskspace
Red Hat Enterprise Linux 9.6 and 9.7	500 MB
Ubuntu 24.04.02	500 MB
OpenSUSE MicroOS 20260630 (rolling release)	500 MB

⚠ Warning Only RHEL 9.6 and 9.7 are supported. Make sure the OS version is pinned to prevent accidental updates to an unsupported version, as this may break the cluster.

Helm must be installed on your machine.

Refer to the Helm Official Documentation for the Installation Guide.

For KOSI versions, you must have Podman installed 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, run the following command:
```
sudo dnf install podman
```
⚠ Caution

KOSI supports only secure registries. If you use an insecure registry, you must explicitly add it as an insecure registry in registries.conf (/etc/containers/registries.conf).

Update Methods

You have multiple options to update KOSI, depending on your system setup and preferences.

Method 1: Automatic Update Check via Config

With KOSI config v3, a new update check feature is introduced. By default, it is disabled (checkforupdates: false).

Important: This feature is not currently supported by OpenSUSE MicroOS.

If you set checkforupdates: true, KOSI will automatically check the kubeops-repo package repository for new versions after every successful KOSI command. If a new version is available, KOSI will prompt you and ask if you want to proceed with the update.

Here is the complete config.yaml:

# file $KUBEOPSROOT/kosi/config.yaml
apiversion: kubernative/sina/config/v3

spec:
  hub: https://dispatcher.kubeops.net/v4/dispatcher/ # <-- set hub url
  plugins: <your kubeopsroot>/plugins/ # <-- set the path to your plugin folder (~ for home or $KUBEOPSROOT don't work, it has to be the full path)
  workspace: /tmp/kosi/process/
  logging: info
  housekeeping: false
  proxy: false
  checkforupdates: false # <-- set to 'true' to enable update checks

Method 2: Update via Package Repository

If you have included the KubeOps package repository in your OS, you can quickly update KOSI using the standard package manager.

sudo apt update
sudo apt install -y kosi

sudo dnf install -y --disableexcludes=kubeops-repo kosi

# KOSI update via package repo is not supported
# Please update it manually

Method 3: Manual Update via Download

Each KOSI release includes an RPM/DEB file for manual installation. To download the package, you must log in to your KubeOps account.

Create a KubeOps Account:
If you haven’t already, create a KubeOps account on the KubeOps website and log in to your account.
Download the Package:
Download your desired version of the KOSI package file (.rpm or .deb) from the official download page:
https://kubeops.net/products/downloads/kosi-downloads-en

Update the KOSI Package:
On your admin node, update KOSI by installing the new package. This will replace the existing version. Run the following command:

# download kosi deb manually and install with
sudo dpkg --install kosi-2.15.0.4_Beta0_amd64.deb # <- Replace the file with the one you downloaded.

# download kosi rpm manually and install with
sudo rpm --install kosi-2.15.0.4_Beta0-0.x86_64.rpm # <- Replace the file with the one you downloaded.

A direct update on OpenSUSE MicroOS is not possible, so you have to repeat the installation steps.

1. Install KOSI

# download kosi rpm manually and install with
sudo transactional-update pkg install --no-confirm --allow-unsigned-rpm --force kosi-2.15.0.4_Beta0-0.x86_64.rpm # <- Replace the file with the one you downloaded.

sudo reboot now # need reboot after transactional update!

sudo mkdir -p /var/kubeops/plugins
sudo cp /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/plugins/*.dll /var/kubeops/plugins/
sudo mkdir -p /var/kubeops/kosi
sudo cp /.snapshots/$(sudo ls -1 /.snapshots | sed '$!d')/snapshot/var/kubeops/kosi/config.yaml /var/kubeops/kosi/

2. Set the KUBEOPSROOT env var

Set KUBEOPSROOT and XDG_RUNTIME_DIR in ~/.bashrc

Note These are not console commands. The following entries must be added to the end of your ~/.bashrc file.

# file ~/.bashrc
# Append these values to the end of your ~/.bashrc file
export KUBEOPSROOT=/home/<yourUser>/kubeops
export XDG_RUNTIME_DIR=$KUBEOPSROOT

Source .bashrc to apply the values

source ~/.bashrc
echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

As a result you should see your KUBEOPSROOT-path two times.

3. Adjust KOSI Configuration

This creates a kubeops directory in your home directory and transfers all necessary files, e.g., the kosi-config and the plugins, to it.

mkdir ~/kubeops
cd ~/kubeops
cp -R /var/kubeops/kosi/ .
cp -R /var/kubeops/plugins/ .

Important The config.yaml is in your KUBEOPSROOT-path (typically in ~/kubeops/kosi)

Set hub in your kosi config to hub: https://dispatcher.kubeops.net/v4/dispatcher/</a>.
Set the “plugins”-entry in your kosi config to plugins: /home/<yourUser>/kubeops/plugins, where is changed to your username.

Note Replace the file name with the exact file name of the package (including the .rpm or .deb extension).

Verify your Installation

To verify the installation of KOSI on your system, use the command kosi version.

kosi version

The output displays the KOSI version along with relevant information. It confirms the successful installation of KOSI.

2026-07-28 13:57:39 Info:      KOSI version: 2.15.0.4_Beta0_1785144578
2026-07-28 13:57:40 Info:      Latest KOSI-package-apiversion: kubernative/kubeops/sina/user/v4
2026-07-28 13:57:40 Info:      Latest KOSI-language-version is: 1.0.0
2026-07-28 13:57:40 Info:      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).
2026-07-28 13:57:40 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2025

Check to see if the environment variables are still set correctly. They may be being overwritten.

echo $KUBEOPSROOT
echo $XDG_RUNTIME_DIR

Check to see if the config.yaml file is still correct. It may have been overwritten.

cat $KUBEOPSROOT/kosi/config.yaml