kubeswift

module

v0.7.0 Latest Latest Go to latest Published: Jul 3, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kubeswift-io/kubeswift

Links

Open Source Insights

README ¶

KubeSwift

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, disk and kernel boot, PCIe GPU passthrough, snapshots, and live migration. QEMU is a secondary runtime used only for HGX SXM (multi-GPU NVSwitch) topologies, where CUDA requires a full PCIe hierarchy that Cloud Hypervisor's flat model does not provide.

It is not a container sandbox (not Kata Containers) — each guest is a real VM, one per pod.

Capabilities

Boot paths — disk boot from cloud images (Ubuntu, Rocky, Debian, Fedora) and direct kernel boot from OCI artifacts (sub-second microVMs). Windows guests via osType: windows.
GPU passthrough — whole-GPU VFIO passthrough with two allocation backends: the native SwiftGPU model (discovery DaemonSet + profiles) or Kubernetes DRA ResourceClaims. 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-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 via spec.network.ports (ClusterIP/NodePort/LoadBalancer), a load-balanced Service across pool replicas via SwiftGuestPool.spec.service, and a VM→cluster egress reachability probe surfaced as EgressReady.
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, and cloneFromSnapshot for fast VM fan-out.
Migration — offline migration on any storage, and live migration (sub-second downtime) with optional mTLS transport and kubectl 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).

