Skip to content

Commit efb47d6

Browse files
committed
docs(features): Add snapshot format and disk usage reference
Signed-off-by: Jerome Jaggi <[email protected]>
1 parent 406cdba commit efb47d6

1 file changed

Lines changed: 42 additions & 1 deletion

File tree

pages/features/snapshots.mdx

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,48 @@ ensuring statefulness across different scale-to-zero and scale-to-one cycles,
4848
but also eliminating any long initialization times from heavyweight apps.
4949

5050

51-
## Learn More
51+
## Snapshot format
52+
53+
When Unikraft Cloud snapshots an instance, it saves the full VM state: CPU registers, device state, and memory contents.
54+
55+
Each snapshot consists of two files:
56+
57+
- **State file** — Device state (CPU registers, device model state).
58+
- **Memory file** — Memory contents in a compressed format.
59+
60+
The snapshot format uses LZ4 compression and zero-page deduplication to minimize disk usage.
61+
On-disk snapshot size depends on the amount of memory the app has actually touched, not the total memory allocation.
62+
63+
### Block types
64+
65+
The memory file stores data in blocks.
66+
Each block has a type that determines how Unikraft Cloud stores it:
67+
68+
| Type | Storage |
69+
|------|---------|
70+
| Zero | Not stored on disk — the block contains only zeros. |
71+
| Raw | Full uncompressed block. |
72+
| LZ4 | LZ4-compressed block. Only the compressed payload is stored. |
73+
| Initrd | References the external initrd file. Not stored inline in the snapshot. |
74+
| Kernel | References the external kernel image. Not stored inline in the snapshot. |
75+
76+
### Disk usage
77+
78+
Zero blocks and reference blocks (initrd, kernel) consume no additional disk space in the snapshot.
79+
Raw blocks store the full block contents.
80+
LZ4 blocks store only the compressed payload.
81+
82+
Workloads that touch less memory produce smaller snapshots.
83+
An app that allocates 256 MiB but only writes to 32 MiB of memory produces a snapshot close to 32 MiB (before compression).
84+
85+
### Restore performance
86+
87+
Unikraft Cloud loads memory pages on demand from the snapshot during restore.
88+
Restore time is constant (a few milliseconds) regardless of memory size.
89+
The platform prefetches pages around the first access to reduce page faults during early execution.
90+
91+
## Learn more
5292

5393
* The `kraft cloud` [command-line tool reference](/cli/), and in particular the `deploy` and `instance` subcommands.
5494
* Unikraft Cloud's [REST API reference](/api/platform/v1), and in particular the [scale-to-zero schema](/api/platform/v1/~schemas#instance-scale-to-zero).
95+
* [Instance templates](/features/templates) — Templates use snapshots as their base.

0 commit comments

Comments
 (0)