README
¶
Unbounded Kubernetes
Run Kubernetes worker nodes anywhere — across clouds, on-prem, and at the edge — connected back to a single control plane.
Early Development — This project is under active development. It is suitable for experimentation and prototyping, but expect rough edges and breaking changes. Please report issues on the Issue Tracker.
What is Unbounded Kubernetes?
Kubernetes assumes all worker nodes share a network — a single VPC in the cloud or a flat LAN on-premises. That model breaks when you need compute in multiple locations: a second cloud region, GPU capacity from a specialized provider, on-prem hardware behind a NAT, or edge devices at remote sites.
Unbounded Kubernetes extends any conformant Kubernetes control plane so that worker nodes can run anywhere and join back to the cluster over encrypted tunnels. It provides multiple provisioning paths and a unified networking layer so that pods, services, and DNS work transparently across sites.
For a deeper dive, see the Project Overview.
Key Features
- Multi-site networking — Transparent pod-to-pod connectivity across sites using WireGuard, GENEVE, VXLAN, IPIP, or direct routing with an eBPF or netlink dataplane.
- SSH-based provisioning — Join existing Linux machines to the cluster over SSH with a single command.
- Cloud API provisioning — Auto-provision instances from Nebius, CoreWeave, OCI, Azure, AWS, and others via Karpenter in response to unschedulable pods.
- Bare-metal PXE boot — PXE-boot servers with integrated DHCP, TFTP, HTTP, Redfish BMC power management, and TPM 2.0 attestation.
- Works with any conformant Kubernetes — AKS, EKS, GKE, kubeadm, k3s, and more. Bring your own cluster or use the quickstart script.
- GPU support — Automatic detection and configuration of NVIDIA GPUs on provisioned nodes.
Components
| Component | Description | Details |
|---|---|---|
| unbounded-agent | Single binary delivered to hosts to bootstrap them as Kubernetes worker nodes using systemd-nspawn. |
Agent Guide |
| machina | Kubernetes controller that provisions remote Linux machines over SSH. | SSH Guide, CRD Reference |
| metalman | Controller for PXE-booting bare-metal servers with DHCP, TFTP, HTTP, Redfish BMC, and TPM 2.0. | PXE Guide, Bare Metal Concepts |
| unbounded-net | CNI plugin and multi-site networking system for cross-site pod connectivity. | Networking Concepts |
| kubectl-unbounded | kubectl plugin for initializing sites, adding machines, and managing the cluster. | CLI Reference |
Quick Start
Get a working multi-site cluster in under 10 minutes. This creates an AKS cluster and joins a remote node to it. Already have a cluster? See the Bring Your Own Cluster guide.
1. Install the kubectl plugin
# Linux amd64
curl -sL https://github.com/Azure/unbounded/releases/latest/download/kubectl-unbounded-linux-amd64.tar.gz | tar xz
sudo mv kubectl-unbounded /usr/local/bin/
macOS (Apple Silicon)
curl -sL https://github.com/Azure/unbounded/releases/latest/download/kubectl-unbounded-darwin-arm64.tar.gz | tar xz
sudo mv kubectl-unbounded /usr/local/bin/
2. Create the cluster
curl -fsSLO https://raw.githubusercontent.com/Azure/unbounded/main/hack/scripts/aks-quickstart.sh
chmod +x aks-quickstart.sh
./aks-quickstart.sh create \
--name my-unbounded \
--location eastus \
--remote-node-cidr 192.168.1.0/24 \
--remote-pod-cidr 10.245.0.0/16
This takes about 8 minutes. The script creates an AKS cluster, adds a gateway node pool, and runs
kubectl unbounded site initto install the networking stack.
3. Add a remote node
kubectl unbounded machine manual-bootstrap my-node --site remote \
| ssh user@<host> sudo bash
Replace
user@<host>with the SSH user and IP of your remote machine.
4. Verify
kubectl get nodes -w
After a few minutes your remote node appears with status Ready.
For the full walkthrough including pod networking verification, see the Getting Started Guide.
Documentation
Full documentation is available at azure.github.io/unbounded.
| Concepts | Project Overview · Networking · Bare Metal |
| Guides | Getting Started · Existing Cluster · SSH Provisioning · Cloud API · PXE Boot · Agent |
| Reference | Architecture · CLI · Machine CRD · GPU / NVIDIA |
Repository Structure
api/ API definitions for custom resources
bin/ Generated binary artifacts
cmd/
agent/ unbounded-agent sources
inventory/ Inventory controller sources
kubectl-unbounded/ kubectl plugin sources
machina/ machina controller sources
metalman/ metalman controller sources
deploy/ Kubernetes manifests for deployment
docs/ Documentation site (Hugo)
hack/ Development tools and scripts
images/ OCI image definitions (Containerfiles)
internal/ Shared internal packages
Building from Source
Requires Go 1.26+.
# Build the kubectl plugin
make kubectl-unbounded
# Build controllers (includes format, lint, test, and build)
make machina
make metalman
# Build without lint/test (used in container images)
make machina-build
make metalman-build
# Build container images
make machina-oci
make metalman-oci
# Serve docs locally
make docs-serve
See CONTRIBUTING.md for full build instructions and coding standards.
Contributing
This project welcomes contributions and suggestions. See CONTRIBUTING.md for details on how to get started, including the CLA process, coding standards, and how to submit pull requests.
License
This project is licensed under the MIT License.
Third-party dependency attributions are listed in the NOTICE file.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
machina/v1alpha3
+kubebuilder:object:generate=true +groupName=unbounded-cloud.io
|
+kubebuilder:object:generate=true +groupName=unbounded-cloud.io |
|
net/v1alpha1
Package v1alpha1 contains API Schema definitions for the net.unbounded-cloud.io v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the net.unbounded-cloud.io v1alpha1 API group. |
|
cmd
|
|
|
agent
command
|
|
|
agent/internal/daemon
Package daemon implements nspawn machine updates for the unbounded-agent.
|
Package daemon implements nspawn machine updates for the unbounded-agent. |
|
inventory/inventory-agent
command
|
|
|
inventory/inventory-aggregator
command
|
|
|
inventory/inventory-inspector
command
|
|
|
inventory/inventory-viewer
command
|
|
|
kubectl-unbounded
command
|
|
|
machina
command
|
|
|
metalman
command
|
|
|
unbounded-net-controller
command
|
|
|
unbounded-net-node
command
|
|
|
unbounded-net-routeplan-debug
command
|
|
|
unping
command
unping sends health check probes to a remote unbounded-net node and prints round-trip times in a format similar to standard ping.
|
unping sends health check probes to a remote unbounded-net node and prints round-trip times in a format similar to standard ping. |
|
unroute
command
unroute dumps the eBPF LPM trie tunnel maps (unbounded_endpoints_v4 and unbounded_endpoints_v6) in human-readable or JSON format.
|
unroute dumps the eBPF LPM trie tunnel maps (unbounded_endpoints_v4 and unbounded_endpoints_v6) in human-readable or JSON format. |
|
deploy
|
|
|
machina
Package machina embeds the rendered Machina controller deployment manifests so they can be bundled into binaries that need to apply them (e.g.
|
Package machina embeds the rendered Machina controller deployment manifests so they can be bundled into binaries that need to apply them (e.g. |
|
net
Package net embeds the rendered unbounded-net controller and node deployment manifests so they can be bundled into binaries that need to apply them (e.g.
|
Package net embeds the rendered unbounded-net controller and node deployment manifests so they can be bundled into binaries that need to apply them (e.g. |
|
hack
|
|
|
cmd/forge
command
|
|
|
cmd/notice
command
notice generates and verifies the project's NOTICE file from the direct dependencies declared in go.mod and frontend/package.json.
|
notice generates and verifies the project's NOTICE file from the direct dependencies declared in go.mod and frontend/package.json. |
|
cmd/notice/internal/gomod
Package gomod implements a notice.Collector for direct dependencies declared in go.mod.
|
Package gomod implements a notice.Collector for direct dependencies declared in go.mod. |
|
cmd/notice/internal/license
Package license contains ecosystem-agnostic helpers for license classification, copyright extraction, and license-URL construction.
|
Package license contains ecosystem-agnostic helpers for license classification, copyright extraction, and license-URL construction. |
|
cmd/notice/internal/notice
Package notice contains the core types and orchestration for the NOTICE generator: the on-disk schema, the Collector interface, and the helpers that ecosystem packages use to assemble entries.
|
Package notice contains the core types and orchestration for the NOTICE generator: the on-disk schema, the Collector interface, and the helpers that ecosystem packages use to assemble entries. |
|
cmd/notice/internal/npm
Package npm implements a notice.Collector for direct dependencies declared in frontend/package.json.
|
Package npm implements a notice.Collector for direct dependencies declared in frontend/package.json. |
|
cmd/notice/internal/testutil
Package testutil provides shared helpers for hermetic notice-tool tests.
|
Package testutil provides shared helpers for hermetic notice-tool tests. |
|
cmd/render-manifests
command
render-manifests is a generic Go template renderer.
|
render-manifests is a generic Go template renderer. |
|
internal
|
|
|
net/allocator
Package allocator provides CIDR allocation functionality for Kubernetes nodes.
|
Package allocator provides CIDR allocation functionality for Kubernetes nodes. |
|
net/certmanager
Package certmanager manages TLS serving certificates for the controller using a self-signed CA.
|
Package certmanager manages TLS serving certificates for the controller using a self-signed CA. |
|
net/config
Package config provides configuration types for the unbounded-net-controller.
|
Package config provides configuration types for the unbounded-net-controller. |
|
net/controller
Package controller implements the Kubernetes node controller for CIDR allocation.
|
Package controller implements the Kubernetes node controller for CIDR allocation. |
|
net/ebpf
Package ebpf provides eBPF-based tunnel dataplane management.
|
Package ebpf provides eBPF-based tunnel dataplane management. |
|
net/html
Package html embeds HTML page templates used by the controller and node binaries.
|
Package html embeds HTML page templates used by the controller and node binaries. |
|
net/metrics
Package metrics provides shared Prometheus metrics helpers for the unbounded-net controller and node agent.
|
Package metrics provides shared Prometheus metrics helpers for the unbounded-net controller and node agent. |
|
net/netlink
Package netlink provides utilities for managing network configuration using netlink
|
Package netlink provides utilities for managing network configuration using netlink |
|
ociutil
Package ociutil provides shared helpers for OCI registry operations.
|
Package ociutil provides shared helpers for OCI registry operations. |
|
version
Package version exposes build-time version metadata.
|
Package version exposes build-time version metadata. |
|
pkg
|
|
|
agent/config
Package config defines the intermediate representation (IR) for agent configuration.
|
Package config defines the intermediate representation (IR) for agent configuration. |