Skip to content

Commit bb39cc3

Browse files
syscod3syscod3
committed
docs: improve plain-language intro and add excalidraw architecture
1 parent 061b580 commit bb39cc3

3 files changed

Lines changed: 306 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@
1616
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
1717

1818
Imp is a Kubernetes operator and node agent for running Firecracker microVM workloads as first-class Kubernetes resources.
19+
In plain terms: it gives you lightweight mini-VMs that behave like disposable app sandboxes, so you can run risky or isolated workloads without giving them access to your whole host.
1920

20-
It provides CRDs for VM lifecycle, VM networking, snapshots, migrations, warm pools, and runner pools, with Cilium-first networking support and a VXLAN fallback for non-Cilium CNIs.
21+
It provides CRDs for VM lifecycle, VM networking, snapshots, migrations, warm pools, and runner pools, with Cilium-first networking support, VXLAN fallback for non-Cilium CNIs, and built-in metrics for VM state, latency, and health.
2122

2223
## What Imp Manages
2324

@@ -31,24 +32,9 @@ It provides CRDs for VM lifecycle, VM networking, snapshots, migrations, warm po
3132

3233
## Architecture
3334

34-
```mermaid
35-
flowchart LR
36-
subgraph K8s[Kubernetes Control Plane]
37-
OP[Imp Operator]
38-
CRD[Imp CRDs]
39-
end
40-
41-
subgraph Node[Worker Node]
42-
AG[Imp Agent DaemonSet]
43-
FC[Firecracker VMM]
44-
GA[Guest Agent]
45-
end
46-
47-
CRD --> OP
48-
OP --> AG
49-
AG --> FC
50-
FC --> GA
51-
```
35+
![Imp architecture (Excalidraw)](docs/diagrams/imp-architecture.svg)
36+
37+
Excalidraw source: `docs/diagrams/imp-architecture.excalidraw`
5238

5339
## Quickstart
5440

@@ -206,6 +192,15 @@ Imp provides first-class integration with **Cilium**. When Cilium is detected:
206192

207193
For non-Cilium CNIs (Flannel/Calico/Weave/etc.), Imp uses a VXLAN fallback for cross-node VM connectivity.
208194

195+
## Metrics & Observability
196+
197+
Imp exposes operator and agent metrics so you can monitor VM lifecycle and platform health:
198+
199+
- VM state and phase metrics
200+
- Scheduling/boot latency metrics
201+
- Guest resource metrics (CPU, memory, disk)
202+
- Prometheus-compatible scraping and dashboards
203+
209204
## Reconcile Sequence
210205

