Engines and clusters
Kontena talks to two kinds of thing, and the switcher in the top bar moves between them.
- Container engines — Docker and Podman. They run containers on a machine: yours, or one you reach over SSH or TLS.
- Clusters — Kubernetes contexts. They schedule work across nodes; you tell them what should exist, not what to start.
Both are backends. Picking one decides what the whole app shows: an engine gives you Containers, Images, Volumes and Networks; a cluster swaps the sidebar for a Kubernetes resource tree and puts a namespace picker in the command bar. The switcher groups them under Container engines and Clusters · Orchestrators, so it is always clear which world you are in.
The backend is an implementation detail, not a lifestyle choice. Switching does not mean switching apps, and nothing you learned about one page stops being true on the other.
Why Docker and Podman are equals#
Every engine sits behind one contract: the Container Engine Abstraction Layer, the CEAL. The UI never talks to Docker or Podman directly — it talks to the CEAL, and an adapter maps that onto the engine underneath. Clusters have the same arrangement one level up, in the orchestration layer.
This is why neither engine is the "real" one with the other as a fallback. Adding a backend means writing an adapter, not touching the pages: Docker and Podman are both just adapters, and so is the in-memory fake used in development.
The rule the adapters follow is model the union, expose the intersection cleanly, degrade gracefully at the edges. Everything below is what that means when you are using the app.
Capabilities: why a button is missing#
Engines do not support the same things, and neither do clusters. Rather than offer everything and fail at the point of use, each backend advertises what it can do and the UI adapts.
An engine answers for
Rootless operation, building images, Compose projects, exec, prune, browsing a volume, GPU passthrough, live stats, and the event stream.
A cluster answers for
A metrics-server, exec into pods, port-forwarding, the apply/dry-run flow, Helm, watch streams, and browsing CRDs.
So a greyed-out or absent action is information, not a bug: this backend does not do that. Live CPU and memory on a cluster's pods need a metrics-server — no metrics-server, no strip. Workload actions are offered where the kind and the cluster support them, and nowhere else.
It also explains something you will notice on the event-driven pages: lists that refresh themselves without polling do so because the backend streams events. Where it does not, the same page still works, just without that.
How backends get there#
The two kinds are found in deliberately different ways.
Engines are detected. They are on your machine and there are only ever a few, so Kontena scans for them and adds what it finds — at first run, and as you start and stop them if auto-detection stays on.
Clusters are chosen. A kubeconfig collects contexts over time, often other people's, and listing all of them puts production one click away from a scratch cluster. New contexts are announced in the switcher rather than added; you tick the ones you want in Settings › Engines › Clusters, and a cluster you did not choose is never contacted.
Both can also be added by hand from Add engine or cluster… in the switcher, which walks through a remote Docker over SSH or TLS, or a kubeconfig and the contexts inside it. The last step is the connection itself, so the wizard ends in something that actually works — nothing is stored before that.
A kube-context is listed under whatever its cluster calls it, which is routinely something
like gke_myproject-prod_europe-west4_cluster-1. Settings › Engines has a name
field per backend, and the name you give is used everywhere the old one was — switcher,
window title, engine list, and the messages about not being able to reach it.
What a backend owns#
A backend is more than a connection: it is the scope for anything that only makes sense against that one. Port forwards are remembered per backend, because a forward means nothing on another cluster. Registry logins, pins and the "what was I on last" that Kontena reopens with all hang off the same identity — which is why editing a remote engine keeps its identity rather than replacing it, and why a typo used to cost you all of that before Edit existed.
When a backend is not there, Kontena says which one and why, in terms that fit what it is: an apiserver that did not answer reads differently from an expired token, a rejected certificate or a stopped socket. A remembered backend that no longer exists — a context removed, an engine uninstalled — is reported as gone and forgotten, instead of offering a reconnect that can never succeed.