KubeOpsDoku – How to Guides

Kosi: How to manually push images to your KubeOps-Registry project space

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

How to manually push images to your KubeOps-Registry project space

To manually push container images into your KubeOps-Registry project space, you need to use your Harbor CLI secret for authentication when using podman.

How to get your CLI secret

Click on your username and select User Profile.
On the User Profile page, you can copy or change your CLI secret if needed.

Now you can push your image using the CLI secret:

podman login registry.kubeops.net -u <username> -p <CLI_secret>

Note: Replace <username> with your KubeOps username and <CLI_secret> with your actual CLI secret.

How to push your image

After logging in, tag your image with the registry path of your KubeOps-Registry project space:

Important: In most cases, you do not need to push images manually. You can specify a local or remote image directly in your KOSI package, for example docker.io/library/nginx:latest or my-app:v1.12.1. When KOSI pushes the package, it rewrites the image reference in the package to the pushed registry image under registry.kubeops.net. After that, you can use the rewritten and pushed image in your KOSI package.

Note: Replace <local_image>, <project>, <image> and <tag> with your actual values.

podman tag <local_image>:<tag> registry.kubeops.net/<project>/<image>:<tag>

Example:

podman tag my-app:v1.12.1 registry.kubeops.net/my-project/my-app:v1.12.1

Then push the image to your project space:

podman push registry.kubeops.net/<project>/<image>:<tag>

Example:

podman push registry.kubeops.net/my-project/my-app:v1.12.1

Kosi: Accessing kubeops-community packages

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

This documentation describes how to search for, install, and manage packages from the kubeops-community hub using the Kosi CLI.

Searching for Packages

To list all available packages within the KubeOps community, you use the search command.

Command:

kosi search --hub kubeops-community

Example Output:

User	Name	Version	Description	Install
kubeops-community	hashicorp-vault	0.32.0	Official HashiCorp Vault Chart	kubeops-community/hashicorp-vault:0.32.0
kubeops-community	jenkins	5.8.142	Deploys jenkins via helm	kubeops-community/jenkins:5.8.142
kubeops-community	elasticsearch	8.5.1	Deploys elasticsearch via helm	kubeops-community/elasticsearch:8.5.1

Note: This overview shows you the exact path needed for the installation step in addition to the package name and version.

Installing Packages

Once you have found a suitable package, you can deploy it into your Kubernetes cluster using the install command. You can assign a specific name to your deployment using the --dname flag.

General Syntax:

kosi install --hub <Hub_Name> <Install_Path> --dname <Deployment_Name>

Examples

Installing HashiCorp Vault:

kosi install --hub kubeops-community kubeops-community/hashicorp-vault:0.32.0 --dname hashicorp-vault

Installing Jenkins:

kosi install --hub kubeops-community kubeops-community/jenkins:5.8.142 --dname jenkins

Installing Elasticsearch:

kosi install --hub kubeops-community kubeops-community/elasticsearch:8.5.1 --dname elasticsearch

Listing Deployed Packages

To view all currently installed packages and their deployment names, use the list command. The deployment name is required for updates and deletions.

Command:

kosi list

Example Output:

Deployment	Package	Hub
hashicorp-vault	kubeops-community/hashicorp-vault:0.32.0	kubeops-community
jenkins	kubeops-community/jenkins:5.8.142	kubeops-community
elasticsearch	kubeops-community/elasticsearch:8.5.1	kubeops-community

Updating and Deleting Packages

To modify or remove an existing deployment, use the update or delete commands and include the --dname flag to specify which deployment you are targeting.

Updating a Package

The update command executes the update logic and updates the deployment in the Kubernetes cluster.

Example (Updating HashiCorp Vault):

kosi update --hub kubeops-community kubeops-community/hashicorp-vault:<new-version> --dname hashicorp-vault

Deleting a Package

The delete command executes the delete logic and removes the deployment from the Kubernetes cluster.

Example (Deleting HashiCorp Vault):

kosi delete --hub kubeops-community kubeops-community/hashicorp-vault:0.32.0 --dname hashicorp-vault

Kosi: How to install KOSI as a user

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

This guide explains how to install KOSI as a user. KOSI can only be downloaded from our official website.

Prerequisites

Operating System: A machine running RHEL 9.
Helm: Helm Must be installed on your machine. Refer to the Helm Official Documentation.
Podman:
KOSI requires Podman to be installed on your machine.

Note If you are a non-root user, ensure that the number of user namespaces (max_user_namespaces) is configured correctly. For more details, refer to this GitHub tutorial.

