unbounded

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 init to 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.

• Code of Conduct
• Support
• Issue Tracker

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.