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.
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.
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:
| Result | What 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.
- The plugins folder.
.pyfiles, or folders with an__init__.py, in thepluginsfolder next to Klotse's settings file. Aname.pyneedsname.jsonbeside it, and a package folder needsklotse-plugin.jsoninside. The Plugins page has buttons to open that folder and to reload. - A pip package. Declare two entry points,
klotse.pluginsfor the code andklotse.plugin_manifestsfor the JSON, then install it into the same environment as Klotse, for examplepipx inject klotse my-klotse-plugin. - 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.
| Name | What it is |
|---|---|
Plugin | Base 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. |
EnrichRequest | plugin_id, kind, context, resources, settings, cache_dir, api_client(), warn(text). |
ActionRequest | plugin_id, action, kind, context, resources, settings, log(line), api_client(), kubectl, cache_dir. |
ResourceInfo | name, 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.
| Version | Added |
|---|---|
| 1 | Columns |
| 2 | Actions |
| 3 | cache_dir and EnrichRequest.warn |
| 4 | Multi-line settings |
| 5 | Overview cards |
| 6 | Cluster settings |
| 7 | Password settings |
| 8 | Required manifests, imports deferred until enabled |
| 9 | EnrichRequest.api_client() |
| 10 | Column presets |
| 11 | Cluster sources |
| 12 | process_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 asMAJOR.MINOR.PATCH. It changes only in a release pull request, titledRelease 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
versionis up to its author. - Releases are made by maintainers only. Publishing is irreversible, so it waits for an explicit go-ahead.
Contribute
- Find or open an issue. Search first. Use the
enhancementlabel for features, and aneffort:label if you can estimate one. For a large change, agree the approach on the issue first. - Branch from an up-to-date
master. Never commit tomasterdirectly. Keep one feature or fix per pull request, and do not stack pull requests. - Change the right layer. Read
AGENTS.mdfor the file map and the rules that must not regress: read-only mode, secret masking, the change log and clean shutdown. - 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. - 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.
- Update the docs in the same pull request when behaviour changes:
README.mdand the relevant part ofAGENTS.md. - Keep line endings. The Windows working tree uses CRLF. Do not convert whole files.
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()orrun(). They run on a worker thread. Change the window through the returned results, such asReload. - Refreshes are cheap. Klotse asks for each resource once, and asks again only when
refresh_ssays 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
QSettingson a temporary folder.
The full plugin notes, including the AWS plugin's design, are in PLUGINS.md in the repository.