Separate host provisioning and node bootstrap into CAPI providers, following the Metal3/CAPM3 model
- Dominant language
- Go
- Stars
- 28
- Forks
- 11
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 55
Description
## Proposal
Could Unbounded expose its host-provisioning and node-bootstrap capabilities as independently usable **Cluster API infrastructure and bootstrap providers**, while keeping cross-site networking separate?
The goal would be to preserve Unbounded's specialized capabilities without requiring users to adopt a parallel Kubernetes machine-lifecycle framework.
## Metal3 As A Reference
[Metal3 and Cluster API Provider Metal3 (CAPM3)](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/docs/deployment_workflow.md) demonstrate a useful separation:
- **Bare Metal Operator and Ironic** manage host inventory, inspection, imaging, cleaning, and power operations.
- **CAPM3** implements CAPI infrastructure contracts, selecting a `BareMetalHost` and connecting its provisioning lifecycle to a CAPI `Machine`.
- **A separate bootstrap provider**, normally kubeadm, generates the configuration that initializes Kubernetes.
- **CAPI** coordinates Machine ownership, replacement rollouts, draining, and remediation.
A physical host is therefore distinct from its allocation as a Kubernetes Machine. Deleting a Machine can deprovision and release the host for reuse without deleting its inventory record.
This is particularly relevant to Unbounded's existing-server and bare-metal scenarios: adopting CAPI does not require treating physical servers as disposable cloud instances.
## Applying This Separation To Unbounded
Unbounded currently combines host access/provisioning, Kubernetes join configuration, and lifecycle operations through its `Machine`, `MachineOperation`, controllers, and agent.
Could these responsibilities be separated along the following boundaries?
| Layer | Proposed responsibility |
|---|---|
| Host management | Retain Machina/Metalman capabilities such as SSH, PXE, Redfish, imaging, and enrollment |
| CAPI infrastructure provider | Claim or provision a host, deliver bootstrap data, report infrastructure identity/status, and clean up or release the allocation |
| CAPI bootstrap provider | Generate Unbounded agent configuration and first-boot data for a particular Machine and target cluster |
| Host runtime | Prepare and run the nspawn worker environment and maintain required local boot services |
| Networking | Continue managing sites, gateways, and cross-site connectivity independently |
| CAPI | Own the Kubernetes Machine lifecycle and coordinate rollout, drain, and remediation |
For cloud VMs, existing infrastructure providers such as CAPZ or CAPA could be reused where compatible, rather than requiring Unbounded to implement another cloud provisioning and replacement stack.
## Why Independent Providers Matter
Separating infrastructure from bootstrap would enable useful compositions:
- Existing cloud infrastructure providers with Unbounded bootstrap and networking.
- Unbounded SSH/PXE infrastructure with its own bootstrap provider.
- CAPM3-managed hardware with Unbounded bootstrap.
- Unbounded-provisioned hosts with another compatible bootstrap provider.
These would need explicit compatibility testing, not just matching resource names. In particular, an Unbounded infrastructure provider should consume the standard bootstrap-data contract rather than always generating its own join configuration.
The benefit is broader than installation: users could integrate with MachineDeployments, MachineHealthChecks, ClusterClass, and management-cluster migration through established contracts instead of maintaining custom synchronization between lifecycle frameworks.
## Lifecycle Ownership
This proposal does not require removing low-level operations or standalone workflows.
Power control, imaging, cleanup, and resumable provisioning still belong in the infrastructure backend. Some `MachineOperation` functionality could serve as a provider's remediation or coordinated in-place-update mechanism.
For CAPI-owned Machines, however, those operations should not independently initiate competing upgrades or replacements. A bootstrap-only path should also avoid requiring a Kubernetes-facing lifecycle daemon unless a specific ongoing responsibility needs it.
CAPI would not automatically solve enrollment security, backend crash recovery, or limited physical capacity. Those remain provider responsibilities, with explicit policies for host reuse and replacement when no spare host is available.
## Suggested First Milestone
1. Define the distinction between persistent host inventory and a CAPI Machine allocation.
2. Implement an Unbounded bootstrap provider with a bootstrap-only host execution mode.
3. Integrate one host backend through the CAPI infrastructure contract.
4. Demonstrate provisioning, Node association, replacement, drain, and release, including controller restarts during provisioning and deletion.
5. Document supported provider combinations and preserve standalone operation where needed.
Would the maintainers be open to a design proposal using the Metal3/CAPM3 separation as a reference?
The central request is **to make Unbounded's host and networking capabilities composable through CAPI, rather than making another machine-lifecycle framework a prerequisite for using them**.
Reference: [Cluster API provider contracts](https://cluster-api.sigs.k8s.io/developer/providers/contracts/overview).
Contributor guide
Research direction
Start by reading the existing Machine, MachineOperation, controller, and agent components, then compare their responsibilities with the referenced Cluster API provider contracts and Metal3/CAPM3 workflow. A first milestone would define persistent host inventory versus Machine allocation, then demonstrate bootstrap, provisioning, replacement, drain, release, and restart-safe deletion while preserving standalone operation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- devops, distributed-systems, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100