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.
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 iface | provider/ |
Shared provider interface 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 ICMPv4 Pinger the probe loop uses |
| Guest exec | guest/ |
RDP help-text shim + 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.
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
- 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 |