This is the multi-page printable view of this section. Click here to print.
In the following sections, you will find everything from initial setup and configuration, to advanced tips and tricks that will help you get the most out of the software. Our aim is to assist you in becoming proficient with kosi, enhancing both your productivity and your user experience.
Lets get started on your journey to mastering kosi!
To manually push container images into your KubeOps-Registry project space, you need to use your Harbor CLI secret for authentication when using podman.
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.
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:latestormy-app:v1.12.1. When KOSI pushes the package, it rewrites the image reference in the package to the pushed registry image underregistry.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
This documentation describes how to search for, install, and manage packages from the kubeops-community hub using the Kosi CLI.
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.
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>
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
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 | PublicHub | 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 |
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.
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
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
This guide explains how to install KOSI as a user. KOSI can only be downloaded from our official website.
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.
max_user_namespaces) is configured correctly. For more details, refer to this GitHub tutorial.
Install on RHEL9:
sudo dnf install podman
Download the KOSI RPM:
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
<path_to_rpm> with the directory path where the file is located.<kosi_file_name> with the exact RPM file name (including the .rpm extension).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/
deployment.yaml.
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 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).
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>.
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']";
);
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
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.
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
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
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
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
--namespaceparameter is specified, the default namespace will be used.
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.
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]
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 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 |
| 1.6.0 |
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 |
| 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 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 |
| 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 |
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.
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.
Before you begin, make sure the following prerequisites are met:
| 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 |
Refer to the Helm Official Documentation for the Installation Guide.
For KOSI versions, you must have Podman installed on your machine.
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
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).
You have multiple options to update KOSI, depending on your system setup and preferences.
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
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
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.
# 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/
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.
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)
hub: https://dispatcher.kubeops.net/v4/dispatcher/</a>.plugins: /home/<yourUser>/kubeops/plugins, where .rpm or .deb extension).
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
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.
kosi tools sbom can only be used by a privileged user (root) and in a non-airgap environment.
Before you begin, make sure the following prerequisites are met:
Supported Operating Systems: KOSI tools are tested and supported on the following operating systems:
Syft Installation: To execute the sbom command, you must have Syft installed on your machine.
A privileged user (root) and a non-airgap environment.
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
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
The command syntax for generating an SBOM is as follows:
kosi tools sbom [options] [<package>]
| 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. |
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
# 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
# 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
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.
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.
To install the KOSI Proxy, you need a dedicated VM running RHEL9 OS and root access.
The minimum VM requirements are:
The following software must be installed on this VM:
# 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.preprod.kubeops.net/rpm/kosi-2.15.0.4_Alpha4-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.preprod.kubeops.net/v4/dispatcher/ # <- set hub
plugins: /var/kubeops/plugins/
workspace: /tmp/kosi/process/
logging: info
housekeeping: false
proxy: false
checkforupdates: false
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
# Preprod config values
proxyPassthrough: preprod
proxyRegistry: registry.preprod.kubeops.net
aspnetcoreEnvironment: Development
# Prod config values
#proxyPassthrough: prod
#proxyRegistry: registry.kubeops.net
#aspnetcoreEnvironment: Production
Use the values for the environment you are deploying to.
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_Alpha4
# kosi login with your user
kosi login -u <user>
# install kosi proxy with values.yaml
kosi install --hub kubeops kubeops/kosi-proxy:2.13.0.1_Alpha7 -f values.yaml
Start the KOSI Proxy:
cd ~/kosi-proxy
docker compose up -d
The KOSI Proxy is already configured during installation; however, you can adjust additional parameters if needed.
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.preprod.kubeops.net/v4/download/",
"GuestQuota": 1000000,
"HubWhitelist": "kosi, kubeops, kosi-enterprise"
}
}
Harbor is used as the registry endpoint in this setup.
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
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
cd ~/harbor
./install.sh
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:
In Harbor, navigate to Administration → Registries → New Endpoint.
| Key | Value |
|---|---|
| Provider | Harbor |
| Name | Preprod |
| Description | [optional] |
| Endpoint URL | https://registry.preprod.kubeops.net |
| Access ID | [registry user] |
| Access Secret | [registry cli secret] |
| Verify Remote Cert | true |
When creating the Harbor registry endpoint, use the registry URL that matches your environment.
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.preprod.kubeops.net |
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
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
Note: This guide requires a KOSI enterprise license.
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:
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 commandtar -xzf docs.tgzand zip it again with the commandtar -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 thekosi createcommand.
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.
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"
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.