211206
```mermaid

‎docs/diagrams/imp-architecture.excalidraw‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
{
2+
"type": "excalidraw",
3+
"version": 2,
4+
"source": "https://excalidraw.com",
5+
"elements": [
6+
{
7+
"id": "cluster-box",
8+
"type": "rectangle",
9+
"x": 40,
10+
"y": 40,
11+
"width": 920,
12+
"height": 420,
13+
"angle": 0,
14+
"strokeColor": "#1e1e1e",
15+
"backgroundColor": "transparent",
16+
"fillStyle": "hachure",
17+
"strokeWidth": 2,
18+
"strokeStyle": "solid",
19+
"roughness": 1,
20+
"opacity": 100,
21+
"groupIds": [],
22+
"frameId": null,
23+
"roundness": null,
24+
"seed": 101,
25+
"version": 1,
26+
"versionNonce": 1,
27+
"isDeleted": false,
28+
"boundElements": [],
29+
"updated": 1770000000000,
30+
"link": null,
31+
"locked": false
32+
},
33+
{
34+
"id": "cluster-label",
35+
"type": "text",
36+
"x": 64,
37+
"y": 56,
38+
"width": 230,
39+
"height": 25,
40+
"angle": 0,
41+
"strokeColor": "#1e1e1e",
42+
"backgroundColor": "transparent",
43+
"fillStyle": "hachure",
44+
"strokeWidth": 2,
45+
"strokeStyle": "solid",
46+
"roughness": 1,
47+
"opacity": 100,
48+
"groupIds": [],
49+
"frameId": null,
50+
"roundness": null,
51+
"seed": 102,
52+
"version": 1,
53+
"versionNonce": 2,
54+
"isDeleted": false,
55+
"boundElements": [],
56+
"updated": 1770000000001,
57+
"link": null,
58+
"locked": false,
59+
"text": "Kubernetes Cluster",
60+
"fontSize": 20,
61+
"fontFamily": 1,
62+
"textAlign": "left",
63+
"verticalAlign": "top",
64+
"containerId": null,
65+
"originalText": "Kubernetes Cluster",
66+
"lineHeight": 1.25
67+
},
68+
{
69+
"id": "operator",
70+
"type": "rectangle",
71+
"x": 90,
72+
"y": 120,
73+
"width": 280,
74+
"height": 90,
75+
"angle": 0,
76+
"strokeColor": "#0b7285",
77+
"backgroundColor": "#e3fafc",
78+
"fillStyle": "solid",
79+
"strokeWidth": 2,
80+
"strokeStyle": "solid",
81+
"roughness": 1,
82+
"opacity": 100,
83+
"groupIds": [],
84+
"frameId": null,
85+
"roundness": {"type": 3},
86+
"seed": 103,
87+
"version": 1,
88+
"versionNonce": 3,
89+
"isDeleted": false,
90+
"boundElements": [],
91+
"updated": 1770000000002,
92+
"link": null,
93+
"locked": false
94+
},
95+
{
96+
"id": "operator-text",
97+
"type": "text",
98+
"x": 120,
99+
"y": 145,
100+
"width": 230,
101+
"height": 50,
102+
"angle": 0,
103+
"strokeColor": "#0b7285",
104+
"backgroundColor": "transparent",
105+
"fillStyle": "hachure",
106+
"strokeWidth": 2,
107+
"strokeStyle": "solid",
108+
"roughness": 1,
109+
"opacity": 100,
110+
"groupIds": [],
111+
"frameId": null,
112+
"roundness": null,
113+
"seed": 104,
114+
"version": 1,
115+
"versionNonce": 4,
116+
"isDeleted": false,
117+
"boundElements": [],
118+
"updated": 1770000000003,
119+
"link": null,
120+
"locked": false,
121+
"text": "Imp Operator\n(CRD control loop)",
122+
"fontSize": 18,
123+
"fontFamily": 1,
124+
"textAlign": "center",
125+
"verticalAlign": "middle",
126+
"containerId": null,
127+
"originalText": "Imp Operator\n(CRD control loop)",
128+
"lineHeight": 1.25
129+
},
130+
{
131+
"id": "agent",
132+
"type": "rectangle",
133+
"x": 430,
134+
"y": 120,
135+
"width": 220,
136+
"height": 90,
137+
"angle": 0,
138+
"strokeColor": "#2b8a3e",
139+
"backgroundColor": "#ebfbee",
140+
"fillStyle": "solid",
141+
"strokeWidth": 2,
142+
"strokeStyle": "solid",
143+
"roughness": 1,
144+
"opacity": 100,
145+
"groupIds": [],
146+
"frameId": null,
147+
"roundness": {"type": 3},
148+
"seed": 105,
149+
"version": 1,
150+
"versionNonce": 5,
151+
"isDeleted": false,
152+
"boundElements": [],
153+
"updated": 1770000000004,
154+
"link": null,
155+
"locked": false
156+
},
157+
{
158+
"id": "agent-text",
159+
"type": "text",
160+
"x": 460,
161+
"y": 145,
162+
"width": 165,
163+
"height": 50,
164+
"angle": 0,
165+
"strokeColor": "#2b8a3e",
166+
"backgroundColor": "transparent",
167+
"fillStyle": "hachure",
168+
"strokeWidth": 2,
169+
"strokeStyle": "solid",
170+
"roughness": 1,
171+
"opacity": 100,
172+
"groupIds": [],
173+
"frameId": null,
174+
"roundness": null,
175+
"seed": 106,
176+
"version": 1,
177+
"versionNonce": 6,
178+
"isDeleted": false,
179+
"boundElements": [],
180+
"updated": 1770000000005,
181+
"link": null,
182+
"locked": false,
183+
"text": "Imp Agent\n(on each node)",
184+
"fontSize": 18,
185+
"fontFamily": 1,
186+
"textAlign": "center",
187+
"verticalAlign": "middle",
188+
"containerId": null,
189+
"originalText": "Imp Agent\n(on each node)",
190+
"lineHeight": 1.25
191+
},
192+
{
193+
"id": "firecracker",
194+
"type": "rectangle",
195+
"x": 710,
196+
"y": 120,
197+
"width": 210,
198+
"height": 90,
199+
"angle": 0,
200+
"strokeColor": "#6741d9",
201+
"backgroundColor": "#f3f0ff",
202+
"fillStyle": "solid",
203+
"strokeWidth": 2,
204+
"strokeStyle": "solid",
205+
"roughness": 1,
206+
"opacity": 100,
207+
"groupIds": [],
208+
"frameId": null,
209+
"roundness": {"type": 3},
210+
"seed": 107,
211+
"version": 1,
212+
"versionNonce": 7,
213+
"isDeleted": false,
214+
"boundElements": [],
215+
"updated": 1770000000006,
216+
"link": null,
217+
"locked": false
218+
},
219+
{
220+
"id": "firecracker-text",
221+
"type": "text",
222+
"x": 740,
223+
"y": 145,
224+
"width": 150,
225+
"height": 50,
226+
"angle": 0,
227+
"strokeColor": "#6741d9",
228+
"backgroundColor": "transparent",
229+
"fillStyle": "hachure",
230+
"strokeWidth": 2,
231+
"strokeStyle": "solid",
232+
"roughness": 1,
233+
"opacity": 100,
234+
"groupIds": [],
235+
"frameId": null,
236+
"roundness": null,
237+
"seed": 108,
238+
"version": 1,
239+
"versionNonce": 8,
240+
"isDeleted": false,
241+
"boundElements": [],
242+
"updated": 1770000000007,
243+
"link": null,
244+
"locked": false,
245+
"text": "Firecracker\nmicroVMs",
246+
"fontSize": 18,
247+
"fontFamily": 1,
248+
"textAlign": "center",
249+
"verticalAlign": "middle",
250+
"containerId": null,
251+
"originalText": "Firecracker\nmicroVMs",
252+
"lineHeight": 1.25
253+
}
254+
],
255+
"appState": {
256+
"gridSize": null,
257+
"viewBackgroundColor": "#ffffff"
258+
},
259+
"files": {}
260+
}

‎docs/diagrams/imp-architecture.svg‎

Lines changed: 32 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)