Skip to content

Connections

DasCondor edited this page Nov 15, 2026 · 2 revisions

Connections

Documentation snapshot from README.md at commit 20d7c81. Check the current source for updates.

🔌 Connecting to a cluster (no kubectl needed)

Important

2.0 is in beta (2.0.0-beta.2). Connecting, managing and storage inspection are verified on a real cluster with running containers (kind) and on a real Docker engine; a user reports k3s working. Not yet tried: any cloud provider, a real AI provider behind Foreman, LiveView on a real application through a port-forward, playing the game against a real Komodo, a physical controller, and a server reached from another machine. On a Mac (Apple Silicon) the game starts and the companion answers; it has not been played there, and an Intel Mac is untried. See docs/KNOWN_LIMITATIONS.md, and docs/GO_LIVE_2.0.md for what is left before 2.0.0.

The short version:

  1. Download and unzip KubeFactory.
  2. KubeFactory.exe --kubeconfig <kubeconfig.yaml or kubeconfig.json>
  3. Done: you are standing in that cluster.

Nothing to install first, no kubectl, and the file is only read, never copied or saved. --kubeconfig=<file> works too, and so does dropping the file on KubeFactory.exe. It uses the file's current context (or its first); add -- --context=<name> to pick another. If the cluster cannot be reached the game says why in plain words and offers the simulation.

KubeFactory ships a small companion program, kf-agent.exe, that reads your kubeconfig and talks to the cluster itself. You do not need kubectl.

Open the connection wizard from the cluster list (Add or manage kubeconfigs...), or just drop a kubeconfig file on the window. It:

  • finds ~/.kube/config and anything in KUBECONFIG, and lists the contexts;
  • takes a file, a dropped file or pasted text (pasted text is kept in your user folder, never in the game folder);
  • tells you how each context signs in (certificate, token, or a helper program) without ever showing the secret;
  • asks before running a sign-in helper such as aws or gke-gcloud-auth-plugin. Nothing named in a kubeconfig runs until you approve that exact command;
  • says what went wrong in plain words: cannot reach the server, certificate not trusted, sign-in refused or expired, not permitted.

Docker hosts, read-only, without root

Every Docker CLI context is a connection of its own on the cluster list, so several Docker hosts are several connections (-- --docker --context=<name> picks one at start). A context on another machine opens read-only. To make the host itself refuse changes, and to avoid giving anything root (Docker access is root), run the read-only proxy in deploy/docker-readonly/ on each host and reach it over an SSH tunnel as an ordinary user: docs/DOCKER_HOSTS.md.

A KubeFactory server: play like a game client

Run KubeFactory once as a server beside your cluster (--headless -- --server) and everyone else connects to it (Esc > Switch cluster > KubeFactory server...) with a token: no kubeconfig or Docker access on their machines. Viewers only look; operators act up to MK.4; the server checks every request and logs it. See docs/SERVER.md.

Backend plugins

New kinds of sources can be added as plugins: separate programs, in any language, that report machines over a small JSON protocol. A plugin runs only once you trust it (tied to a hash of its files) and can only look unless you also allow changes. See docs/PLUGINS.md and examples/plugins/static-world.

Komodo (read-only)

Using Komodo for your Docker hosts? Esc > Switch cluster > Komodo..., enter the Core's address and an API key and secret (Komodo: Settings > API keys; a read-only key is enough). Every server becomes a platform and every container a machine, and the Krew reads them. KubeFactory sends Komodo only read requests (GetVersion, ListServers, ListAllContainers, or ListAllDockerContainers on a Core older than 2.3), never /write or /execute, and offers no actions on a Komodo connection: changes stay in Komodo. The key and secret are sealed by the companion and never shown again.

Clone this wiki locally