Manage Kubernetes clusters on prepared hosts.
kg turns pools of physical servers or VMs into Kubernetes clusters over SSH. A local genesis node runs Cluster API to create and manage them. Use one genesis node for several clusters, then keep managing them, move management into a workload cluster, or release a cluster to run independently.
The result is an ordinary kubeadm cluster. You choose where its management lives.
| Capability | What you can do |
|---|---|
| Host inventory | Check SSH access, runtime and Kubernetes readiness before deploying |
| Cluster lifecycle | Create clusters, scale worker pools, tear down and reuse hosts |
| Multiple clusters | Manage separate cluster inventories from one genesis node |
| Management handover | Keep clusters managed, move to self-managed, or leave them released |
| Persistent cluster access | List known clusters and query status or export kubeconfigs after handover |
| Availability and rollouts | Use a kube-vip endpoint and spare hosts for CAPI rolling replacements |
kg is for pre-provisioned Linux hosts with SSH, a container runtime and Kubernetes packages already installed. It does not provision operating systems or upgrade host packages. You also supply the CNI manifests. The cluster registry is local to your state directory; it is not a shared fleet database.
Architecture explains the design. Cluster management explains the lifecycle choices.
Download the CLI archive for your operating system and architecture from
GitHub Releases. Verify it against the
release's SHA256SUMS, extract it, and place kg on your PATH:
$ kg versionReleases support macOS and Linux on amd64 and arm64. The machine running kg
needs Docker and SSH reachability to the hosts.
See Installation for exact installation steps, source builds and host requirements.
Prepare the hosts, install kg, and configure your host inventory, Kubernetes version, control plane endpoint and CNI manifests:
$ kg config init
$ $EDITOR ~/.kg/config
$ kg config validate
$ kg inventory check
$ kg init
$ kg cluster create
$ kg kubeconfig
$ kg clusters
$ kg cluster statusThis leaves the cluster managed by its genesis node. For the full walkthrough, see Getting started and the configuration example.
When you are ready to hand it over, choose deliberately:
| Command | Outcome |
|---|---|
kg eject --self-manage |
Move Cluster API into the workload cluster; requires spare hosts and an HA control plane |
kg eject |
Stop Cluster API management while the workload keeps running |
See Cluster management for requirements, limitations and multi-cluster workflows.
Start at the documentation index, or go directly to:
- Installation and Getting started
- Configuration: host inventory, worker pools, CNI, VIP and SSH trust
- Cluster management: multiple clusters, handovers and local records
- Command reference
- Rollout order
- Architecture
- Development and testing: builds, E2E, releases and CI
The same scenario suite runs against container hosts and virtual machines. VM coverage includes VIP failover, self-management and a Kubernetes rolling upgrade. Container runs explicitly skip scenarios that require VM capabilities. See the scenario catalog for assertions and the management acceptance cases; the badges above link to current CI results.
$ make build
$ make testContributor workflows and local VM setup are in Development and testing.
MIT. See LICENSE. Dependencies and vendored assets retain their own licenses; see third-party licensing.