KubeKey: Kubernetes Cluster Installer Tool
KubeKey is a command-line tool for installing Kubernetes clusters, built by the KubeSphere project and put through CNCF's Kubernetes Conformance Certification. It handles all-in-one, multi-node, and HA layouts, and installs cloud-native add-ons alongside the cluster. Reach for it if you need a scriptable, Ansible-style installer for on-prem or offline Kubernetes; skip it if a managed cloud service already provisions clusters for you.
Understanding KubeKey's Role
KubeKey is a Go-based, open-source tool from the KubeSphere project that runs task flows to install Kubernetes, small enough to ship as a single binary. Version 3.x turned it from a narrower Kubernetes lifecycle-management tool into a general task execution tool whose flow design the README says is modeled on Ansible, with task templates stored in git or locally and multiple node connection methods including SSH and Kubernetes itself.
Key Capabilities of KubeKey
- โDeploys three cluster topologies from one tool: all-in-one, multi-node, and HA, per the repo description.
- โPassed CNCF's Kubernetes Conformance Certification, per the README.
- โ3.x rebuilt KubeKey around a task execution engine whose flow design the README says references Ansible, rather than the narrower lifecycle-management tool earlier versions were.
- โTask templates can be managed from git or local storage, so a cluster definition can live in version control.
- โConnects to nodes over local, SSH, Kubernetes, or Prometheus connections, per the README's node-connection list.
- โInstalls cloud-native add-ons alongside the cluster instead of leaving that to a second tool.
- โShips a `kk web` command for a browser-based installer UI, supported from v4.0.0 onward per the README.
Scenarios for KubeKey Deployment
- โขProvisioning an HA Kubernetes cluster on your own servers when you don't have a managed control plane to lean on.
- โขRunning an offline install, since the README documents a dedicated offline-installation doc and an offline package build script (package.sh).
- โขManaging cluster lifecycle tasks (creating, adding nodes, deleting nodes, renewing certificates) through the playbooks the README lists under docs/en/reference/playbooks.
- โขKeeping infrastructure definitions in git by storing KubeKey's task templates there instead of only locally.
- โขInstalling KubeSphere's own add-ons or other cloud-native components as part of the same run that creates the cluster.
Getting Started with KubeKey
Two paths are documented: pull a prebuilt binary from the project's GitHub Releases page, or run `curl -sfL https://get-kk.kubesphere.io | sh -` to fetch it directly. The downloaded archive (kubekey-v4.x.x-linux-amd64.tar.gz) extracts to the `kk` binary; a separate web-installer.tgz bundle holds the Web UI assets, task template files, schema configs, and a README with installation instructions, plus a package.sh script for building an offline package.
Deploying Kubernetes with KubeKey
The command-line path is `./kk create cluster`, which reads a task template and runs it against your nodes. From v4.0.0 on, `./kk web --schema-path web-installer/schema --ui-path web-installer/dist` starts the browser-based installer using the schema and UI assets that ship in web-installer.tgz. Beyond cluster creation, the README's playbook docs cover add-nodes, delete-nodes, cert renewal, offline-artifact export, a pre-installation check, and OS initialization as separate playbooks rather than flags on the create command.
Strengths
- โHandles three deployment topologies (all-in-one, multi-node, and HA) from a single binary instead of separate tools per topology.
- โCNCF Conformance Certification is documented in the README, a specific, checkable claim rather than a vague quality claim.
- โCloud-native add-ons install through the same run as the cluster, per the description, instead of needing a second tool.
- โOffline installation is a documented, first-class path (docs/en/installation/offline.md, package.sh), not an afterthought bolted onto an online-only installer.
- โTask templates can live in git, so cluster definitions are versionable the same way application code is.
- โApache-2.0 license, no proprietary strings attached.
Current KubeKey Limitations
- โณThe web UI only works from v4.0.0 onward, per the README, so anyone on an older release is CLI-only.
- โณThe README's own 3.x feature list flags the UI page as 'not yet open' at that point, which suggests the web UI has a shorter track record than the CLI path.
- โณNo specific list of supported OS distributions, Kubernetes versions, or minimum node specs appears in the provided README text; check docs/en/installation/components.md before planning a rollout.
- โณKubeKey's task execution framework is its own design; the README says the flow only 'refers to' Ansible for inspiration, so it isn't a fork or wrapper of Ansible itself.
- โณNo version number or release cadence is stated in the facts provided here, so there's no documented timeline for when features move from 3.x to 4.x.
KubeKey Alternatives for Cluster Management
KubeKey Frequently Asked Questions
KubeKey is released under the Apache-2.0 license, as listed on its GitHub repository.
KubeKey documents offline installation directly, with a dedicated guide at docs/en/installation/offline.md and a package.sh script for building an offline package.
KubeKey's own description says it installs Kubernetes 'and related cloud-native add-ons,' and its task model is built for cloud-native automated batch task management.
KubeKey has had a web UI since version 4.0.0. Running `./kk web --schema-path web-installer/schema --ui-path web-installer/dist` starts it, using assets bundled in web-installer.tgz.
KubeKey deploys all-in-one, multi-node, and HA (high-availability) Kubernetes clusters, per its GitHub repo description.
KubeKey runs its own task execution framework, built around Project, Playbook, Role, and Task concepts, whose flow design the README says takes inspiration from Ansible without being Ansible itself.
The problem it solves
Standing up a Kubernetes cluster outside a managed cloud service usually means hand-rolling kubeadm commands across every node, or adopting a full configuration-management stack just to sequence the steps. KubeKey packages that sequencing into one binary. It runs a task flow closer to an Ansible playbook than a wrapper script, provisioning all-in-one, multi-node, or HA clusters and layering on cloud-native add-ons without a separate provisioning tool.
Who should try it โ and who should skip
Reach for KubeKey if you're standing up Kubernetes on your own servers, bare metal, VMs, or air-gapped, and want one binary that handles all-in-one, multi-node, or HA layouts plus add-ons, with git-backed task templates. Skip it if you're deploying on a managed Kubernetes service like EKS, GKE, or AKS, where the cloud provider already runs cluster provisioning for you, or if you need to reuse an existing library of Ansible playbooks, since KubeKey's task framework is its own design.
Related repositories
Curious whether kubekey is right for you?
Let ChatGPT, Claude, or Perplexity look into it โ click below and see what AI actually says about kubekey.