Skip to content

Commit 2115931

Browse files
cdalarclaude
andcommitted
docs(fc): add local testing guide for the fc provider rename
Walkthrough for testing this branch on a GCP fc-host VM: building/copying the binary, running create/pause/resume/destroy against the new `fc` provider and flags, and confirming the old `firecracker` provider name is rejected. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ha7EmqjjYwGC3f1wk41TE2
1 parent 0c95d4d commit 2115931

1 file changed

Lines changed: 90 additions & 0 deletions

File tree

‎TESTING-fc.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Testing the `fc` provider (this branch)
2+
3+
How to test the renamed Firecracker provider (`firecracker` → `fc`) and its new
4+
zero-YAML CLI flags, on a GCP `fc-host` VM. The host-setup script already
5+
installs KVM + the `firecracker` binary + kernel/rootfs images under
6+
`~/.onctl/firecracker/images/`; this guide tests the **new `onctl` binary**
7+
(renamed provider `fc` + new flags) talking to that host.
8+
9+
## 1. Build this branch for the host (linux/amd64)
10+
11+
From your workstation, on branch `firecracker-flags-no-yaml`:
12+
13+
```bash
14+
GOOS=linux GOARCH=amd64 go build -o onctl-fc .
15+
```
16+
17+
## 2. Provision / reuse the fc-host (if you don't have one)
18+
19+
```bash
20+
# nested-virt GCP VM with KVM + firecracker + images under ~/.onctl/firecracker/images
21+
ONCTL_CLOUD=gcp onctl create -n fc-host -a firecracker/firecracker-host-setup.sh
22+
```
23+
24+
If `fc-host` already exists, skip this.
25+
26+
## 3. Copy the new binary onto the host
27+
28+
```bash
29+
HOST_IP=$(ONCTL_CLOUD=gcp onctl ls | awk '/fc-host/{print $4}') # confirm column for IP
30+
scp onctl-fc <user>@$HOST_IP:/tmp/onctl
31+
onctl ssh fc-host # or: ssh <user>@$HOST_IP
32+
sudo install /tmp/onctl /usr/local/bin/onctl # replace any old release
33+
onctl version
34+
```
35+
36+
## 4. Run the `fc` provider on the host
37+
38+
`fc` needs `CAP_NET_ADMIN` (tap/bridge) → run as **root**. Note that
39+
`~/.onctl/firecracker` is per-user, so under `sudo` it resolves to
40+
`/root/.onctl/...`. Two options:
41+
42+
**A — point at the images the setup script downloaded (recommended):**
43+
```bash
44+
KIMG=$HOME/.onctl/firecracker/images/vmlinux
45+
RIMG=$HOME/.onctl/firecracker/images/rootfs.ext4
46+
47+
sudo onctl create -n mv1 --provider fc \
48+
--kernel-image "$KIMG" --rootfs-image "$RIMG"
49+
```
50+
51+
**B — zero-config (tests the new defaults):** put images at
52+
`/root/.onctl/firecracker/images/{vmlinux,rootfs.ext4}`, then just:
53+
```bash
54+
sudo ONCTL_CLOUD=fc onctl create -n mv1
55+
```
56+
This exercises the Phase-1 defaults (`fc.kernelImage`/`fc.rootfsImage` now
57+
default to `~/.onctl/firecracker/images/...` with no YAML).
58+
59+
## 5. Verify the microVM and the rename
60+
61+
```bash
62+
sudo ONCTL_CLOUD=fc onctl ls # Provider column should read "fc"
63+
sudo ONCTL_CLOUD=fc onctl ls | grep mv1 # grab its IP
64+
ssh root@<microvm-ip> # your pubkey was injected into the rootfs
65+
66+
# new flags work:
67+
sudo onctl create -n mv2 --provider fc --vcpu 2 --memory 1024 \
68+
--kernel-image "$KIMG" --rootfs-image "$RIMG"
69+
70+
# pause / resume:
71+
sudo ONCTL_CLOUD=fc onctl pause mv2 && sudo ONCTL_CLOUD=fc onctl resume mv2
72+
73+
# cleanup:
74+
sudo ONCTL_CLOUD=fc onctl destroy mv1 -f && sudo ONCTL_CLOUD=fc onctl destroy mv2 -f
75+
```
76+
77+
## 6. Confirm the old name is gone (the actual rename check)
78+
79+
```bash
80+
sudo ONCTL_CLOUD=firecracker onctl ls # expect: unsupported provider "firecracker"
81+
sudo onctl create -n x --provider firecracker # same — should be rejected
82+
onctl create --help | grep -E 'kernel-image|rootfs-image|fc-binary|vcpu|memory' # new flags present
83+
```
84+
85+
## Notes
86+
87+
- **`onctl ls` IP column** — double check the column index in step 3; it may
88+
differ across `onctl` versions.
89+
- **`--username`** now also sets the fc microVM SSH user (defaults to
90+
`root`); if your rootfs uses a different user, pass `--username`.

0 commit comments

Comments
 (0)
⌂ 换网址