You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
VPC-native networking setup for [Cocoon](https://github.com/cocoonstack/cocoon) VM nodes on GKE and Volcengine. It provisions cloud networking resources and configures the Linux host so that Windows and Linux VMs obtain VPC-routable IPs directly via DHCP — no overlay network, no iptables DNAT, no `kubectl port-forward` required.
3
+
VPC-native networking for [Cocoon](https://github.com/cocoonstack/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.
4
4
5
5
## Overview
6
6
7
-
-**Platform auto-detection** -- identifies GKE or Volcengine via instance metadata
7
+
-**Embedded DHCP server** on `cni0` bridge, replacing the external DHCP server dependency
8
+
-**Dynamic /32 host routes** added on DHCP lease, removed on expiry
9
+
-**Platform auto-detection** via instance metadata (GKE or Volcengine)
8
10
-**Cloud resource provisioning** -- GKE alias IP ranges or Volcengine ENI secondary IPs
Uses application default credentials or the GCE instance service account. Requires `roles/compute.networkAdmin` or equivalent.
85
-
86
-
**Volcengine**
87
-
88
-
Reads from `~/.volcengine/config.json`:
89
-
90
-
```json
91
-
{
92
-
"access_key_id": "AKxxxx",
93
-
"secret_access_key": "xxxx",
94
-
"region": "cn-hongkong"
95
-
}
96
-
```
97
-
98
-
Or environment variables:
99
-
100
-
```bash
101
-
export VOLCENGINE_ACCESS_KEY_ID=AKxxxx
102
-
export VOLCENGINE_SECRET_ACCESS_KEY=xxxx
103
-
export VOLCENGINE_REGION=cn-hongkong
57
+
make build
104
58
```
105
59
106
60
## Usage
107
61
108
-
### init — full node setup
62
+
### init -- provision cloud networking
109
63
110
64
```bash
111
65
sudo cocoon-net init \
66
+
--platform gke \
112
67
--node-name cocoon-pool \
113
68
--subnet 172.20.100.0/24 \
114
69
--pool-size 140
115
70
```
116
71
117
-
With all flags:
72
+
### daemon -- run DHCP server (systemd service)
118
73
119
74
```bash
120
-
sudo cocoon-net init \
121
-
--node-name cocoon-pool \
122
-
--subnet 172.20.100.0/24 \
123
-
--pool-size 140 \
124
-
--gateway 172.20.100.1 \
125
-
--platform volcengine \
126
-
--primary-nic eth0 \
127
-
--dns "8.8.8.8,1.1.1.1" \
128
-
--state-dir /var/lib/cocoon/net
75
+
sudo cocoon-net daemon
129
76
```
130
77
131
-
Dry run (show what would be done):
78
+
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.
### adopt — bring an existing node under cocoon-net management
97
+
### adopt -- bring an existing node under management
138
98
139
-
For nodes whose cloud networking (alias IP range or secondary ENIs) was already provisioned by hand, `adopt` runs only the host-side configuration (bridge, sysctl, routes, dnsmasq, CNI conflist) and writes the pool state file — without calling any cloud APIs.
99
+
For nodes whose cloud networking was already provisioned by hand:
140
100
141
101
```bash
142
102
sudo cocoon-net adopt \
103
+
--platform gke \
143
104
--node-name cocoon-pool \
144
105
--subnet 172.20.0.0/24
145
106
```
146
107
147
-
By default, adopt preserves the host's existing iptables rules. Opt in to let cocoon-net manage them:
108
+
### status -- show pool state
148
109
149
110
```bash
150
-
sudo cocoon-net adopt \
151
-
--node-name cocoon-pool \
152
-
--subnet 172.20.0.0/24 \
153
-
--manage-iptables
111
+
cocoon-net status
154
112
```
155
113
156
-
Cloud-side teardown must be done manually on adopted nodes — cocoon-net will not undo what it did not provision.
157
-
158
-
### status — show pool state
114
+
### teardown -- remove cloud networking resources
159
115
160
116
```bash
161
-
sudo cocoon-net status
117
+
sudo cocoon-net teardown
162
118
```
163
119
164
-
Output:
120
+
## Flags
165
121
166
-
```
167
-
Platform: volcengine
168
-
Node: cocoon-pool
169
-
Subnet: 172.20.100.0/24
170
-
Gateway: 172.20.100.1
171
-
IPs: 140
172
-
Updated: 2026-04-04T06:00:00Z
173
-
ENIs: 7
174
-
SubnetID: subnet-xxx
175
-
```
122
+
| Flag | Default | Description |
123
+
|---|---|---|
124
+
|`--platform`| (required) | Cloud platform (`gke` or `volcengine`) |
125
+
|`--node-name`| (required) | Virtual node name |
126
+
|`--subnet`| (required) | VM subnet CIDR (e.g. `172.20.100.0/24`) |
127
+
|`--pool-size`|`140` (init) / `253` (adopt) | Number of IPs in the pool |
128
+
|`--gateway`| first IP in subnet | Gateway IP on `cni0`|
129
+
|`--primary-nic`| auto-detect | Host primary NIC |
130
+
|`--dns`|`8.8.8.8,1.1.1.1`| DNS servers for DHCP clients |
131
+
|`--state-dir`|`/var/lib/cocoon/net`| State directory for `pool.json`|
Both `init` and `adopt` generate `/etc/cni/net.d/30-dnsmasq-dhcp.conflist`:
145
+
Both `init` and `adopt` generate `/etc/cni/net.d/30-cocoon-dhcp.conflist`:
186
146
187
147
```json
188
148
{
189
149
"cniVersion": "1.0.0",
190
-
"name": "dnsmasq-dhcp",
191
-
"plugins": [
192
-
{
193
-
"type": "bridge",
194
-
"bridge": "cni0",
195
-
"isGateway": false,
196
-
"ipMasq": false,
197
-
"ipam": {}
198
-
}
199
-
]
150
+
"name": "cocoon-dhcp",
151
+
"plugins": [{
152
+
"type": "bridge",
153
+
"bridge": "cni0",
154
+
"isGateway": false,
155
+
"ipMasq": false,
156
+
"ipam": {}
157
+
}]
200
158
}
201
159
```
202
160
203
-
The CNI IPAM is intentionally empty — Windows guests obtain their IP directly from dnsmasq running on `cni0`. Using `"type": "dhcp"` would cause a dual-DHCP conflict.
204
-
205
-
In a CocoonSet, use `network: dnsmasq-dhcp` to route VM pods through this CNI:
161
+
IPAM is intentionally empty -- VMs obtain IPs from the embedded DHCP server. In a CocoonSet:
206
162
207
163
```yaml
208
164
spec:
209
165
agent:
210
-
network: dnsmasq-dhcp
166
+
network: cocoon-dhcp
211
167
os: windows
212
168
```
213
169
170
+
## Credentials
171
+
172
+
**GKE**: Uses application default credentials or GCE instance service account (`roles/compute.networkAdmin`).
173
+
174
+
**Volcengine**: Reads from `~/.volcengine/config.json` or environment variables (`VOLCENGINE_ACCESS_KEY_ID`, `VOLCENGINE_SECRET_ACCESS_KEY`, `VOLCENGINE_REGION`).
175
+
214
176
## Development
215
177
216
178
```bash
217
-
make build # build binary
218
-
make test # run tests with coverage
219
-
make lint # run golangci-lint (linux + darwin)
220
-
make fmt # format code with gofumpt and goimports
221
-
make deps # tidy modules
222
-
make clean # remove artifacts
223
-
make help # show all targets
179
+
make build # build binary
180
+
make test # run tests with coverage
181
+
make lint # golangci-lint (linux + darwin)
182
+
make fmt # gofumpt + goimports
183
+
make help # show all targets
224
184
```
225
185
226
186
### Guides
@@ -232,11 +192,11 @@ make help # show all targets
0 commit comments