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 through an eBPF 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 exposure of NVIDIA and AMD 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 maintained in this repository 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

The script creates an AKS cluster, adds a gateway node pool, runs kubectl unbounded install to bootstrap the operator, then kubectl unbounded site init to request the networking stack through the cluster Site.

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.

AKS Flex: create the entire cluster with one script

Create one AKS system node and three automatically bootstrapped VMSS workers, with Unbounded networking and Gantry:

bash hack/scripts/aks-flex-cluster.sh \
    --name my-flex-cluster \
    --location canadacentral \
    --subscription "<subscription-uuid>" \
    --yes

Requires an authenticated Azure CLI >= 2.90.0 and a subscription supporting the AKS Flex preview. Run bash hack/scripts/aks-flex-cluster.sh --help for tools and options; add --plan to preview without creating resources.

Keep the state directory (tmp/aks-flex/my-flex-cluster/ by default), which contains the kubeconfig and SSH key. Rerun with the same arguments to resume provisioning. Scale workers separately with az vmss scale; reruns preserve capacity. The script is not an upgrade or teardown tool.

For ARM64 Flex workers, add --worker-arch arm64. This selects the ARM64 Ubuntu 24.04 host and agent archive, with Standard_D4ps_v6 as the default worker VM size; the system node keeps its existing AMD64 default.

For a streaming-capable build, add --artifact-streaming to preload NBD before Flex bootstrap and enable operator-managed Gantry Artifact Streaming only on the Flex workers. The setting is pinned in deployment state and applies to new VMSS instances after scale-out. ARM64 streaming is experimental; successful ACR conversion does not by itself establish runtime compatibility.

To install an unreleased build, use --plugin-binary /path/to/kubectl-unbounded, --image-registry ghcr.io/myorg, and --operator-image unbounded-operator:TAG. Publish the required component images under that registry with tags matching the operator's compiled version. These selections are pinned in the deployment state, so reruns cannot silently switch the installer or images.

Gantry starts without ACR authentication. See the ACR attachment guide to enable it with a compatible plugin/operator; the script's pinned v0.8.0 baseline does not include managed authentication.

Documentation

Full documentation is available at unbounded-cloud.io.

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 · GPU / AMD

Project direction and stewardship are documented in the roadmap, maintainer list, governance policy, and security policy. CNCF Sandbox preparation is tracked in CNCF.md and issue #555.

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 Apache License 2.0.

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.