KLOTSE

Klotse, a calmer way to read your clusters

Klotse is a desktop manager for Kubernetes. It uses the kubeconfig you already have, shows each cluster you open in its own tab, and checks every change with the cluster before it is saved.

This guide walks through the main windows, with pictures. The data in the screenshots is invented.

The main window. Clusters are on the left, the open cluster is in the tabs, and the Details pane is on the right.

1. Start and connect

Nothing connects when Klotse starts. You choose which clusters to open.

  1. Start Klotse. It reads your kubeconfig (the KUBECONFIG variable, or ~/.kube/config).
  2. Right-click a cluster in the list and choose Connect, or double-click it.
  3. Work in the tab. Each open cluster has its own tab and its own connection.
  4. Quit normally. Answer Yes to remember the open clusters for next time.
Before you startkubectl must be on your PATH for drain, shells, attach and port forwards. Klotse uses the same authentication helpers as kubectl.

Using a different kubeconfig? Open Edit > Preferences > General and choose it there. Klotse closes open clusters after you confirm.

2. Clusters and the navigator

The cluster list on the left keeps connected clusters at the top. Use it to find, group and rename clusters.

Switch fast

The drop-down above the list switches between open clusters. It shows each cluster's alias.

Search

The search box filters the list. The button beside it shows or hides the box.

Group

Right-click the list to make groups and move clusters into them. Suggest groups… does it by name.

Alias

Rename alias… gives a cluster a friendly name. The real context name stays the same.

TipThe cluster menu appears on the cluster's own row. Connect, Disconnect, Rename, Move to group, plugin settings and Metrics source all live there.

3. Views, tables and filters

Every kind of object has a view: pods, deployments, nodes, services, secrets, events and more. Tables are built to be scanned.

A filter expression such as Restarts > 3 and kind = pod*. A bad expression filters nothing and says why.
  • Sort by any heading. Age sorts by real time, so 1d comes before 8h.
  • Select several rows with Ctrl or Shift. Bulk actions apply to the selection, after one confirmation.
  • Right-click a cell to copy it or to filter by it.
  • Double-click a pod to open it, a container for its logs, or a node for its pods.
  • Columns… shows, hides and reorders columns, and adds label columns. Your choice is saved.
  • Refresh is automatic for workloads and nodes. Other lists reload on Refresh, or when you switch refresh on for them.

4. The Details pane

Select an object and its details open on the right. You can switch between four views, and every kind has the YAML view, even kinds with no summary.

The YAML view of a Deployment. Search it, copy it or wrap its lines.

Summary

A readable view for workloads, networking, RBAC and more.

YAML

The full object. Secrets stay masked until you choose to decode a key.

Events

What the cluster recorded about the object. These are kept for about an hour.

Related

Owners, what the object owns, and what it uses. Click one to go there.

In a narrow pane the buttons scroll sideways, so every view stays reachable.

5. Changing things safely

Klotse asks before it changes anything, and it checks each change with the cluster first.

Review before saving

Edit as a form or as YAML. Review changes shows the diff, after a server dry run.

Apply YAML

Paste or open manifests and check them with the server. Klotse never forces a conflicting field.

Scale and restart

Type a number, or *2, +1. Restarts roll the workload after you confirm.

Nodes

Cordon, drain and delete a node object. Deleting a node does not remove its machine. Drain asks before it bypasses disruption budgets.

Change log

View > Operations > Change log… lists what you changed from Klotse. It stores identity only, never content or Secret values.

Read-only modeTurn it on per cluster with View > Read-only mode. Klotse then refuses every change it would make, while looking stays allowed. It guards the Klotse window; it does not limit a terminal you open yourself.

6. Pods, logs and terminals

  • Logs for a container, with wrap, timestamps and the previous instance.
  • Logs of all pods… follows every pod of a workload in one tab (up to 40 streams).
  • Shell and Attach open a terminal in the container. Windows, macOS and Linux each use their own terminal. An embedded terminal is in Preferences, off by default.
  • Debug adds an ephemeral container. It stays on the pod until the pod is deleted.
  • Terminate and Force terminate (zero grace period, which can remove the object early).

7. Usage history and metrics

See CPU and memory for a pod, node or workload, and ask Prometheus or VictoriaMetrics questions, without opening a graph tool.

Usage history. With only metrics-server, the chart starts when the window opens and is not kept after you close it.

Usage history

  • Right-click an object and choose Usage history….
  • Source… picks Prometheus or VictoriaMetrics, through the API server or a port-forward.
  • Test checks the source before you press OK. OK keeps the connection Test started. Cancel closes it.

