Virtual Kubelet provider that maps Kubernetes pods to Cocoon MicroVMs.
One vk-cocoon process runs per node. It satisfies the
virtual-kubelet
provider contract by translating pod CRUD into cocoon CLI calls and
pushing per-VM status back to the kubelet.
Documentation: cocoonstack.github.io/vk-cocoon (source in docs/).
Kubernetes API ──► virtual-kubelet provider (vk-cocoon, one per node)
pod CRUD ──► CreatePod / DeletePod / UpdatePod ── cocoon clone/run/snapshot
status ◄── async notify ── per-pod probe loop + real-time VM event watcher
snapshots ──► Puller / Pusher ── OCI registry (cross-node hibernate/wake)
| Layer | Package | Responsibility |
|---|---|---|
| Application | package main |
Entry point, node registration, metrics server, VM event watcher startup |
| Provider | provider/cocoon/ |
Lifecycle methods, startup reconcile, orphan policy, VM event watcher, pod eviction |
| Provider types | provider/ |
Shared orphan policy, VMStats / NodeStats, and node-capacity helpers |
| Cocoon CLI | vm/ |
Runtime interface + the CocoonCLI that shells out to cocoon |
| Snapshot SDK | snapshots/ |
Puller / Pusher stream snapshots and cloud images to an OCI registry |
| Network | network/ |
cocoon-net lease parser, the lease-release control-socket client, and the ICMPv4 Pinger the probe loop uses |
| Guest console | guest/ |
SAC dialer for Windows static IP |
| Probes | probes/ |
Per-pod probe agents that keep the async provider's pushed status live |
| Metrics | metrics/ |
Prometheus collectors for lifecycle, snapshots, VM table, orphans |
See Architecture for the full layer map and the async-provider contract.
Pods annotated cocoonset.cocoonstack.io/os: macos dispatch to the standalone
cocoon-macos QEMU/KVM backend
(VK_COCOON_MACOS_BIN, default /usr/local/bin/cocoon-macos) instead of the
cocoon CLI. The guest joins the cocoon CNI plane for a DHCP'd routed IP.
Readiness uses a bare TCP accept on the declared vm.cocoonstack.io/probe-port,
or falls back to requiring the guest sshd's SSH- banner on :22. The QEMU VNC
framebuffer gets a node-unique, password-protected host port allocated by
vk-cocoon, published via vm.cocoonstack.io/vnc-port and served on all node
interfaces (firewall 5900-5999; unset COCOON_MACOS_VNC_PASSWORD disables VNC).
A vk-cocoon restart
adopts a live guest instead of relaunching it (two QEMU processes on one overlay
corrupt the disk). Hibernate/wake, fork, and snapshot push do not apply to macOS guests.
vk-cocoon is a host-level binary installed via a systemd unit:
sudo install -m 0755 ./vk-cocoon /usr/local/bin/vk-cocoon
sudo install -m 0644 packaging/vk-cocoon.service /etc/systemd/system/vk-cocoon.service
sudo install -m 0644 packaging/vk-cocoon.env.example /etc/cocoon/vk-cocoon.env
# edit /etc/cocoon/vk-cocoon.env, then:
sudo systemctl daemon-reload && sudo systemctl enable --now vk-cocoonFull steps in Installation.
- Architecture — layer map, async-provider contract
- Pod lifecycle — CreatePod / DeletePod / hibernate
- Readiness probing — the per-pod probe loop
- Runtime reconciliation — startup reconcile, VM events
- Post-clone network hints — manual guest fixups
- Node resources — host-probed Capacity/Allocatable
- CPU QoS — pod requests/limits onto per-VM cgroup policy
- Metrics & monitoring — the three metrics surfaces
- Configuration — every environment variable
- Installation — systemd unit and building from source
make all # deps + fmt + lint + test + build
make build # build the vk-cocoon binary
make test # vet + race-detected tests
make lint # golangci-lint on linux + darwin
make help # show all targets| Project | Role |
|---|---|
| cocoon | The MicroVM runtime vk-cocoon shells out to |
| cocoon-common | CRD types, annotation contract, OCI registry + snapshot/cloud-image packages |
| cocoon-operator | CocoonSet and CocoonHibernation reconcilers |
| cocoon-webhook | Admission webhook for sticky scheduling and CocoonSet validation |
| cocoon-net | Per-host networking; vk-cocoon reads its JSON lease file and releases leases over its control socket (≥ v0.2.2) |