Install on RHEL9:
```
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).

Installation Steps

Download the KOSI RPM:
- Log in to your KubeOps account.
- Download your desired version of the KOSI RPM from the official download page.
Install the KOSI RPM on your admin node:
Run the following commands:
```
echo 'export KUBEOPSROOT=/home/<user>/kubeops' >> $HOME/.bashrc
source $HOME/.bashrc
sudo dnf install <path_to_rpm>/<kosi_file_name>.rpm
```
Note
- Replace <path_to_rpm> with the directory path where the file is located.
- Replace <kosi_file_name> with the exact RPM file name (including the .rpm extension).

$KUBEOPSROOT Variable

The $KUBEOPSROOT environment variable defines the location of the KOSI plugins, deployment.yaml, and config.yaml.
If you change the KUBEOPSROOT variable after installation, you must manually copy the updated deployment.yaml, config.yaml, and plugins.

Run the following commands to update them:

echo 'export KUBEOPSROOT=/home/<user>/kubeops' >> $HOME/.bashrc
source $HOME/.bashrc
cp -r /var/kubeops/kosi/config.yaml $KUBEOPSROOT/kosi/config.yaml
cp -r /var/kubeops/kosi/deployment.yaml $KUBEOPSROOT/kosi/deployment.yaml
cp -r /var/kubeops/plugins $KUBEOPSROOT/

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

Check Installation

To verify that KOSI is installed correctly on your machine, run:

kosi version

A successful installation will display version details, it will look similar like this:

2024-08-07 13:49:00 Info:      KOSI version: 2.15.0.0_XXXXXXXXXX
2024-08-07 13:49:00 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).
2024-08-07 13:49:00 Info:      © KubeOps GmbH, Hinter Stöck 17, 72406 Bisingen - Germany, 2023

Kosi: How to use Variables in KOSI Packages

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

KOSI plugins can produce internal variables during execution, which you can reference in subsequent steps of your package (for example in conditions or output messages). The following guide explains how to use variables set by various KOSI plugins and how to consume them using e.g. the if and fprint plugins (which allow conditional logic and formatted output, respectively).

Plugins that set Variables

Several plugins store their results in named variables. These include:

Firewall / Firewalld / IPTables – All three firewall plugins support a key like getFirewallStatus = "<var>". For example:
```
firewall
(
    type = "firewalld";
    action = "enable";
    getFirewallStatus = "status";
);
```
This stores the firewall status ("running" or "not running") into the variable status. You can then reference this status variable in later steps.
Hostname – The hostname plugin can get the current hostname into a variable or set a new hostname from a variable. Its keys are: get = "<var>" to save the current hostname and setVar = "<var>" to restore from a saved variable. For example:
```
hostname(get = "oldHostname");
```
This saves the machine’s current hostname into the variable oldHostname.
kubeadm – The kubeadm plugin runs kubeadm commands. Its outputVar = "<var>" option captures the command’s output into a variable. For example:
```
kubeadm
(
    operation = "version";
    kubeadmVersion = "version";
    outputVar = "kubeadmVersionOutput";
);
```
This saves the output of kubeadm version into the variable kubeadmVersionOutput.
kubectl – The kubectl plugin executes kubectl commands. Its outputVar = "<var>" captures the command output. For example:
```
kubectl
(
    operation = "get";
    resource = "pods";
    flags = "-n kube-system -o wide";
    outputVar = "podsOutput";
    outputFile = "/root/output.txt";
);
```
This saves the kubectl get pods output into podsOutput. You can then use podsOutput in subsequent steps.
osCheck – The osCheck plugin detects the OS name and version. It has two keys: getOSVar="<var>" for the OS name and getOSVersionVar="<var>" for the OS version. For example:
```
osCheck(getOSVar="osName"; getOSVersionVar="osVersion");
```
This stores the OS name in osName and the version in osVersion.
set – The set plugin lets you define arbitrary variables. Use variable="<name>"; value="<something>" to create a variable. For example:
```
set(variable = "envType"; value = "production");
```
This creates a variable named envType with value "production". Variables set by the set plugin are accessed via vars.<variableName>.

Referencing Plugin Variables

KOSI provides two main ways to use these variables:

Conditional checks with the if plugin: The if plugin evaluates an expression and branches accordingly. In the condition string, you can include plugin variables by name, enclosed in $...$ . For example:
```
if(condition = "$oldHostname$ = 'myHost'") then {
    # ... do something ...
}
```
For variables set via the set plugin, access them as $vars.<name>$ , e.g. $vars.envType$ .

Formatted output with the fprint plugin: The fprint plugin prints a message and can include plugin-variable values. You provide a list of variable names in its variables key and placeholders {0}, {1}, etc. in the message. For example:

fprint
(
    message = "Firewall status is {0}";
    variables = "['status']";
);

For variables from the set plugin:

set(variable="userName"; value="Alice");
set(variable="userIP"; value="10.0.0.1");
fprint
(
    message = "User {0} has IP {1}";
    variables = "['vars.userName','vars.userIP']";
);

Example Workflow

Set or retrieve a variable:

hostname(get = "myHostname");
osCheck(getOSVar = "osName"; getOSVersionVar = "osVersion");

Conditionally act on it:

 if(condition = "$myHostname$ = 'expectedHost'") then {
     fprint
     (
         message = "Got expected hostname: {0}";
         variables = "['myHostname']";
     );
 }

Output or log values:

fprint
(
    message = "Running on {0} version {1}";
    variables = "['osName','osVersion']";
);

Plugins mentioned in this How to Guide that set or use variables

Kosi: Installing KOSI packages from KubeOps Hub

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

To install KOSI packages from the KubeOps Hub on your machines, follow these steps:

Search for the Package:
Use the kosi search command to find the desired package on the KubeOps Hub.
(Refer to kosi search for more info.)
Install the Package:
Copy the installation address of the desired package and use it with the kosi install command:
```
kosi install --hub <hubname> <installation address>
```

To be able to install a package from the software Hub, you must be logged in as a user.

Install from Private Hub

Example:
The package wordpressdemo of user kosi with version 0.1.0 is to be installed from the private software Hub:

kosi install --hub kubeops kosi/wordpressdemo:0.1.0

Install from Public Hub

Example:
The package wordpressdemo of user kosi with version 0.1.0 is to be installed from the public software Hub:

kosi install --hub kubeops kosi/wordpressdemo:0.1.0

Install along with yaml files

The -f parameter is used to provide YAML files from the user.

kosi install --hub <hubname> <package> -f <user.yaml>

Example:
The package wordpressdemo of user kosi with version 0.1.0 is installed from the public software Hub with user-specific YAML files:

kosi install --hub kubeops kosi/wordpressdemo:0.1.0 -f userfile1.yaml

Install in specific namespace

The --namespace flag allows you to specify a Kubernetes namespace for the installation.

kosi install --hub <hubname> <package> --namespace <namespace>

Example:
The package wordpressdemo of user kosi with version 0.1.0 is installed from the public software Hub in a custom Kubernetes namespace:

kosi install --hub kubeops kosi/wordpressdemo:0.1.0 --namespace MyNamespace

Note: If no --namespace parameter is specified, the default namespace will be used.

Install with specific deployment name

The --dname flag allows you to assign a specific name to the deployment.

kosi install --hub <hubname> <package> --dname <deploymentname>

Example:
The package wordpressdemo of user kosi with version 0.1.0 is installed from the public software Hub with a deployment name set:

kosi install --hub kubeops kosi/wordpressdemo:0.1.0 --dname MyDeployment

If no --dname parameter is specified, a random deployment name will be generated.

Note: The deployment name is stored in the file /home/<user>/var/kubeops/kosi/deployment.yaml.

In these few steps, you can successfully install and use a KOSI package.

For additional functionality and features provided by KOSI, always refer to the Full Documentation.

Install on a machine with no internet connection

Download the Package:
Use kosi pull on a machine with an internet connection to download the package:

kosi pull [package name from hub] -o [your preferred name] --hub public

Transfer the Package:
Move the downloaded package to the machine without an internet connection (which has KubeOps installed).
Install the Package:
Install the transferred package with the following command:

kosi install -p [package name]

Kosi: How to install and access the Plugins from the Hub

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

How to access the Plugins

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

All plugins are available as KOSI packages in the KubeOpsHub. Our plugins are grouped into several KOSI packages. To view the available packages, use the command:

KOSI Basic Plugins Version 1.6.X

kosi search --hub kosi-basic

2024-08-07 13:47:02 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name          | Version     | Description        | Install                        |
|------|---------------|-------------|--------------------|--------------------------------|
| kosi | basic-plugins | 1.5.0_beta0 | KOSI Basic Plugins | kosi/basic-plugins:1.5.0_beta0 |
| kosi | basic-plugins | 1.5.0       | KOSI Basic Plugins | kosi/basic-plugins:1.5.0       |
| kosi | basic-plugins | 1.4.0       | KOSI Basic Plugins | kosi/basic-plugins:1.4.0       |
| kosi | basic-plugins | 1.6.0_Beta0 | KOSI Basic Plugins | kosi/basic-plugins:1.6.0_Beta0 |
| kosi | basic-plugins | 1.4.2       | KOSI Basic Plugins | kosi/basic-plugins:1.4.2       |
| kosi | basic-plugins | 1.4.1       | KOSI Basic Plugins | kosi/basic-plugins:1.4.1       |

This package contains the following plugins:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0

KOSI Professional Plugins Version 1.6.X

kosi search --hub kosi-professional

2024-08-07 13:47:36 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name                 | Version     | Description               | Install                               |
|------|----------------------|-------------|---------------------------|---------------------------------------|
| kosi | professional-plugins | 1.5.0_beta0 | KOSI Professional Plugins | kosi/professional-plugins:1.5.0_beta0 |
| kosi | professional-plugins | 1.4.0       | KOSI Professional Plugins | kosi/professional-plugins:1.4.0       |
| kosi | professional-plugins | 1.5.0       | KOSI Professional Plugins | kosi/professional-plugins:1.5.0       |
| kosi | professional-plugins | 1.4.2       | KOSI Professional Plugins | kosi/professional-plugins:1.4.2       |
| kosi | professional-plugins | 1.4.1       | KOSI Professional Plugins | kosi/professional-plugins:1.4.1       |
| kosi | professional-plugins | 1.6.0_Beta0 | KOSI Professional Plugins | kosi/professional-plugins:1.6.0_Beta0 |

This are the plugins which the packages contains:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0
kubectl	1.6.0
bash	1.6.0
cmd	1.6.0
sh	1.6.0
editfile	1.6.0
fprint	1.6.0
if	1.6.0
loop	1.6.0
kosi	2.11.0.10
merge	1.6.0
exit	1.6.0
setfact	1.6.0

KOSI Enterprise Plugins Version 1.6.X

kosi search --hub kosi-enterprise

2024-08-07 13:47:59 Info:      KOSI version: 2.14.0.0_XXXXXXXXXX
| User | Name               | Version     | Description                  | Install                             |
|------|--------------------|-------------|------------------------------|-------------------------------------|
| kosi | enterprise-plugins | 1.5.0       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.5.0       |
| kosi | piaoperator        | 1.4.0       | Pia Operator Install Package | kosi/piaoperator:1.4.0              |
| kosi | enterprise-plugins | 1.4.2       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.2       |
| kosi | enterprise-plugins | 1.5.0_beta0 | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.5.0_beta0 |
| kosi | enterprise-plugins | 1.4.0       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.0       |
| kosi | enterprise-plugins | 1.6.0_Beta0 | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.6.0_Beta0 |
| kosi | enterprise-plugins | 1.4.1       | KOSI Enterprise Plugins      | kosi/enterprise-plugins:1.4.1       |

This package contains the following plugins:

Plugin	Version
template	1.6.0
helm	1.6.0
print	1.6.0
kubectl	1.6.0
bash	1.6.0
cmd	1.6.0
sh	1.6.0
editfile	1.6.0
fprint	1.6.0
if	1.6.0
loop	1.6.0
kosi	2.11.0.10
merge	1.6.0
exit	1.6.0
setfact	1.6.0
auditlog	1.6.0
chmod	1.6.0
copy	1.6.0
firewall	1.6.0
firewallD	1.6.0
containerd	1.6.0
containerruntime	1.6.0
hostname	1.6.0
iptables	1.6.0
kubeadm	1.6.0
osCheck	1.6.0
packagemanager	1.6.0
pia	1.6.0
service	1.6.0
sudo	1.6.0

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 enterprise-plugins of the user kosi with the version 1.6.0_Beta0 is to be installed from the kosi-enterprise hub.

kosi install --hub=kosi-enterprise kosi/enterprise-plugins:1.6.0_Beta0

Note: You can also use the Install Tab from the output to help with installation.

Kosi: How to update KOSI

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

This guide shows you how to update KOSI. KOSI can be updated via the package repository, updated automatically, or downloaded from our official website for manual installation.

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

Kosi: How to create SBOM for kosi packages (kosi tools sbom)

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

How to use KOSI Tools SBOM

This guide shows you how to use the kosi tools sbom command to generate and display a Software Bill of Materials (SBOM) for KOSI packages. You can generate SBOMs for both locally available packages and packages hosted on a hub.

⚠ Warning Currently kosi tools sbom can only be used by a privileged user (root) and in a non-airgap environment.

Prerequisites

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

Supported Operating Systems: KOSI tools are tested and supported on the following operating systems:
- Ubuntu 24.04
- Red Hat Enterprise Linux (RHEL) 9.6
Syft Installation: To execute the sbom command, you must have Syft installed on your machine.
A privileged user (root) and a non-airgap environment.

Installing Syft

You can easily install Syft on our supported systems using wget to download the specific package format for your OS.

# Define the Syft version (check GitHub for the current release)
# https://github.com/anchore/syft/releases/
SYFT_VERSION="1.46.0"

# Download the .deb package with wget
wget https://github.com/anchore/syft/releases/download/v${SYFT_VERSION}/syft_${SYFT_VERSION}_linux_amd64.deb

# Install the downloaded package
sudo dpkg --install syft_${SYFT_VERSION}_linux_amd64.deb

# Define the Syft version (check GitHub for the current release)
# https://github.com/anchore/syft/releases/
SYFT_VERSION="1.46.0"

# Download the .rpm package with wget
wget https://github.com/anchore/syft/releases/download/v${SYFT_VERSION}/syft_${SYFT_VERSION}_linux_amd64.rpm

# Install the downloaded package
sudo dnf install syft_${SYFT_VERSION}_linux_amd64.rpm

Note

Alternatively, you can install Syft universally using their official installation script:

wget -qO- https://get.anchore.io/syft | sudo sh -s -- -b /usr/local/bin

Usage Options

The command syntax for generating an SBOM is as follows:

kosi tools sbom [options] [<package>]

Available Arguments and Options

Option	Description
`<package>`	The name or path of the package.
`-p, --local-package <p>`	Show SBOM from a local package file (e.g., a `.tgz` archive).
`--hub`	Show SBOM directly from a package located in the KOSI hub.
`-?, -h, --help`	Show help and usage information.

Examples

To generate an SBOM for a package that has already been downloaded to your local file system, use the -p (or --local-package) flag followed by the file name:

kosi tools sbom -p metricsserver.tgz

Example output

# kosi tools sbom -p metricsserver.tgz
2026-07-06 10:16:41 Info:      KOSI version: KOSI version: 2.15.0.4_Beta0_1785144578
----------------------------------------------------------------------
Generate SBOM for image registry.kubeops.net/kubeops/kubeops/metrics-server/metrics-server:v0.8.0@sha256:3d2ca9b2af6aa14c9b698fa14e3a8f017f012517ebd1a6d3a36f28a4c56ae938
NAME                                                                         VERSION                               TYPE
base-files                                                                   12.4+deb12u11                         deb
cel.dev/expr                                                                 v0.20.0                               go-module
github.com/NYTimes/gziphandler                                               v1.1.1                                go-module
github.com/antlr4-go/antlr/v4                                                v4.13.0                               go-module
github.com/beorn7/perks                                                      v1.0.1                                go-module
github.com/blang/semver/v4                                                   v4.0.0                                go-module
github.com/cenkalti/backoff/v4                                               v4.3.0                                go-module
github.com/cespare/xxhash/v2                                                 v2.3.0                                go-module
github.com/coreos/go-semver                                                  v0.3.1                                go-module
github.com/coreos/go-systemd/v22                                             v22.5.0                               go-module
github.com/davecgh/go-spew                                                   v1.1.2-0.20180830191138-d8f796af33cc  go-module
github.com/emicklei/go-restful/v3                                            v3.11.0                               go-module
github.com/felixge/httpsnoop                                                 v1.0.4                                go-module
github.com/fsnotify/fsnotify                                                 v1.8.0                                go-module
github.com/fxamacker/cbor/v2                                                 v2.7.0                                go-module
github.com/go-logr/logr                                                      v1.4.2                                go-module
github.com/go-logr/stdr                                                      v1.2.2                                go-module
github.com/go-logr/zapr                                                      v1.3.0                                go-module
github.com/go-openapi/jsonpointer                                            v0.21.0                               go-module
github.com/go-openapi/jsonreference                                          v0.21.0                               go-module
github.com/go-openapi/swag                                                   v0.23.0                               go-module
github.com/gogo/protobuf                                                     v1.3.2                                go-module
github.com/golang/protobuf                                                   v1.5.4                                go-module
github.com/google/btree                                                      v1.1.3                                go-module
github.com/google/cel-go                                                     v0.23.2                               go-module
github.com/google/gnostic-models                                             v0.6.9                                go-module
github.com/google/go-cmp                                                     v0.7.0                                go-module
github.com/google/uuid                                                       v1.6.0                                go-module
github.com/grafana/regexp                                                    v0.0.0-20240518133315-a468a5bfb3bc    go-module
github.com/grpc-ecosystem/go-grpc-prometheus                                 v1.2.0                                go-module
github.com/grpc-ecosystem/grpc-gateway/v2                                    v2.26.3                               go-module
github.com/josharian/intern                                                  v1.0.0                                go-module
github.com/json-iterator/go                                                  v1.1.12                               go-module
github.com/kylelemons/godebug                                                v1.1.0                                go-module
github.com/mailru/easyjson                                                   v0.7.7                                go-module
github.com/moby/term                                                         v0.5.0                                go-module
github.com/modern-go/concurrent                                              v0.0.0-20180306012644-bacd9c7ef1dd    go-module
github.com/modern-go/reflect2                                                v1.0.2                                go-module
github.com/munnerz/goautoneg                                                 v0.0.0-20191010083416-a7dc8b61c822    go-module
github.com/pkg/errors                                                        v0.9.1                                go-module
github.com/prometheus/client_golang                                          v1.22.0                               go-module
github.com/prometheus/client_model                                           v0.6.2                                go-module
github.com/prometheus/common                                                 v0.65.0                               go-module
github.com/prometheus/procfs                                                 v0.15.1                               go-module
github.com/prometheus/prometheus                                             v0.304.2                              go-module
github.com/spf13/cobra                                                       v1.9.1                                go-module
github.com/spf13/pflag                                                       v1.0.6                                go-module
github.com/stoewer/go-strcase                                                v1.3.0                                go-module
github.com/x448/float16                                                      v0.8.4                                go-module
go.etcd.io/etcd/api/v3                                                       v3.5.21                               go-module
go.etcd.io/etcd/client/pkg/v3                                                v3.5.21                               go-module
go.etcd.io/etcd/client/v3                                                    v3.5.21                               go-module
go.opentelemetry.io/auto/sdk                                                 v1.1.0                                go-module
go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc  v0.58.0                               go-module
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp                v0.60.0                               go-module
go.opentelemetry.io/otel                                                     v1.35.0                               go-module
go.opentelemetry.io/otel/exporters/otlp/otlptrace                            v1.35.0                               go-module
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc              v1.35.0                               go-module
go.opentelemetry.io/otel/metric                                              v1.35.0                               go-module
go.opentelemetry.io/otel/sdk                                                 v1.35.0                               go-module
go.opentelemetry.io/otel/trace                                               v1.35.0                               go-module
go.opentelemetry.io/proto/otlp                                               v1.5.0                                go-module
go.uber.org/multierr                                                         v1.11.0                               go-module
go.uber.org/zap                                                              v1.27.0                               go-module
golang.org/x/crypto                                                          v0.38.0                               go-module
golang.org/x/exp                                                             v0.0.0-20250106191152-7588d65b2ba8    go-module
golang.org/x/net                                                             v0.40.0                               go-module
golang.org/x/oauth2                                                          v0.30.0                               go-module
golang.org/x/sync                                                            v0.14.0                               go-module
golang.org/x/sys                                                             v0.33.0                               go-module
golang.org/x/term                                                            v0.32.0                               go-module
golang.org/x/text                                                            v0.25.0                               go-module
golang.org/x/time                                                            v0.11.0                               go-module
google.golang.org/genproto/googleapis/api                                    v0.0.0-20250303144028-a0af3efb3deb    go-module
google.golang.org/genproto/googleapis/rpc                                    v0.0.0-20250414145226-207652e42e2e    go-module
google.golang.org/grpc                                                       v1.72.0                               go-module
google.golang.org/protobuf                                                   v1.36.6                               go-module
gopkg.in/evanphx/json-patch.v4                                               v4.12.0                               go-module
gopkg.in/inf.v0                                                              v0.9.1                                go-module
gopkg.in/natefinch/lumberjack.v2                                             v2.2.1                                go-module
gopkg.in/yaml.v3                                                             v3.0.1                                go-module
k8s.io/api                                                                   v0.33.2                               go-module
k8s.io/apimachinery                                                          v0.33.2                               go-module
k8s.io/apiserver                                                             v0.33.2                               go-module
k8s.io/client-go                                                             v0.33.2                               go-module
k8s.io/component-base                                                        v0.33.2                               go-module
k8s.io/klog/v2                                                               v2.130.1                              go-module
k8s.io/kms                                                                   v0.33.2                               go-module
k8s.io/kube-openapi                                                          v0.0.0-20250318190949-c8a335a9a2ff    go-module
k8s.io/metrics                                                               v0.33.2                               go-module
k8s.io/utils                                                                 v0.0.0-20241104100929-3ea5e8cea738    go-module
netbase                                                                      6.4                                   deb
sigs.k8s.io/apiserver-network-proxy/konnectivity-client                      v0.31.2                               go-module
sigs.k8s.io/json                                                             v0.0.0-20241010143419-9aa6b5e7a4b3    go-module
sigs.k8s.io/metrics-server                                                   UNKNOWN                               go-module
sigs.k8s.io/randfill                                                         v1.0.0                                go-module
sigs.k8s.io/structured-merge-diff/v4                                         v4.6.0                                go-module
sigs.k8s.io/yaml                                                             v1.4.0                                go-module
stdlib                                                                       go1.24.4                              go-module
tzdata                                                                       2025b-0+deb12u1                       deb
----------------------------------------------------------------------
Generate SBOM for image registry.kubeops.net/kubeops/kubeops/autoscaling/addon-resizer:1.8.23@sha256:4c24051f09c29ed6a855341754feb581b81e0f54aaedc7782edf2c9e7e67b3a7
NAME                                  VERSION                               TYPE
base-files                            12.4+deb12u9                          deb
github.com/beorn7/perks               v1.0.1                                go-module
github.com/blang/semver/v4            v4.0.0                                go-module
github.com/cespare/xxhash/v2          v2.3.0                                go-module
github.com/davecgh/go-spew            v1.1.2-0.20180830191138-d8f796af33cc  go-module
github.com/emicklei/go-restful/v3     v3.11.0                               go-module
github.com/fxamacker/cbor/v2          v2.7.0                                go-module
github.com/go-logr/logr               v1.4.2                                go-module
github.com/go-openapi/jsonpointer     v0.21.0                               go-module
github.com/go-openapi/jsonreference   v0.20.2                               go-module
github.com/go-openapi/swag            v0.23.0                               go-module
github.com/gogo/protobuf              v1.3.2                                go-module
github.com/golang/protobuf            v1.5.4                                go-module
github.com/google/gnostic-models      v0.6.8                                go-module
github.com/google/go-cmp              v0.6.0                                go-module
github.com/google/gofuzz              v1.2.0                                go-module
github.com/google/uuid                v1.6.0                                go-module
github.com/josharian/intern           v1.0.0                                go-module
github.com/json-iterator/go           v1.1.12                               go-module
github.com/klauspost/compress         v1.17.9                               go-module
github.com/mailru/easyjson            v0.7.7                                go-module
github.com/modern-go/concurrent       v0.0.0-20180306012644-bacd9c7ef1dd    go-module
github.com/modern-go/reflect2         v1.0.2                                go-module
github.com/munnerz/goautoneg          v0.0.0-20191010083416-a7dc8b61c822    go-module
github.com/pkg/errors                 v0.9.1                                go-module
github.com/prometheus/client_golang   v1.20.5                               go-module
github.com/prometheus/client_model    v0.6.1                                go-module
github.com/prometheus/common          v0.62.0                               go-module
github.com/prometheus/procfs          v0.15.1                               go-module
github.com/spf13/pflag                v1.0.5                                go-module
github.com/x448/float16               v0.8.4                                go-module
go.opentelemetry.io/otel              v1.28.0                               go-module
go.opentelemetry.io/otel/trace        v1.28.0                               go-module
golang.org/x/net                      v0.33.0                               go-module
golang.org/x/oauth2                   v0.24.0                               go-module
golang.org/x/sys                      v0.28.0                               go-module
golang.org/x/term                     v0.27.0                               go-module
golang.org/x/text                     v0.21.0                               go-module
golang.org/x/time                     v0.7.0                                go-module
google.golang.org/protobuf            v1.36.1                               go-module
gopkg.in/evanphx/json-patch.v4        v4.12.0                               go-module
gopkg.in/inf.v0                       v0.9.1                                go-module
gopkg.in/yaml.v3                      v3.0.1                                go-module
k8s.io/api                            v0.32.1                               go-module
k8s.io/apimachinery                   v0.32.1                               go-module
k8s.io/autoscaler/addon-resizer       v1.8.23                               go-module
k8s.io/client-go                      v0.32.1                               go-module
k8s.io/component-base                 v0.32.1                               go-module
k8s.io/klog/v2                        v2.130.1                              go-module
k8s.io/kube-openapi                   v0.0.0-20241105132330-32ad38e42d3f    go-module
k8s.io/utils                          v0.0.0-20241104100929-3ea5e8cea738    go-module
netbase                               6.4                                   deb
sigs.k8s.io/json                      v0.0.0-20241010143419-9aa6b5e7a4b3    go-module
sigs.k8s.io/structured-merge-diff/v4  v4.4.2                                go-module
sigs.k8s.io/yaml                      v1.4.0                                go-module
stdlib                                go1.23.4                              go-module
tzdata                                2024b-0+deb12u1                       deb

To generate an SBOM for a package that is hosted on the KOSI hub without downloading it manually, specify the package name and use the --hub flag to specify the hub name:

kosi tools sbom kubeops/metrics-server:2.2.0_Beta0 --hub kubeops

Example output

# kosi tools sbom kubeops/metrics-server:2.2.0_Beta0 --hub kubeops
2026-07-06 10:15:32 Info:      KOSI version: 2.15.0.4_Beta0_1785144578
2026-07-06 10:15:33 Info:      ...Download 100%
2026-07-06 10:16:25 Info:      Checking package hash
2026-07-06 10:16:25 Info:      Hash checked succesfully. Is equal
----------------------------------------------------------------------
Generate SBOM for image registry.kubeops.net/kubeops/kubeops/metrics-server/metrics-server:v0.8.0@sha256:3d2ca9b2af6aa14c9b698fa14e3a8f017f012517ebd1a6d3a36f28a4c56ae938
NAME                                                                         VERSION                               TYPE
base-files                                                                   12.4+deb12u11                         deb
cel.dev/expr                                                                 v0.20.0                               go-module
github.com/NYTimes/gziphandler                                               v1.1.1                                go-module
github.com/antlr4-go/antlr/v4                                                v4.13.0                               go-module
github.com/beorn7/perks                                                      v1.0.1                                go-module
github.com/blang/semver/v4                                                   v4.0.0                                go-module
github.com/cenkalti/backoff/v4                                               v4.3.0                                go-module
github.com/cespare/xxhash/v2                                                 v2.3.0                                go-module
github.com/coreos/go-semver                                                  v0.3.1                                go-module
github.com/coreos/go-systemd/v22                                             v22.5.0                               go-module
github.com/davecgh/go-spew                                                   v1.1.2-0.20180830191138-d8f796af33cc  go-module
github.com/emicklei/go-restful/v3                                            v3.11.0                               go-module
github.com/felixge/httpsnoop                                                 v1.0.4                                go-module
github.com/fsnotify/fsnotify                                                 v1.8.0                                go-module
github.com/fxamacker/cbor/v2                                                 v2.7.0                                go-module
github.com/go-logr/logr                                                      v1.4.2                                go-module
github.com/go-logr/stdr                                                      v1.2.2                                go-module
github.com/go-logr/zapr                                                      v1.3.0                                go-module
github.com/go-openapi/jsonpointer                                            v0.21.0                               go-module
github.com/go-openapi/jsonreference                                          v0.21.0                               go-module
github.com/go-openapi/swag                                                   v0.23.0                               go-module
github.com/gogo/protobuf                                                     v1.3.2                                go-module
github.com/golang/protobuf                                                   v1.5.4                                go-module
github.com/google/btree                                                      v1.1.3                                go-module
github.com/google/cel-go                                                     v0.23.2                               go-module
github.com/google/gnostic-models                                             v0.6.9                                go-module
github.com/google/go-cmp                                                     v0.7.0                                go-module
github.com/google/uuid                                                       v1.6.0                                go-module
github.com/grafana/regexp                                                    v0.0.0-20240518133315-a468a5bfb3bc    go-module
github.com/grpc-ecosystem/go-grpc-prometheus                                 v1.2.0                                go-module
github.com/grpc-ecosystem/grpc-gateway/v2                                    v2.26.3                               go-module
github.com/josharian/intern                                                  v1.0.0                                go-module
github.com/json-iterator/go                                                  v1.1.12                               go-module
github.com/kylelemons/godebug                                                v1.1.0                                go-module
github.com/mailru/easyjson                                                   v0.7.7                                go-module
github.com/moby/term                                                         v0.5.0                                go-module
github.com/modern-go/concurrent                                              v0.0.0-20180306012644-bacd9c7ef1dd    go-module
github.com/modern-go/reflect2                                                v1.0.2                                go-module
github.com/munnerz/goautoneg                                                 v0.0.0-20191010083416-a7dc8b61c822    go-module
github.com/pkg/errors                                                        v0.9.1                                go-module
github.com/prometheus/client_golang                                          v1.22.0                               go-module
github.com/prometheus/client_model                                           v0.6.2                                go-module
github.com/prometheus/common                                                 v0.65.0                               go-module
github.com/prometheus/procfs                                                 v0.15.1                               go-module
github.com/prometheus/prometheus                                             v0.304.2                              go-module
github.com/spf13/cobra                                                       v1.9.1                                go-module
github.com/spf13/pflag                                                       v1.0.6                                go-module
github.com/stoewer/go-strcase                                                v1.3.0                                go-module
github.com/x448/float16                                                      v0.8.4                                go-module
go.etcd.io/etcd/api/v3                                                       v3.5.21                               go-module
go.etcd.io/etcd/client/pkg/v3                                                v3.5.21                               go-module
go.etcd.io/etcd/client/v3                                                    v3.5.21                               go-module
go.opentelemetry.io/auto/sdk                                                 v1.1.0                                go-module
go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc  v0.58.0                               go-module
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp                v0.60.0                               go-module
go.opentelemetry.io/otel                                                     v1.35.0                               go-module
go.opentelemetry.io/otel/exporters/otlp/otlptrace                            v1.35.0                               go-module
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc              v1.35.0                               go-module
go.opentelemetry.io/otel/metric                                              v1.35.0                               go-module
go.opentelemetry.io/otel/sdk                                                 v1.35.0                               go-module
go.opentelemetry.io/otel/trace                                               v1.35.0                               go-module
go.opentelemetry.io/proto/otlp                                               v1.5.0                                go-module
go.uber.org/multierr                                                         v1.11.0                               go-module
go.uber.org/zap                                                              v1.27.0                               go-module
golang.org/x/crypto                                                          v0.38.0                               go-module
golang.org/x/exp                                                             v0.0.0-20250106191152-7588d65b2ba8    go-module
golang.org/x/net                                                             v0.40.0                               go-module
golang.org/x/oauth2                                                          v0.30.0                               go-module
golang.org/x/sync                                                            v0.14.0                               go-module
golang.org/x/sys                                                             v0.33.0                               go-module
golang.org/x/term                                                            v0.32.0                               go-module
golang.org/x/text                                                            v0.25.0                               go-module
golang.org/x/time                                                            v0.11.0                               go-module
google.golang.org/genproto/googleapis/api                                    v0.0.0-20250303144028-a0af3efb3deb    go-module
google.golang.org/genproto/googleapis/rpc                                    v0.0.0-20250414145226-207652e42e2e    go-module
google.golang.org/grpc                                                       v1.72.0                               go-module
google.golang.org/protobuf                                                   v1.36.6                               go-module
gopkg.in/evanphx/json-patch.v4                                               v4.12.0                               go-module
gopkg.in/inf.v0                                                              v0.9.1                                go-module
gopkg.in/natefinch/lumberjack.v2                                             v2.2.1                                go-module
gopkg.in/yaml.v3                                                             v3.0.1                                go-module
k8s.io/api                                                                   v0.33.2                               go-module
k8s.io/apimachinery                                                          v0.33.2                               go-module
k8s.io/apiserver                                                             v0.33.2                               go-module
k8s.io/client-go                                                             v0.33.2                               go-module
k8s.io/component-base                                                        v0.33.2                               go-module
k8s.io/klog/v2                                                               v2.130.1                              go-module
k8s.io/kms                                                                   v0.33.2                               go-module
k8s.io/kube-openapi                                                          v0.0.0-20250318190949-c8a335a9a2ff    go-module
k8s.io/metrics                                                               v0.33.2                               go-module
k8s.io/utils                                                                 v0.0.0-20241104100929-3ea5e8cea738    go-module
netbase                                                                      6.4                                   deb
sigs.k8s.io/apiserver-network-proxy/konnectivity-client                      v0.31.2                               go-module
sigs.k8s.io/json                                                             v0.0.0-20241010143419-9aa6b5e7a4b3    go-module
sigs.k8s.io/metrics-server                                                   UNKNOWN                               go-module
sigs.k8s.io/randfill                                                         v1.0.0                                go-module
sigs.k8s.io/structured-merge-diff/v4                                         v4.6.0                                go-module
sigs.k8s.io/yaml                                                             v1.4.0                                go-module
stdlib                                                                       go1.24.4                              go-module
tzdata                                                                       2025b-0+deb12u1                       deb
----------------------------------------------------------------------
Generate SBOM for image registry.kubeops.net/kubeops/kubeops/autoscaling/addon-resizer:1.8.23@sha256:4c24051f09c29ed6a855341754feb581b81e0f54aaedc7782edf2c9e7e67b3a7
NAME                                  VERSION                               TYPE
base-files                            12.4+deb12u9                          deb
github.com/beorn7/perks               v1.0.1                                go-module
github.com/blang/semver/v4            v4.0.0                                go-module
github.com/cespare/xxhash/v2          v2.3.0                                go-module
github.com/davecgh/go-spew            v1.1.2-0.20180830191138-d8f796af33cc  go-module
github.com/emicklei/go-restful/v3     v3.11.0                               go-module
github.com/fxamacker/cbor/v2          v2.7.0                                go-module
github.com/go-logr/logr               v1.4.2                                go-module
github.com/go-openapi/jsonpointer     v0.21.0                               go-module
github.com/go-openapi/jsonreference   v0.20.2                               go-module
github.com/go-openapi/swag            v0.23.0                               go-module
github.com/gogo/protobuf              v1.3.2                                go-module
github.com/golang/protobuf            v1.5.4                                go-module
github.com/google/gnostic-models      v0.6.8                                go-module
github.com/google/go-cmp              v0.6.0                                go-module
github.com/google/gofuzz              v1.2.0                                go-module
github.com/google/uuid                v1.6.0                                go-module
github.com/josharian/intern           v1.0.0                                go-module
github.com/json-iterator/go           v1.1.12                               go-module
github.com/klauspost/compress         v1.17.9                               go-module
github.com/mailru/easyjson            v0.7.7                                go-module
github.com/modern-go/concurrent       v0.0.0-20180306012644-bacd9c7ef1dd    go-module
github.com/modern-go/reflect2         v1.0.2                                go-module
github.com/munnerz/goautoneg          v0.0.0-20191010083416-a7dc8b61c822    go-module
github.com/pkg/errors                 v0.9.1                                go-module
github.com/prometheus/client_golang   v1.20.5                               go-module
github.com/prometheus/client_model    v0.6.1                                go-module
github.com/prometheus/common          v0.62.0                               go-module
github.com/prometheus/procfs          v0.15.1                               go-module
github.com/spf13/pflag                v1.0.5                                go-module
github.com/x448/float16               v0.8.4                                go-module
go.opentelemetry.io/otel              v1.28.0                               go-module
go.opentelemetry.io/otel/trace        v1.28.0                               go-module
golang.org/x/net                      v0.33.0                               go-module
golang.org/x/oauth2                   v0.24.0                               go-module
golang.org/x/sys                      v0.28.0                               go-module
golang.org/x/term                     v0.27.0                               go-module
golang.org/x/text                     v0.21.0                               go-module
golang.org/x/time                     v0.7.0                                go-module
google.golang.org/protobuf            v1.36.1                               go-module
gopkg.in/evanphx/json-patch.v4        v4.12.0                               go-module
gopkg.in/inf.v0                       v0.9.1                                go-module
gopkg.in/yaml.v3                      v3.0.1                                go-module
k8s.io/api                            v0.32.1                               go-module
k8s.io/apimachinery                   v0.32.1                               go-module
k8s.io/autoscaler/addon-resizer       v1.8.23                               go-module
k8s.io/client-go                      v0.32.1                               go-module
k8s.io/component-base                 v0.32.1                               go-module
k8s.io/klog/v2                        v2.130.1                              go-module
k8s.io/kube-openapi                   v0.0.0-20241105132330-32ad38e42d3f    go-module
k8s.io/utils                          v0.0.0-20241104100929-3ea5e8cea738    go-module
netbase                               6.4                                   deb
sigs.k8s.io/json                      v0.0.0-20241010143419-9aa6b5e7a4b3    go-module
sigs.k8s.io/structured-merge-diff/v4  v4.4.2                                go-module
sigs.k8s.io/yaml                      v1.4.0                                go-module
stdlib                                go1.23.4                              go-module
tzdata                                2024b-0+deb12u1                       deb

Kosi: How to install KOSI Proxy

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

How to install KOSI Proxy

This guide shows you how to install the KOSI Proxy. The KOSI Proxy enables controlled access to packages and container images by allowing downloads while blocking uploads to the internet. This guide describes how to install, configure, and operate the KOSI Proxy and Harbor registry integration.

Architecture

The following diagram shows the architecture of the KOSI Proxy. Packages and container images can be fetched through the KOSI Proxy. Uploading packages and container images to the internet is blocked. Access can also be restricted to a HUB.

Prerequisites

To install the KOSI Proxy, you need a dedicated VM running RHEL9 OS and root access.

The minimum VM requirements are:

4 CPUs
8 GB RAM
50 GB disk space

The following software must be installed on this VM:

docker
docker compose
kosi

# docker
subscription-manager register
subscription-manager refresh
subscription-manager attach --auto
dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
dnf repolist -v
dnf install docker-ce
systemctl enable docker --now
systemctl status docker

# docker compose
curl -L "https://github.com/docker/compose/releases/download/v5.3.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose 

# kosi
wget https://packagerepo.kubeops.net/rpm/kosi-2.15.0.4_Beta0-0.x86_64.rpm
dnf install -y kosi*.rpm

#### Configure the KOSI hub in ´/var/kubeops/kosi/config.yaml`    
```yaml
apiversion: kubernative/sina/config/v3

spec:
  hub: https://dispatcher.kubeops.net/v4/dispatcher/ # <- set hub
  plugins: /var/kubeops/plugins/
  workspace: /tmp/kosi/process/
  logging: info
  housekeeping: false
  proxy: false
  checkforupdates: false

Install KOSI Proxy

Once all prerequisites are met, you can install the KOSI Proxy.

A values.yaml file is required for KOSI Proxy installation.
Below is an example values.yaml configuration for the environment:

# Proxy host IP address
proxyIP: 10.2.10.99

# Prod config values
#proxyPassthrough: prod
#proxyRegistry: registry.kubeops.net
#aspnetcoreEnvironment: Development

# Prod config values
proxyPassthrough: prod
proxyRegistry: registry.kubeops.net
aspnetcoreEnvironment: Production

Note

Use the values for the environment you are deploying to.

For prod, use the prod registry and prod config values.

After creating the values.yaml file, the KOSI Proxy can be installed using a kosi package.
The KOSI Proxy will be installed in ~/kosi-proxy

# install kosi enterprise plugins
kosi install --hub kosi-enterprise kosi/enterprise-plugins:2.2.0_Beta0

# kosi login with your user
kosi login -u <user>

# install kosi proxy with values.yaml
kosi install --hub kubeops kubeops/kosi-proxy:2.15.0.4_Beta0 -f values.yaml

Start the KOSI Proxy:

cd ~/kosi-proxy
docker compose up -d

Configure KOSI Proxy (Advanced)

The KOSI Proxy is already configured during installation; however, you can adjust additional parameters if needed.

1. Hub Whitelist

The hub whitelist can be configured in the app settings file ~/kosi-proxy/data/download-v4/appsettings.json.
By default the hubs kosi, kubeops and kosi-enterprise are set.

{
  "Logging": {
    "LogLevel": {
      "Microsoft": "Warning",
      "System": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Kubeops": "Debug"
    },
    "Console": {
      "FormatterName": "simple",
      "FormatterOptions": {
        "SingleLine": false,
        "TimestampFormat": "HH:mm:ss ",
        "ColorBehavior": "Enabled",
        "UseUtcTimestamp": false
      }
    }
  },
  "AllowedHosts": "*",
  "Config": {
    "RepositoryPath": "/service/repository",
    "PermissionServiceUrl": "http://permission-v4/",
    "ProxyPassthroughUrl": "https://dispatcher.kubeops.net/v4/download/",
    "GuestQuota": 1000000,
    "HubWhitelist": "kosi, kubeops, kosi-enterprise"
  }
}

Install Harbor

Harbor is used as the registry endpoint in this setup.

1. Download installer

Download the Harbor offline installer:

# harbor
cd ~
curl -L https://github.com/goharbor/harbor/releases/download/v2.15.2/harbor-offline-installer-v2.15.2.tgz | tar -xvzf -
cd ~/harbor
cp harbor.yml.tmpl harbor.yml

2. Configure harbor.yml values

Edit the harbor.yml

Change:

hostname: 10.2.10.99  # line 5
insecure: true        # line 122

Comment out:

#  port: 443                            # line 15
#  certificate: /your/certificate/path  # line 17
#  private_key: /your/private/key/path  # line 18

3. Run install script:

cd ~/harbor
./install.sh

Configure Harbor

1. Port Forwarding

To log in to Harbor, port 80 of the proxy host must be forwarded.
The following example shows SSH port forwarding. Adjust the values as needed.

ssh -i "C:\Users\<user>\.ssh\id_rsa" -J <user>@10.9.112.19 -L 8080:10.2.10.99:80 root@10.2.10.99

You can then log in to Harbor -> http://localhost:8080
Default credentials:

User: admin
Initial Password: Harbor12345

2. Add Registry Endpoint

In Harbor, navigate to Administration → Registries → New Endpoint.

Key	Value
Provider	Harbor
Name	Prod
Description	[optional]
Endpoint URL	https://registry.kubeops.net
Access ID	[registry user]
Access Secret	[registry cli secret]
Verify Remote Cert	true

Note

When creating the Harbor registry endpoint, use the registry URL that matches your environment.

Prod: https://registry.kubeops.net

3. Add Project

In Harbor, navigate to Project → New Project.

Key	Value
Project Name	kubeops
Access Level	false
Project quota limits	-1
Proxy Cache	true
Endpoint	https://registry.kubeops.net

Manage applications with docker compose

1. KOSI Proxy

KOSI Proxy is installed in the folder ~/kosi-proxy.

cd ~/kosi-proxy

# show kosi proxy containers
docker compose ps

# show kosi proxy logs 
docker compose logs -f

# stop kosi proxy
docker compose down

# start kosi proxy
docker compose up -d

2. Harbor

Harbor is installed in the folder ~/harbor.

cd ~/harbor

# show harbor containers
docker compose ps

# show harbor logs 
docker compose logs -f

# stop harbor
docker compose down

# start harbor
docker compose up -d

Kosi: How to template within the package.kosi

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

TBA

Kosi: Create Kosi package

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

Note: This guide requires a KOSI enterprise license.

kosi create

To create a Kosi package, you must first run the kosi create command in your directory.

The kosi create command creates four files (package.yaml, template.yaml, logo.png and docs.tgz) in the current directory. These files can be edited.

kosi create

Created files:

package.yaml - Defines properties of the Kosi package. (see below)
template.yaml - Required if the template engine Scriban is to be used.
logo.png - A package-thumbnail with the size of 50x50px, for showing logo on the KubeOpsHub.
docs.tgz - A zipped directory with the documentation of the package, for showing documentation on the KubeOpsHub.

The documentation of the package is written in markdown. The file for the documentation is called readme.md.
To edit the markdown, you can unzip the docs.tgz in your directory with the command tar -xzf docs.tgz and zip it again with the command tar -czf docs.tgz docs/ after you finished.

Note: Please name your markdown files inside docs.tgz without a version-tag (docs/documentation-1.0.0.md).
Do not change the file names of any of the files above generated with the kosi create command.

package.yaml

The package.yaml defines a package in a specific version as well as the tasks needed to install it. The tasks which are used in the package.yaml are plugins, which can be created by the user.

Elements:

includes.files: Describes the files which are inluded in the Kosi package.
includes.containers: Used for docker images. A container for the docker images will be created when the kosi install, kosi update or kosi delete command is used.
installation.tasks: The tree describes the tasks (Kosi plugins), which are executed with the kosi install command.
update.tasks: The tree describes the tasks (Kosi plugins), which are executed with the kosi update command.
delete.tasks: The tree describes the tasks (Kosi plugins), which are executed with the kosi delete command.

IMPORTANT: It is required to enter the package name in lowercase.
Do not use any docker tags (:v1.0.0) in your package name.

Example package.yaml

apiversion: kubernative/kubeops/sina/user/v4 # Required field
name: kosi-example-packagev3 # Required field
description: kosi-example-package # Required field
version: 0.1.0 # Required field
includes:  # Required field: When "files" or "containers" are needed.
  files:  # Optional field: IF file is attached, e.g. "rpm, .extension"
    input: "template.yaml"
  containers: # Optional field: When "containers" are needed.
    example:
      registry: docker.io
      image: nginx
      tag: latest
docs: docs.tgz
logo: logo.png
installation: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks: 
    - cmd:
        command: "touch ~/kosiExample1"
update: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks:
    - cmd:
        command: "touch ~/kosiExample2"
delete: # Required field
  includes: # Optional field: When "files" or "containers" are needed.
    files: # Optional field:
      - input # Reference to includes
    containers: # Optional field:
      - example # Reference to includes
  tasks:
    - cmd:
        command: "rm ~/kosiExample1"
    - cmd:
        command: "rm ~/kosiExample2"

kosi build

Now, after you created and edited the files from kosi create, you can simply build a Kosi package by just running the kosi build command in your directory.

kosi build

All files specified in the package.yaml are combined together with the package.yaml to form a kosi package.

In these few steps, you can successfully create and use the kosi package. This is the basic functionality offered by Kosi.

You can always explore Full Documentation to go through all the functionality and features provided by Kosi.

KubeOpsDoku – How to Guides

Kosi: How to manually push images to your KubeOps-Registry project space

How to manually push images to your KubeOps-Registry project space

How to get your CLI secret

How to push your image

Kosi: Accessing kubeops-community packages

Searching for Packages

Installing Packages

Examples

Listing Deployed Packages

Updating and Deleting Packages

Updating a Package

Deleting a Package

Kosi: How to install KOSI as a user

Prerequisites

Installation Steps

$KUBEOPSROOT Variable

Check Installation

Kosi: How to use Variables in KOSI Packages

Plugins that set Variables

Referencing Plugin Variables

Example Workflow

Related Plugin Documentation

Kosi: Installing KOSI packages from KubeOps Hub

Install from Private Hub

Install from Public Hub

Install along with yaml files

Install in specific namespace

Install with specific deployment name

Install on a machine with no internet connection

Kosi: How to install and access the Plugins from the Hub

How to access the Plugins

KOSI Basic Plugins Version 1.6.X

KOSI Professional Plugins Version 1.6.X

KOSI Enterprise Plugins Version 1.6.X

How to install the Plugins

Kosi: How to update KOSI

Prerequisites

Update Methods

Method 1: Automatic Update Check via Config

Method 2: Update via Package Repository

Method 3: Manual Update via Download

1. Install KOSI

2. Set the KUBEOPSROOT env var

3. Adjust KOSI Configuration

Verify your Installation

Kosi: How to create SBOM for kosi packages (kosi tools sbom)

How to use KOSI Tools SBOM

Prerequisites

Installing Syft

Usage Options

Available Arguments and Options

Examples

Example output

Example output

Kosi: How to install KOSI Proxy

How to install KOSI Proxy

Architecture

Prerequisites

Install KOSI Proxy

Configure KOSI Proxy (Advanced)

1. Hub Whitelist

Install Harbor

1. Download installer

2. Configure harbor.yml values

3. Run install script:

Configure Harbor

1. Port Forwarding

2. Add Registry Endpoint

3. Add Project

Manage applications with docker compose

1. KOSI Proxy

2. Harbor

Kosi: How to template within the package.kosi

TBA

Kosi: Create Kosi package

kosi create

package.yaml

Example package.yaml

kosi build