Metrics query

  • Right-click an object and choose Metrics query…. The presets fill in CPU, memory, network, restarts and replica counts.
  • Run adds rows below the earlier ones, each with the time it was sampled. Clear empties the table.
  • Repeat runs the query every 5 seconds to 5 minutes. Graph draws it over 15 minutes to 24 hours.
The Metrics query window. Each run adds rows; the graph draws the query over the range you choose.
metrics-server is limitedIt gives current CPU and memory for pods and nodes. It cannot run queries, and it has no network or replica data. Those come from Prometheus or VictoriaMetrics.

8. Port forwards

Port forwards open a pod or service on this computer. They listen on 127.0.0.1 only.

The Port forwards tab: state, address, and who started each forward.
  • Port forward… on a pod or service starts a forward.
  • Save forward keeps a forward so you can start it again with the same ports.
  • Open in browser opens http://127.0.0.1:<port>.
  • Closing the tab or the cluster stops every forward.

9. Insights

Look, don't touch: these windows only read.

Health check: crash loops, missing limits, latest tags and more. Each finding is advice, not a verdict.

RBAC lookup

Who can do something, and what a user or service account can do.

My permissions

What you may do in a namespace, with a Can I? check.

Right-sizing

Requests and limits compared with current usage.

Trivy and Helm

Vulnerability reports from the Trivy Operator, and Helm releases.

10. Command palette and shortcuts

Press Ctrl+K (Cmd+K on a Mac) and type a few letters. The palette finds views, namespaces, clusters and every enabled menu action.

Type pod and the views that match it are listed. Enter opens the top one.
  • Ctrl+K opens the palette.
  • Ctrl+Shift+F searches objects across the cluster.
  • The menu bar lists every other shortcut beside its item.

11. Preferences

Open Edit > Preferences. Settings are stored in your user settings folder, and Open config folder shows where.

General

Kubeconfig, usage-history SSL and certificate defaults, metrics-query autocomplete, and a timing log for slow loads.

Terminal

The macOS terminal (Terminal or iTerm2) and the embedded terminal.

Plugins

Optional plugins, such as the AWS plugin for node details. Off until you enable them.

12. Multi-cloud (work in progress)

Work in progressMulti-cloud is not in a released version yet. It is only in the git code of this project, so you can use it by running Klotse from source. Its cloud sign-in and cluster listing have not been tested against real AWS, Google Cloud, Oracle or Azure accounts, and the details may still change.

Klotse can list the clusters of a cloud account and add them to your kubeconfig. Cloud plugins add a few things for nodes: their cloud details, console links and sign-in. Every plugin is off until you turn it on in Edit > Preferences > Plugins.

File > Add clusters from the cloud… lists the clusters of an enabled plugin. Tick the ones you want. The names here are invented.
  1. Enable a cloud plugin in Preferences > Plugins: AWS, Google Cloud (GKE), Azure (AKS) or Oracle Cloud (OKE).
  2. Choose File > Add clusters from the cloud… and fill in the region, and the profile if you use one.
  3. List clusters, tick the ones to add and press Add selected clusters.

The clusters go into klotse-cloud.klotse in your .kube folder, which Klotse reads with your other kubeconfig files. Klotse can write them into your main kubeconfig instead, but only when you turn that on in Preferences (off by default), and it keeps a backup first.

AWS

Lists EKS clusters. Node columns show the instance, type, capacity, AMI and price. Estimates the cost of the selected nodes. Sign-in runs aws sso login in a terminal.

Google Cloud

Sign-in for a GKE node, through gcloud auth login in a terminal. Cluster listing and columns are not there yet.

Oracle Cloud

Sign-in for an OKE node, through oci session authenticate. Cluster listing and columns are not there yet.

Azure

Sign-in for an AKS node, through az login. Cluster listing and columns are not there yet.

CredentialsKlotse uses the cloud's own command-line tool and its sign-in. A cloud profile is the safer choice. The AWS plugin can also keep an access key in Klotse's settings, but that key is stored as plain text, so use a dedicated read-only key if you do.
Tested so farThe project's tests use fake cloud tools and invented data. Nothing has been run against a real cloud account yet.

13. Help and troubleshooting

A cluster will not connect

Check that the kubeconfig context works in kubectl, and that the authentication helper it names is installed. The error says which step failed, and Retry tries again.

A list says "forbidden"

Your account has no permission for that kind. View permissions shows what you can do.

Usage history shows only metrics-server

No Prometheus or VictoriaMetrics source answered. The status line under the chart says which service failed and why. Choose a source with Source….

A port forward fails

The Port forwards tab shows kubectl's own words. For "port in use", leave the local port empty so Klotse picks a free one.

Something feels slow

Turn on the timing log in Preferences and send the timings.log file. It holds names, counts and seconds only.