Checkpoints and forks

A checkpoint captures a machine as it is at that instant, memory included. A restore puts the moment back: the same processes, the same open files, the same half finished thing you were in the middle of.

Take one before the risky step

pilot machine checkpoint scratch
pilot machine checkpoints scratch

The capture pauses the guest briefly, writes the memory and the disk as content-addressed blocks, and returns an id. Blocks that already exist are not written again, so a second checkpoint of the same machine stores the difference rather than the whole thing.

Put it back

pilot machine restore ck-3a3077f4d51c9b0e7a624f18

A restore is IN PLACE. The machine keeps its id, its name and its URL, and what was running at the moment of the checkpoint is running again when it finishes. That is also why it is destructive: everything the machine did after the checkpoint is gone. Confirm it with whoever owns the machine first, and an agent driving the API must ask before calling it.

Branch instead of overwriting

A fork makes a NEW machine from a machine or from one of its checkpoints, with its own id and its own URL. Use it to try two answers from one starting point, or to give every run of a test suite the same warm state.

pilot machine fork scratch
pilot machine fork ck-3a3077f4d51c9b0e7a624f18

A chain is two levels deep

A machine's disk is a template plus one per-machine difference, and the depth of that chain is exactly 2. A checkpoint of a checkpoint of a checkpoint is refused when the header is parsed rather than failing later at fault time, which is the difference between an error you can read and an error at three in the morning.

What a restore promises

A restore never fails because a memory image is gone. Memory snapshots carry raw processor identification, so an image is portable within a vendor pool and never across one. When no host of that pool is live, the machine cold-boots from its own disk instead.