Cluster API brings declarative, Kubernetes-style APIs to cluster creation, configuration and management.
BYOH is a Cluster API Infrastructure Provider for already-provisioned hosts running Linux. This provider allows operators to adopt Cluster API for deploying and managing kubernetes nodes without also having to adopt a specific infrastructure service. This enables users to decouple kubernetes node provisioning from host and infrastructure provisioning.
Host - A host is a running computer system. It could be physical or virtual. It has a kernel and some base operating system
BYO Host - A Linux host provisioned and managed outside of Cluster API
BYOH Capacity Pool - A set of BYO Hosts registered in a management cluster & authorized for usage as a capacity for deploying Kubernetes nodes
Kubernetes Node - A Kubernetes Node that runs on top of a Host. There is a 1-to-1 relationship between nodes and hosts (every host has zero or one nodes). Node provisioning and lifecycle management is a Cluster API responsibility
Kubernetes Host Components - The components that run uncontainerized on the host and are required to bootstrap a Kubernetes node. Typically, this is at least kubelet, containerd and kubeadm, but different OS might require different components in this category
- Native Kubernetes manifests and API
- Support for single and multi-node control plane clusters
- Support already provisioned Linux VMs with Ubuntu 22.04 and 24.04
Check out the getting_started guide for launching a BYOH workload cluster
For an IPv6 or dual-stack control-plane endpoint, see IPv6 and dual-stack support.
BYOH was originally created by the VMware Tanzu team as a Cluster API sub-project. It has since been adopted by Platform9, who now maintains this fork.
The best way to ask questions, report bugs, or discuss the project is to open an issue on the issue tracker.
Pull Requests and feedback on issues are very welcome! See the issue tracker if you're unsure where to start, especially the Good first issue and Help wanted tags, and also feel free to reach out to discuss.
See also our contributor guide and the Kubernetes community page for more details on how to get involved.
This project is currently a work-in-progress, in an Alpha state, so it may not be production ready. There is no backwards-compatibility guarantee at this point. For more details on the roadmap and upcoming features, check out the project's issue tracker on GitHub.
This project uses asdf to pin the Go version. The required version is declared in .tool-versions.
Install asdf by following the official instructions for your platform.
Install the Go plugin and the pinned version:
asdf plugin add golang
asdf installasdf install reads .tool-versions and installs the exact version. After that, go version in this directory will report the pinned version.
To verify, for example:
$ go version
go version go1.26.4 darwin/arm64Check out the developer guide for launching a BYOH cluster consisting of Docker containers as hosts.
More about development and contributing practices can be found in CONTRIBUTING.md.
An installer controller is responsible to provide the installation and uninstallation scripts for k8s dependencies, prerequisites and components on each BYOHost.
If someone wants to implement their own installer controller then they need to follow the contract defined in installer doc.
- BYOH is currently compatible with Cluster API v1beta1, built/tested against Cluster API v1.10.10
| Operating System | Architecture | Kubernetes v1.31 - v1.35 |
|---|---|---|
| Ubuntu 22.04.* | amd64 | ✓ |
| Ubuntu 24.04.* | amd64 | ✓ |
NOTE: The '*' in OS means that all patches of that Ubuntu release are supported.
NOTE: The Kubernetes range means that minor release is supported but it may happen that a BYOH bundle for a specific patch may not exist in the OCI registry.
- TGIK episode on BYOH
- BYOH presented during Cluster API Office Hours
- BYOH on ARM