Custom Resources

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	—	`snapshot.kubeswift.io`	Namespaced	VM snapshot (disk or memory+disk)
SwiftRestore	—	`snapshot.kubeswift.io`	Namespaced	Restore from a snapshot
SwiftSnapshotSchedule	—	`snapshot.kubeswift.io`	Namespaced	Cron-scheduled snapshots + keep-N
SwiftMigration	—	`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.

Documentation

Start at the documentation index. Common entry points:

Quickstart — boot your first VM
Architecture — components, boot paths, status model
CRD reference · API overview
GPU passthrough · GPU via DRA
Networking operations
Snapshots · Live migration
swiftctl CLI · Observability
Install (Helm/OCI)

Build

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/)

Status

Pre-1.0; the v1alpha1 API may change between releases. Host requirement: x86_64 Linux nodes with /dev/kvm (KVM). Guest OS: Linux (Ubuntu 22.04+, Rocky 9, Debian 12, Fedora) and Windows (Server 2022/2025, via osType: windows). Disk and kernel boot, Windows boot, networking, snapshots, offline and live migration, SwiftGuestPool, and Tier-1 PCIe GPU passthrough are validated on a live cluster. Hardware-gated items (HGX Tier-2/3 GPU, SR-IOV NICs, SEV-SNP confidential VMs) are implemented or designed but await hardware.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
fleet/v1alpha1 +kubebuilder:object:generate=true +groupName=fleet.kubeswift.io	+kubebuilder:object:generate=true +groupName=fleet.kubeswift.io
gpu/v1alpha1 +kubebuilder:object:generate=true +groupName=gpu.kubeswift.io	+kubebuilder:object:generate=true +groupName=gpu.kubeswift.io
image/v1alpha1 +kubebuilder:object:generate=true +groupName=image.kubeswift.io	+kubebuilder:object:generate=true +groupName=image.kubeswift.io
kernel/v1alpha1 +kubebuilder:object:generate=true +groupName=kernel.kubeswift.io	+kubebuilder:object:generate=true +groupName=kernel.kubeswift.io
migration/v1alpha1 +kubebuilder:object:generate=true +groupName=migration.kubeswift.io	+kubebuilder:object:generate=true +groupName=migration.kubeswift.io
seed/v1alpha1 +kubebuilder:object:generate=true +groupName=seed.kubeswift.io	+kubebuilder:object:generate=true +groupName=seed.kubeswift.io
shared Package shared holds common types for KubeSwift API.	Package shared holds common types for KubeSwift API.
snapshot/v1alpha1 +kubebuilder:object:generate=true +groupName=snapshot.kubeswift.io	+kubebuilder:object:generate=true +groupName=snapshot.kubeswift.io
swift/v1alpha1 +kubebuilder:object:generate=true +groupName=swift.kubeswift.io	+kubebuilder:object:generate=true +groupName=swift.kubeswift.io
cmd
controller-manager command
gpu-discovery command
kubeswift-dra-driver command kubeswift-dra-driver is KubeSwift's REFERENCE DRA driver for VM GPU passthrough.	kubeswift-dra-driver is KubeSwift's REFERENCE DRA driver for VM GPU passthrough.
kubeswift-gateway command Command kubeswift-gateway is the browser-facing Connect hub for the KubeSwift UI.	Command kubeswift-gateway is the browser-facing Connect hub for the KubeSwift UI.
kubeswift-guest-agent command Command kubeswift-guest-agent is a tiny in-guest agent that regenerates a cloneFromSnapshot clone's identity (machine-id / SSH host keys / hostname / MAC) and renews its DHCP lease IN PLACE — with no reboot — over a host-only vsock channel.	Command kubeswift-guest-agent is a tiny in-guest agent that regenerates a cloneFromSnapshot clone's identity (machine-id / SSH host keys / hostname / MAC) and renews its DHCP lease IN PLACE — with no reboot — over a host-only vsock channel.
snapshot-oras command snapshot-oras — the OCI-registry (ORAS) uploader/downloader for KubeSwift SwiftSnapshot/SwiftRestore (Snapshot "oci" backend).	snapshot-oras — the OCI-registry (ORAS) uploader/downloader for KubeSwift SwiftSnapshot/SwiftRestore (Snapshot "oci" backend).
snapshot-s3 command snapshot-s3 — the Tier C (object-storage export) uploader/downloader for KubeSwift SwiftSnapshot/SwiftRestore (Snapshot Phase 3).	snapshot-s3 — the Tier C (object-storage export) uploader/downloader for KubeSwift SwiftSnapshot/SwiftRestore (Snapshot Phase 3).
snapshot-stager command
swiftctl command
gen
kubeswift/v1
kubeswift/v1/kubeswiftv1connect
internal
actions Package actions implements the shared SwiftGuest lifecycle primitives — start, stop, migrate — used by BOTH swiftctl and the kubeswift-gateway.	Package actions implements the shared SwiftGuest lifecycle primitives — start, stop, migrate — used by BOTH swiftctl and the kubeswift-gateway.
cli
controller/migrationcert Package migrationcert provisions the per-node TLS identities used by the Phase 3c live-migration mTLS transport (stunnel sidecar).	Package migrationcert provisions the per-node TLS identities used by the Phase 3c live-migration mTLS transport (stunnel sidecar).
controller/swiftdrain Package swiftdrain implements the Phase 4 drain controller: the "controller creates" half of the webhook-marks / controller-creates / PDB-guarantees architecture (design doc §3).	Package swiftdrain implements the Phase 4 drain controller: the "controller creates" half of the webhook-marks / controller-creates / PDB-guarantees architecture (design doc §3).
controller/swiftgpu
controller/swiftguest Cold / suspended-state migration (P4) — the import half.	Cold / suspended-state migration (P4) — the import half.
controller/swiftguestpool
controller/swiftimage
controller/swiftkernel
controller/swiftmigration Package swiftmigration reconciles SwiftMigration resources for Phase 1 of live migration: offline migration via direct PVC reuse.	Package swiftmigration reconciles SwiftMigration resources for Phase 1 of live migration: offline migration via direct PVC reuse.
controller/swiftrestore Package swiftrestore reconciles SwiftRestore resources.	Package swiftrestore reconciles SwiftRestore resources.
controller/swiftsnapshot Cold / suspended-state migration (P4) — the disk half of an includeDisk oci snapshot.	Cold / suspended-state migration (P4) — the disk half of an includeDisk oci snapshot.
controller/swiftsnapshotschedule Package swiftsnapshotschedule reconciles SwiftSnapshotSchedule resources: it creates a SwiftSnapshot each time the cron schedule fires (Phase 6).	Package swiftsnapshotschedule reconciles SwiftSnapshotSchedule resources: it creates a SwiftSnapshot each time the cron schedule fires (Phase 6).
gateway Package gateway implements the kubeswift-gateway: the browser-facing Connect hub that fronts the KubeSwift operator across a fleet of member clusters.	Package gateway implements the kubeswift-gateway: the browser-facing Connect hub that fronts the KubeSwift operator across a fleet of member clusters.
gpualloc Package gpualloc defines the pluggable GPU allocation backend seam for KubeSwift.	Package gpualloc defines the pluggable GPU allocation backend seam for KubeSwift.
imageref Package imageref centralises the lookup that both the SwiftImage and SwiftGuest controllers need: "give me the SwiftGuests in this namespace that reference this SwiftImage".	Package imageref centralises the lookup that both the SwiftImage and SwiftGuest controllers need: "give me the SwiftGuests in this namespace that reference this SwiftImage".
metrics
migrationsidecar Package migrationsidecar is the single source of truth for the Phase 3c live-migration mTLS stunnel sidecar contract: the image, container name, mount paths, env keys, role values, and the controller<->sidecar annotation keys.	Package migrationsidecar is the single source of truth for the Phase 3c live-migration mTLS stunnel sidecar contract: the image, container name, mount paths, env keys, role values, and the controller<->sidecar annotation keys.
oci Package oci holds the KubeSwift golden-image (P3) OCI transfer core: the sparse, zero-skipping, content-addressed disk chunking used by both the in-cluster snapshot-oras transfer Job and the client-side `swiftctl image publish` command.	Package oci holds the KubeSwift golden-image (P3) OCI transfer core: the sparse, zero-skipping, content-addressed disk chunking used by both the in-cluster snapshot-oras transfer Job and the client-side `swiftctl image publish` command.
resolved
runtimeintent
scheme
seed
snapshot/clonecommon Package clonecommon holds the backend-mechanism primitives shared by the snapshot clone/restore paths — the s3 download Job, the node-local cache layout, the per-clone MAC computation, and the runtime-dir prefix.	Package clonecommon holds the backend-mechanism primitives shared by the snapshot clone/restore paths — the s3 download Job, the node-local cache layout, the per-clone MAC computation, and the runtime-dir prefix.
snapshot/configjson Package configjson reads and minimally patches Cloud Hypervisor's snapshot config.json before a restore-receive launch.	Package configjson reads and minimally patches Cloud Hypervisor's snapshot config.json before a restore-receive launch.
version
webhook/eviction Package eviction is the Phase 4 drain-integration eviction webhook.	Package eviction is the Phase 4 drain-integration eviction webhook.
webhook/swiftguest
webhook/swiftimage
webhook/swiftmigration Package swiftmigration contains the admission webhook validator for SwiftMigration.	Package swiftmigration contains the admission webhook validator for SwiftMigration.
webhook/swiftrestore Package swiftrestore contains the admission webhook validator for SwiftRestore.	Package swiftrestore contains the admission webhook validator for SwiftRestore.
webhook/swiftseedprofile
webhook/swiftsnapshot Package swiftsnapshot contains the admission webhook validator for SwiftSnapshot.	Package swiftsnapshot contains the admission webhook validator for SwiftSnapshot.
webhook/swiftsnapshotschedule Package swiftsnapshotschedule contains the admission webhook validator for SwiftSnapshotSchedule (Phase 6).	Package swiftsnapshotschedule contains the admission webhook validator for SwiftSnapshotSchedule (Phase 6).