KubeSwift runs virtual machines as Kubernetes workloads. You define a VM with a custom resource; controllers reconcile it into a pod; inside that pod, swiftletd
launches a hypervisor. Cloud Hypervisor is the hypervisor for nearly every workload — Linux and Windows guests, traditiona disk VMs and kernel boot (microVMs), PCIe GPU passthrough, snapshots, and live migration. QEMU is used for the moment as a secondary runtime only for HGX SXM (multi-GPU NVSwitch) topologies, where CUDA requires a full PCIe hierarchy that Cloud Hypervisor's flat model does not currently provide. We are tracking upstream for this capability.
Boot paths— disk boot from cloud images (Linux and Windows) and direct kernel boot from OCI artifacts (sub-second microVMs).** GPU passthrough**— whole-GPU VFIO passthrough with two allocation backends: the native SwiftGPU model (discovery DaemonSet + profiles) or KubernetesDRAResourceClaims. PCIe GPUs on Cloud Hypervisor; HGX SXM on QEMU.Networking— tap + bridge + DHCP with the guest IP surfaced in status; multi-NIC via Multus; SR-IOV NIC passthrough; OVN Backend supported: OVN-Kubernetes and multi-node L2 with IP-preserving cross-node live migration (kube-ovn primary-on-NAD — see).docs/networking/ovn-l2-install.md
Services— expose guest ports as Kubernetes Services viaspec.network.ports
(ClusterIP/NodePort/LoadBalancer), a load-balanced Service across pool replicas viaSwiftGuestPool.spec.service
, and a VM→cluster egress reachability probe surfaced asEgressReady
.Storage— per-guest root-disk cloning sized from a class; optional data disks (blank/sized, image-backed, or attached PVC); RWX+Block for live-migration-capable volumes.Snapshots & clones— disk-only (CSI) and memory+disk (local/S3) snapshots, scheduled snapshots, andcloneFromSnapshot
for fast VM fan-out.OCI registry artifacts— golden VM images (SwiftImage.spec.source.oci
+swiftctl image publish
, cosign-signed with verify-on-pull) and VM snapshots / full-state cold migration (SwiftSnapshot
backend.type: oci
) stored in any OCI registry, for cross-cluster and edge distribution.Migration— offline migration on any storage, and live migration (sub-second downtime) with optional mTLS transport andkubectl drain
integration.Fleets—SwiftGuestPool
gives ReplicaSet-style scaling with rolling updates, topology spread, and a PVC per replica.Operations—swiftctl
for console/SSH/lifecycle/describe; Prometheus metrics and Grafana dashboards across every feature; cloud-init via NoCloud; security-hardened containers (drop-ALL, no privileged).
| CRD | Short | API group | Scope | Purpose |
|---|---|---|---|---|
| SwiftGuest | sg |
|||
swift.kubeswift.io |
||||
| Namespaced | A VM instance | |||
| SwiftGuestClass | sgc |
|||
swift.kubeswift.io |
||||
| Cluster | CPU/memory/disk template | |||
| SwiftGuestPool | sgpool |
|||
swift.kubeswift.io |
||||
| Namespaced | Fleet of identical VMs | |||
| SwiftImage | si |
|||
image.kubeswift.io |
||||
| Namespaced | Disk image source | |||
| SwiftSeedProfile | ssp |
|||
seed.kubeswift.io |
||||
| Namespaced | cloud-init (NoCloud) config | |||
| SwiftKernel | sk |
|||
kernel.kubeswift.io |
||||
| Namespaced | Kernel + initramfs OCI artifact | |||
| SwiftGPUProfile | sgp |
|||
gpu.kubeswift.io |
||||
| Namespaced | GPU passthrough request (native backend) | |||
| SwiftGPUNode | sgn |
|||
gpu.kubeswift.io |
||||
| Cluster | Per-node GPU inventory | |||
| SwiftSnapshot | ssnap | snapshot.kubeswift.io |
||
| Namespaced | VM snapshot (disk or memory+disk) | |||
| SwiftRestore | srst | snapshot.kubeswift.io |
||
| Namespaced | Restore from a snapshot | |||
| SwiftSnapshotSchedule | — | snapshot.kubeswift.io |
||
| Namespaced | Cron-scheduled snapshots + keep-N | |||
| SwiftMigration | smig | migration.kubeswift.io |
||
| Namespaced | Move a guest between nodes | |||
| Cluster | ksc |
|||
fleet.kubeswift.io |
||||
| Namespaced | Member cluster federated by the gateway hub |
13 CRDs, all v1alpha1
.
Start at the ** documentation index**. Common entry points:
Quickstart— boot your first VMArchitecture— components, boot paths, status modelCRD reference·API overviewGPU passthrough·GPU via DRANetworking operationsSnapshots·Live migrationswiftctl CLI·ObservabilityInstall (Helm/OCI)
make build # Go binaries
make build-images # container images
make deploy # apply CRDs + deploy the controller
go test ./... # Go tests
cargo test # Rust tests (from rust/)
Pre-1.0; the v1alpha1
API may change between releases. Host requirement: x86_64 Linux nodes with /dev/kvm
(KVM).
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).