vk-cocoon is configured entirely through environment variables. The
systemd unit reads them from /etc/cocoon/vk-cocoon.env.
| Variable | Default | Description |
|---|---|---|
KUBECONFIG |
unset | Path to kubeconfig (in-cluster used otherwise). |
VK_NODE_NAME |
cocoon-pool |
Virtual node name registered with the K8s API. |
VK_LOG_LEVEL |
info |
projecteru2/core/log level. |
OCI_REGISTRY |
required | OCI registry base for snapshots and cloud images (e.g. an Artifact Registry repo). Auth resolves GCP ADC then docker config. |
GOOGLE_APPLICATION_CREDENTIALS |
unset | Path to a GCP service-account JSON key with roles/artifactregistry.writer, fed to ADC for the snapshot push. Unset falls back to the read-only node instance SA. |
VK_LEASES_PATH |
/var/lib/cocoon/net/leases.json |
cocoon-net JSON lease file. |
VK_COCOON_BIN |
/usr/local/bin/cocoon |
Path to the cocoon CLI binary. |
VK_COCOON_MACOS_BIN |
/usr/local/bin/cocoon-macos |
cocoon-macos binary os=macos pods dispatch to. |
COCOON_MACOS_BRIDGE |
cni0 |
Host bridge macOS guests’ tap NICs join for a DHCP’d routed IP. |
VK_ORPHAN_POLICY |
destroy |
destroy (auto-clean), alert, or keep. |
VK_RESTORE_MODE |
ondemand |
Guest-memory restore mode for Cloud Hypervisor clones: copy, ondemand, or mmap. Windows VMs always use copy (lazy restore stalls DHCP boot); Firecracker has no restore mode. mmap shares page cache across clones of one snapshot — the fastest fan-out — but requires a Cloud Hypervisor build with mmap restore support (cocoonstack/cloud-hypervisor dev); on other CH builds clones fail, so it is opt-in. Invalid values abort startup. |
VK_STAGING_DIR |
/var/lib/cocoon/vk-staging |
Temporary destination for peer-restored raw snapshot files. Keep it on the Cocoon run-directory filesystem to preserve hardlinks; stale entries are swept at startup. |
VK_PEER_ADDR |
:12501 |
Plain-HTTP peer-snapshot listener. Peers dial the node’s InternalIP on this port, so expose it only inside the trusted node network. |
VK_COCOON_SNAPSHOT_DIR |
/var/lib/cocoon/snapshot/localfile |
Cocoon localfile snapshot store served to peers. Override it when Cocoon uses a different root directory. |
VK_NODE_IP |
auto-detected | Override the virtual node’s InternalIP address (first non-loopback IPv4 used otherwise). |
VK_NODE_POOL |
default |
Cocoon pool label stamped onto the registered node. |
VK_SNAPSHOT_CPU_CLASS |
unset | Guest-visible CPU ABI class stamped as cocoonstack.io/snapshot-cpu-class. Classified CocoonSets schedule only to an exact match; use a certified class such as n2-cascade-lake-v1, not a broad architecture such as amd64. |
VK_PROVIDER_ID |
unset | Cloud-provider ProviderID for the virtual node (e.g. gce://<project>/<zone>/<instance>). Prevents cloud node lifecycle controllers from deleting the virtual node. |
VK_TLS_CERT |
/etc/cocoon/vk/tls/vk-kubelet.crt |
Path to the kubelet serving TLS certificate. |
VK_TLS_KEY |
/etc/cocoon/vk/tls/vk-kubelet.key |
Path to the kubelet serving TLS private key. |
VK_KUBELET_PORT |
10250 |
Port the virtual node’s kubelet API listens on and advertises. Override when a real kubelet on the same host already owns :10250 (e.g. a co-located k3s server node). |
VK_METRICS_ADDR |
:9091 |
Plain-HTTP prometheus listener. |
VK_RESERVE_PERCENT |
20 |
Percentage of host resources reserved for the host OS (0-100). Allocatable = Capacity × (100 - reserve) / 100. Align with cocoon’s cgroup_cpus fence so the accounting reserve matches the physically fenced cores. |
COCOON_CGROUP_PARENT |
cocoon.slice |
cgroup v2 slice holding cocoon’s per-VM CPU scopes; must match cocoon’s cgroup_parent config. Per-VM CPU usage and throttling stats are read from <slice>/vm-<id>.scope/cpu.stat. |
VK_NODE_CPU |
auto-detected | Override CPU capacity (auto: runtime.NumCPU()). |
VK_NODE_MEM |
auto-detected | Override memory capacity (auto: /proc/meminfo MemTotal). |
VK_NODE_STORAGE |
auto-detected | Override storage capacity (auto: statfs on COCOON_ROOT_DIR). |
VK_NODE_HUGEPAGES |
auto-detected | Override hugepages capacity (auto: /proc/meminfo; keyed by the host’s default page size). |
VK_NODE_PODS |
256 |
Maximum pod count. |
SNAPSHOT_ZSTD_LEVEL |
0 |
Snapshot writer zstd level; 0 keeps compression disabled. |
SNAPSHOT_CHUNK_SIZE_MIB |
0 |
Snapshot writer chunk size; 0 keeps chunking disabled. |
SNAPSHOT_TRANSFER_CONCURRENCY |
8 |
Parallel chunk transfers for encoded snapshots. |
SNAPSHOT_MEMORY_BUDGET_MIB |
9216 |
Push pipeline buffer cap per active push. |
SNAPSHOT_PULL_BUDGET_MIB |
2048 |
Pull prefetch buffer cap per active pull. |
Keep zstd and chunking disabled until every fleet reader and snapshot tool supports the v2 snapshot format. The push and pull memory budgets can be tuned independently without changing the writer format.