KLOTSE

Klotse for developers

Klotse can be extended with plugins, without changing its code. This page covers how plugins work, how Klotse is versioned, and how to run and contribute to the project. For using Klotse, see the user guide.

Work in progressThe plugin API described here is in the git code of this project, not yet in a released version. Names and details may still change, and the bundled cloud plugins have not been tested against real clouds.

Start here

Klotse is a Python desktop application (PySide6 / Qt Widgets). It talks to clusters with the Kubernetes Python client and kubectl. There is no server and no database. You can extend it in two ways:

Plugins

Add columns to the resource lists, right-click actions, Overview cards, settings, per-cluster settings, environment variables for kubectl and terminals, and cluster sources. A plugin is a Python module plus a small JSON manifest, and it runs inside Klotse's process.

Changes to Klotse

Behaviour lives in clear layers: pure logic in src/klotse/k8s/, windows in src/klotse/ui/, and cluster writes in KubeService.

Most extension work is a plugin, so start with Write a plugin.

Run from source

# macOS / Linux: create .venv and install the requirements
./run.sh --install

# Windows
run.bat --install

# Run from the checkout
PYTHONPATH=src .venv/bin/python -m klotse

# Tests (no live cluster needed)
PYTHONPATH=src QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q tests/test_<area>.py
PYTHONPATH=src QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q      # the full suite, about 10 minutes
git diff --check

kubectl must be on the PATH for drain and terminals. Tests use fake services and synthetic objects. They never change a real cluster and never touch the real user settings.

HooksRun pre-commit install once per clone. The hooks check for private keys, run bandit on src and scripts, and check whitespace. They refuse commits to master.

Write a plugin

A plugin is a Python module with a Plugin subclass, plus a JSON manifest beside it. The manifest lets Klotse list the plugin without importing its code. This example adds a zone column to the Nodes list and a "Copy zone" action:

from klotse.plugins import Action, Column, Copy, Plugin


class NodeZone(Plugin):
    id = "node-zone"            # lower case letters, digits, "-" and "_"
    name = "Node zone"
    description = "Shows the availability zone of every node."
    columns = (Column("zone", "Zone"),)
    actions = (Action("copy", "Copy zone", multi=True),)

    def zone(self, resource):
        labels = (resource.raw.get("metadata") or {}).get("labels") or {}
        return labels.get("topology.kubernetes.io/zone")

    def enrich(self, request):
        # runs on a worker thread: no Qt here; it may use the network
        return {resource.key: {"zone": self.zone(resource)} for resource in request.resources}

    def run(self, request):
        return Copy("\n".join(str(self.zone(resource)) for resource in request.resources))


plugin = NodeZone()   # Klotse looks for a module-level `plugin`, or a `register()` function

Save it as node_zone.py, with node_zone.json beside it:

{
  "manifest_version": 1,
  "id": "node-zone",
  "name": "Node zone",
  "description": "Shows the availability zone of every node.",
  "requires_api": 1,
  "columns": [{"key": "zone", "title": "Zone"}],
  "actions": [{"key": "copy", "title": "Copy zone", "multi": true}]
}

The manifest is required. Its ID, name, API requirement and declarations must match the Python plugin. Omitted lists are empty, and omitted fields take their API defaults.

Columns

enrich() returns {resource.key: {column key: value}}. Values are strings, numbers or None. A resource you leave out gets empty cells. Set refresh_s when values go stale, such as prices. Cache anything expensive yourself.

Actions

An action appears in the right-click menu for the kinds you name. run(request) runs on a worker thread and returns one of these:

ResultWhat Klotse does
Message(text, level)Status bar, or a dialog for warning and error
Copy(text)Puts the text on the clipboard
OpenUrl(url)Opens an http or https address in the browser
ShowText(title, text)A read-only tab in Logs & activity
Terminal(argv)Runs a command in the user's terminal
Reload(kinds)Reloads open lists after a change

Set dangerous=True for anything that changes a cluster or something outside it. Klotse then marks the entry with ⚠ and always asks first. This is a label that triggers the question, not a sandbox.

Install and enable

Klotse finds plugins in three places. None runs until the user enables it in Preferences > Plugins.

  1. The plugins folder. .py files, or folders with an __init__.py, in the plugins folder next to Klotse's settings file. A name.py needs name.json beside it, and a package folder needs klotse-plugin.json inside. The Plugins page has buttons to open that folder and to reload.
  2. A pip package. Declare two entry points, klotse.plugins for the code and klotse.plugin_manifests for the JSON, then install it into the same environment as Klotse, for example pipx inject klotse my-klotse-plugin.
  3. Bundled. Plugins the project ships itself, such as AWS, Google Cloud, Azure and Oracle Cloud, in src/klotse_plugins/.
[project.entry-points."klotse.plugins"]
node-zone = "my_klotse_plugin:plugin"

[project.entry-points."klotse.plugin_manifests"]
node-zone = "my_klotse_plugin.klotse_manifest"

[tool.setuptools.package-data]
my_klotse_plugin = ["klotse_manifest.json"]

Discovery reads manifests only. Enabling a plugin imports and checks its code on a worker thread. A plugin that fails to load stays disabled, and the reason is shown. A missing or invalid manifest makes a plugin unavailable without importing it. Its saved settings are kept, and come back when a valid manifest is installed.

