Prerequisites
- A Linux worker with usable
/dev/kvm. Virtual workers need nested virtualization. - Permission to run privileged pods and mount host devices.
- Docker,
kubectlaccess, and an image registry the worker can pull from. - Pod network access to download the guest image.
Build the image
Save these two files in an empty directory. This complete application uses Python and asks a sandbox to uppercase a shared file. The same bind-mount workflow is available in TypeScript, Rust, and Go; Ruby does not expose mount configuration.Required application files
Required application files
Create The Python package includes the runtime and kernel firmware; the pod needs no Docker daemon.
agent.py:Volume.bind() shares /workspace from the application container with the guest.Add Dockerfile:REGISTRY/PROJECT here and in the manifest, then build and push:
--platform linux/amd64 and amd64 in the manifest below.
For private images, configure Kubernetes imagePullSecrets for the application image and microsandbox registry credentials for the guest image.
Run the pod
ReplaceYOUR_KVM_NODE with your worker name, then create a test namespace:
pod.yaml with your image reference:
Clean up
Delete the test namespace and remove the worker label:Troubleshooting
Check KVM access inside the pod
Check KVM access inside the pod
To run a diagnostic instead of the application, add this under the Recreate the pod, wait for completion, and read the results:Check the KVM device and access results. Remove
agent
container in pod.yaml:command and recreate the pod to run the application again.Beyond the example
- Storage:
emptyDirsurvives container restarts but is deleted with the pod. Use a PVC for durable files. Keep/msbprivate to each pod; persisting it does not keep VMs running. - Resources: allow memory and disk space for the application, guests, and runtime. This example gives a 512 MiB guest a 2 GiB pod limit. Keep runtime volumes disk-backed.
- Shutdown: the context manager kills and removes the sandbox. For graceful shutdown, call
await sandbox.stop()first. Long-running applications also need aSIGTERMhandler to stop work and shut down sandboxes within the pod’s grace period.
Device plugins
A KVM device plugin can provide device access without a privileged application container. A host mount alone may not grant that access. Request the plugin’s resource in the container limits, remove thekvm volume and mount, and remove privileged: true. Resource names such as devices.kubevirt.io/kvm depend on the plugin. Verify microVM boot with your device permissions and seccomp/AppArmor/SELinux policies before using this setup.
The plugin may itself require privileges. A KVM allocation does not limit VM count; control concurrency in your application.