cocoon-net

VPC-native networking for Cocoon VM nodes. Provisions cloud networking resources and runs an embedded DHCP server so VMs obtain VPC-routable IPs directly -- no overlay network, no iptables DNAT, no external DHCP server dependency.

Overview

• Embedded DHCP server on cni0 bridge, replacing the external DHCP server dependency
• Dynamic /32 host routes added on DHCP lease, removed on expiry
• Platform auto-detection via instance metadata (GKE or Volcengine)
• Cloud resource provisioning -- GKE alias IP ranges or Volcengine ENI secondary IPs
• Host networking -- cni0 bridge, sysctl, iptables FORWARD + NAT
• CNI integration -- generates conflist for Kubernetes pod networking
• State management -- pool state persisted to /var/lib/cocoon/net/pool.json
• Adopt mode -- bring existing hand-provisioned nodes under management
• Daemon mode -- runs as a long-lived systemd service

Supported Platforms

Platform	Mechanism	Max IPs/node
GKE	VPC alias IP ranges (gcloud)	~254
Volcengine	Dedicated subnet + secondary ENI IPs (ve CLI)	140 (7 ENIs x 20)

Architecture

cocoon-net init          cocoon-net daemon
      |                        |
      v                        v
Cloud provisioning       Node setup (sysctl, bridge, iptables, CNI conflist)
(alias IPs / ENIs)             |
      |                        v
      v                  DHCP server on cni0
pool.json  <----------        |
                               v
                         On lease: add /32 route
                         On release: del /32 route

Two-phase operation:

1. cocoon-net init (or adopt) -- one-time cloud provisioning + state persistence
2. cocoon-net daemon -- long-running service: node setup + DHCP + dynamic routing

Installation

curl -sL https://github.com/cocoonstack/cocoon-net/releases/latest/download/cocoon-net_Linux_x86_64.tar.gz | tar xz
sudo install -m 0755 cocoon-net /usr/local/bin/

Build from source:

git clone https://github.com/cocoonstack/cocoon-net.git
cd cocoon-net
make build

Usage

init -- provision cloud networking

sudo cocoon-net init \
  --platform gke \
  --node-name cocoon-pool \
  --subnet 172.20.100.0/24 \
  --pool-size 140

daemon -- run DHCP server (systemd service)

sudo cocoon-net daemon

The daemon loads the pool from pool.json, configures host networking, and starts the embedded DHCP server. Host routes are managed dynamically: added when a VM gets a lease, removed when the lease expires.

Systemd unit:

[Unit]
Description=cocoon-net VPC networking daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/cocoon-net daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

adopt -- bring an existing node under management

For nodes whose cloud networking was already provisioned by hand:

sudo cocoon-net adopt \
  --platform gke \
  --node-name cocoon-pool \
  --subnet 172.20.0.0/24

status -- show pool state

cocoon-net status

teardown -- remove cloud networking resources

sudo cocoon-net teardown

Flags

Flag	Default	Description
--platform	(required)	Cloud platform (gke or volcengine)
--node-name	(required)	Virtual node name
--subnet	(required)	VM subnet CIDR (e.g. 172.20.100.0/24)
--pool-size	140 (init) / 253 (adopt)	Number of IPs in the pool
--gateway	first IP in subnet	Gateway IP on cni0
--primary-nic	auto-detect	Host primary NIC
--dns	8.8.8.8,1.1.1.1	DNS servers for DHCP clients
--state-dir	/var/lib/cocoon/net	State directory for pool.json
--lease-file	/var/lib/cocoon/net/leases.json	DHCP lease persistence file
--dry-run	false	Preview changes without applying
--skip-iptables	false	(daemon) Skip iptables setup
--manage-iptables	false	(adopt) Let cocoon-net write iptables rules

Environment Variables

Variable	Default	Description
COCOON_NET_LOG_LEVEL	info	Log level (debug, info, warn, error)

CNI Integration

Both init and adopt generate /etc/cni/net.d/30-cocoon-dhcp.conflist:

{
  "cniVersion": "1.0.0",
  "name": "cocoon-dhcp",
  "plugins": [{
    "type": "bridge",
    "bridge": "cni0",
    "isGateway": false,
    "ipMasq": false,
    "ipam": {}
  }]
}

IPAM is intentionally empty -- VMs obtain IPs from the embedded DHCP server. In a CocoonSet:

spec:
  agent:
    network: cocoon-dhcp
    os: windows

Credentials

GKE: Uses application default credentials or GCE instance service account (roles/compute.networkAdmin).

Volcengine: Reads from ~/.volcengine/config.json or environment variables (VOLCENGINE_ACCESS_KEY_ID, VOLCENGINE_SECRET_ACCESS_KEY, VOLCENGINE_REGION).

Development

make build      # build binary
make test       # run tests with coverage
make lint       # golangci-lint (linux + darwin)
make fmt        # gofumpt + goimports
make help       # show all targets

Guides

• GKE VPC-native networking
• Volcengine VPC-native networking

Related Projects

Project	Role
cocoon	MicroVM engine (Cloud Hypervisor + Firecracker)
cocoon-common	Shared metadata, Kubernetes, and logging helpers
cocoon-operator	CocoonSet and Hibernation CRDs
cocoon-webhook	Admission webhook for sticky scheduling
vk-cocoon	Virtual kubelet provider

License

MIT