API reference

Everything a plugin needs is in klotse.plugins.

NameWhat it is
PluginBase class. Set id, name, description, version, requires_api, columns, actions, settings, cluster_settings, overview_cards, refresh_s. Override enrich() and run(), and optionally applies() and process_environment().
Column(key, title, kinds, format, presets)A column for tables of those kinds. Sorting uses the raw value, so numbers stay numbers.
Action(key, title, kinds, multi, confirm, dangerous)A right-click entry. multi offers it for several selected rows. confirm asks a Yes/No question first.
Setting(key, label, default, kind, help, pattern)A setting shown on the Plugins page. Kinds: text, password, note, multiline, bool. A password is still saved as plain text, like every other setting.
EnrichRequestplugin_id, kind, context, resources, settings, cache_dir, api_client(), warn(text).
ActionRequestplugin_id, action, kind, context, resources, settings, log(line), api_client(), kubectl, cache_dir.
ResourceInfoname, namespace, raw (the full manifest, read-only), key, uid.
parse_environment(text)Turns NAME=value lines into a dict for process_environment().

Cluster sources (API 11)

A plugin that lists the clusters of an account declares a cluster source, and File > Add clusters from the cloud… offers it. The plugin lists clusters and writes one cluster's credentials into a private temporary file. Klotse merges that entry into its own kubeconfig file. The plugin never edits the user's main kubeconfig.

Variables for commands and terminals (API 12)

def process_environment(self, context, settings):
    return {"MY_CLOUD_PROFILE": settings["profile"], **parse_environment(settings["extra_environment"])}

Klotse calls this on the GUI thread each time a kubectl, helm or terminal process starts for the cluster. It must be fast, and must not use the network or read files. Names must match [A-Za-z_][A-Za-z0-9_]*, and values must be one line. Values are never logged or written to the change log.

API versions

The plugin API has its own number, klotse.plugins.API_VERSION, which goes up when the API grows. Each plugin states the lowest version it needs in requires_api. An older Klotse lists such a plugin as not loadable, instead of failing in a strange way.

VersionAdded
1Columns
2Actions
3cache_dir and EnrichRequest.warn
4Multi-line settings
5Overview cards
6Cluster settings
7Password settings
8Required manifests, imports deferred until enabled
9EnrichRequest.api_client()
10Column presets
11Cluster sources
12process_environment()

Set requires_api to the lowest version your plugin needs. The current value is in src/klotse/plugins/api.py.

Versions and releases

  • Klotse's version is one line in src/klotse/_version.py, written as MAJOR.MINOR.PATCH. It changes only in a release pull request, titled Release vX.Y.Z. Contributors do not change it.
  • Tags. Merging the release pull request tags its commit vX.Y.Z. The packaging and PyPI workflows run on version tags.
  • Development builds report the version followed by the commit, for example 0.4.0+g1a2b3c4, so a build from source is easy to tell from a release.
  • The plugin API version is separate from Klotse's version. A release can raise it, and each plugin's own version is up to its author.
  • Releases are made by maintainers only. Publishing is irreversible, so it waits for an explicit go-ahead.

Contribute

  1. Find or open an issue. Search first. Use the enhancement label for features, and an effort: label if you can estimate one. For a large change, agree the approach on the issue first.
  2. Branch from an up-to-date master. Never commit to master directly. Keep one feature or fix per pull request, and do not stack pull requests.
  3. Change the right layer. Read AGENTS.md for the file map and the rules that must not regress: read-only mode, secret masking, the change log and clean shutdown.
  4. Add tests next to the existing ones in tests/test_<area>.py. Run at least the focused tests for your area, and say what you ran in the pull request.
  5. Show UI changes. A pull request that changes what the app looks like includes before and after screenshots taken from the app, embedded by their full commit-pinned URL.
  6. Update the docs in the same pull request when behaviour changes: README.md and the relevant part of AGENTS.md.
  7. Keep line endings. The Windows working tree uses CRLF. Do not convert whole files.
AI-assisted changesWelcome, as long as a person has run and tested them, can answer review questions about every line, and says in the pull request that AI wrote most of it. Never paste secrets, kubeconfig data or real cluster output into issues, pull requests or test fixtures.

Report security problems privately, not as public issues. See SECURITY.md.

Rules that matter

  • Plugins are trusted code. They run in Klotse's process with your permissions and see the manifests of the resources they are asked about. There is no sandbox, so enable only plugins you trust.
  • No Qt in enrich() or run(). They run on a worker thread. Change the window through the returned results, such as Reload.
  • Refreshes are cheap. Klotse asks for each resource once, and asks again only when refresh_s says so or a value was missing. Cache expensive lookups yourself, since one plugin object lives for the whole session.
  • Failures are contained. An exception is shown on the Plugins page and retried after about a minute. It never stops Klotse.
  • Column keys are saved. Plugin columns are saved under plugin:<id>:<key>, so renaming a key resets where users put that column.
  • Settings live in one place. Use the settings store or the plugin's own section, never a hard-coded path. Tests inject a QSettings on a temporary folder.

The full plugin notes, including the AWS plugin's design, are in PLUGINS.md in the repository.