Repository navigation
Getting Started
Documentation snapshot from README.md at commit
20d7c81. Check the current source for updates.
https://dascondor.github.io/kubefactory/
The browser build is a sandbox: it runs the built-in simulated clusters only and
connects to nothing. A browser cannot run kubectl or Docker, so managing real
clusters needs the desktop build below. Every tool works against the simulation,
including Porter's bundled app setups; his online app lists do not load there.
Graphics start light (drawn in code, one shadow pass) so the demo opens at once
on any device. Esc → Graphics → High switches to the real model library
(about 13 MB, fetched once from the same site and checked against the catalog's
checksums), 4x anti-aliasing and softer shadows; the page reloads to apply it,
and ?gfx=high in the address opens it that way. Global illumination and
reflections need the desktop build: WebGL cannot run them. On desktop, click the
page to capture the mouse; touch devices have
on-screen controls. It is rebuilt and redeployed on every push to main by
.github/workflows/pages.yml.
See the mobile guide for touch controls and what the demo looks like when you turn a phone.
Start the simulation (the browser demo, the Demo edition, or --demo) and you
pick a world. Switch any time from the pause menu, or name one up front with
--demo=<id>. In every demo you are signed in as DasCondor.
An explicitly selected desktop demo starts without inspecting kubeconfigs or
probing Docker. To switch to local infrastructure, open Clusters and select
Discover local connections, or add a kubeconfig in the connection wizard.
Simulated actions do not send audit webhooks, and online app lists are disabled
in a demo; Porter's bundled app setups remain available.
--demo= |
World | What is running | What is broken |
|---|---|---|---|
kubernetes |
Kubernetes cluster | a web shop: frontend, cart, checkout, database, monitoring | checkout crash-loops; one image tag is mistyped |
home-assistant |
Home Assistant | Home Assistant, Mosquitto, Zigbee2MQTT, Z-Wave JS, ESPHome, Node-RED, Frigate, voice (Whisper, Piper), MariaDB, InfluxDB, Grafana | Zigbee2MQTT cannot find its USB stick; one image tag is mistyped |
dev-containers |
Dev containers | a build farm: Gitea, CI server and runners, BuildKit, registry, compile cache, and a dev container each for C++, Rust, Go, Python and Node | a heavy C++ build runs out of memory; one image tag is mistyped |
media |
Media suite | Plex, Jellyfin, shared and dedicated VPN gateways, Heimdall, and monitoring |
library-check has a sample image-pull failure and an unavailable service port |
The broken ones are there for Bob: ask him to read the log and he finds the
missing /dev/ttyUSB0 or the compiler killed for memory. The cloud-flavoured
Kubernetes simulations (EKS, AKS, GKE, Rancher) are still at the cluster gates.
2.0.0-beta.2 is the current pre-release. The latest stable build (1.0.1, Windows only) and every earlier version are on the Releases page.
| Platform | Download | Start it |
|---|---|---|
| Windows | .zip, 59 MB |
install.ps1 or KubeFactory.exe
|
| Linux x86_64 | .tar.gz, 51 MB | ./KubeFactory.x86_64 |
| macOS (Apple Silicon, Intel) | .zip, 91 MB |
KubeFactory.app (below) |
Checking a download. Every package has a .sha256, the release has one
SHA256SUMS, and every package carries a signed build-provenance attestation
that ties it to this repository's release workflow and the exact commit:
gh attestation verify KubeFactory-2.0.0-beta.2-linux-x86_64.tar.gz -R DasCondor/kubefactoryNone of the packages is signed with a Windows or Apple developer identity yet. Windows signing is free through SignPath Foundation once the project is approved (CODE_SIGNING); until then Windows SmartScreen asks for confirmation on first run. On macOS the app is ad-hoc signed but not notarized, so Gatekeeper blocks a downloaded copy until you clear the quarantine flag on the unpacked folder:
xattr -dr com.apple.quarantine KubeFactory-2.0.0-beta.2-macosLinux: unpack KubeFactory-<version>-linux-x86_64.tar.gz and run
./KubeFactory.x86_64 from that folder. macOS: unzip, clear the quarantine
flag (above), and open KubeFactory.app; keep the other files beside it. On
both, the options below work the same way (./KubeFactory.x86_64 -- --demo).
Windows: unzip KubeFactory-<version>-win64.zip, then:
powershell -ExecutionPolicy Bypass -File install.ps1That installs for the current user (no admin rights) to
%LOCALAPPDATA%\Programs\KubeFactory and adds Start Menu entries: KubeFactory,
KubeFactory (simulation) and KubeFactory (read-only). -Quiet skips the desktop
shortcut for IT rollouts. Upgrading keeps your edited config files.
uninstall.ps1 removes it (-Purge also removes settings and audit logs).
You can also just run KubeFactory.exe from the unzipped folder.
Command-line options go after --:
| Command | Does |
|---|---|
KubeFactory.exe --kubeconfig <file> |
connect to the cluster in that kubeconfig (YAML or JSON) |
KubeFactory.exe -- --demo |
built-in simulated cluster (safe to break) |
KubeFactory.exe -- --sim=aws-eks-prod |
or azure-aks-staging, gke-analytics, rancher-edge
|
KubeFactory.exe -- --context=<name> |
a specific kubeconfig context |
KubeFactory.exe -- --read-only |
look, don't touch |
KubeFactory.exe -- --docker --context=<n> |
a Docker host, by its Docker context |
KubeFactory.exe -- --remote=wss://host:7666 |
a KubeFactory server (token in KF_REMOTE_TOKEN) |
KubeFactory.exe --headless -- --server |
be a server for the others (SERVER) |
KubeFactory.exe -- --kubectl-cli |
use kubectl instead of the built-in client |
With no options it connects to your current kube context, then Docker, then the
simulation. KubeFactory.console.exe is the same game with a console window,
for troubleshooting. check-requirements.ps1 checks for the optional cloud CLIs.
The same game also comes in two narrower builds. They install side by side with
the full game (KubeFactory Docker, KubeFactory Demo).
| Edition | Opens on | Never touches |
|---|---|---|
| KubeFactory Docker | your local Docker engine: every container is a machine, Compose projects are namespaces | kubectl / any Kubernetes cluster |
| KubeFactory Demo | the built-in simulated clusters, with every tool unlocked | kubectl and Docker: it connects to nothing |
The Docker edition falls back to the simulation while the Docker engine is not
running. Build them with tools\package.ps1 -Edition docker / -Edition demo, or
run them from source with play.bat --edition=docker / --edition=demo.
| Command | Does |
|---|---|
tools\setup.ps1 |
checks / installs the software below (including the engine) |
play.bat |
starts the game; same options as above, without the leading --
|
play.bat --edition=docker or demo
|
the Docker or Demo edition |
tools\package.ps1 |
runs the tests and builds the release zip and checksum in dist (-Edition docker or demo builds that edition) |
tools\dev-cluster.ps1 |
a 3-node Kubernetes cluster in Docker containers (kind), with sample workloads, two of them broken on purpose |
tools\dev-cluster.ps1 -Delete |
removes it |
tools\dev-users.ps1 |
multi-user setup and two test logins on that cluster |
| Software | Needed for | Install |
|---|---|---|
Godot 4.3 (portable, in engine\) |
running the game |
tools\setup.ps1 downloads it |
| Go 1.25+ | building the companion from source (tools\build-agent.ps1; -Fetch gets a private copy) |
winget install GoLang.Go |
| Microsoft Edge or Google Chrome | LiveView | Edge ships with Windows |
| kubectl | optional: only for --kubectl-cli and the admin commands in docs/ADMIN.md
|
winget install Kubernetes.kubectl |
| Docker Desktop | local containers, dev cluster | winget install Docker.DockerDesktop |
| kind | dev cluster in Docker | winget install Kubernetes.kind |
| AWS CLI | EKS login, CloudWatch logs | winget install Amazon.AWSCLI |
| Azure CLI + kubelogin | AKS login, Azure Monitor logs | winget install Microsoft.AzureCLI Microsoft.Azure.Kubelogin |
| Google Cloud SDK + gke-gcloud-auth-plugin | GKE login, Cloud Logging | winget install Google.CloudSDK |
| curl (ships with Windows) | Grafana Loki logs | - |
Rancher needs nothing extra: download the cluster's kubeconfig from the Rancher UI.
tools\setup.ps1 -Cloud installs the three cloud CLIs.
Start
Visual guides
Operations
- Storage and screens
- LiveView
- Krew and Foreman
- Porter and Bob
- Text editor
- Logs
- Teams
- Administration
- Server mode
- Docker hosts
- Security
- Known limitations
Development and reference