Guides / Compute
Hibernate and resume a process
This guide takes a resident process off its machine and brings it back without losing its place. The process is written to a bucket and released, and later it continues with its memory, timers and open TCP connections. It keeps its MAC address and addresses, and while it is hibernated it is not metered as running.
Before you start
- A process with
spec.residency: Resident. An ephemeral process has no memory to keep. - A Storage bucket in the same project to hold the snapshots (Store and fetch objects).
- A program that keeps what it needs in ordinary memory, as programs written with the Rust SDK do. The program must be the same one before and after.
1. Create the bucket and the process
kubectl apply -f - <<EOF
apiVersion: storage.etorm.com/v1alpha1
kind: Bucket
metadata: {name: snaps}
spec:
description: process snapshots
---
apiVersion: compute.etorm.com/v1alpha1
kind: Process
metadata: {name: echo}
spec:
programRef: {name: tcp-echo}
interfaces:
- {name: eth0, vpcRef: {name: lan}}
residency: Resident
hibernation:
bucketRef: {name: snaps}
resources: {memoryPower: 5}
EOF
The program tcp-echo is the one built in Run a TCP service. hibernation.bucketRef is required, and the bucket is added to spec.buckets for you.
Admission refuses a process that is not resident, whose bucket does not exist in the project, or that is set to Hibernated without hibernation.
2. Hibernate it
kubectl patch process echo --type merge -p '{"spec":{"desiredState":"Hibernated"}}'
kubectl get process echo -o jsonpath='{.status.phase}{"\n"}'
# Hibernated
kubectl get process echo -o jsonpath='{.status.snapshot}'
# {"generation":1,"takenAt":"2026-11-11T12:40:03Z","bytes":196753,"memoryPages":3,"node":"gw-1","reason":"Hibernated"}
While the machine writes the snapshot, the phase is Ready with reason Hibernating. Then it becomes Hibernated. A call in progress finishes first, because the snapshot is taken between calls. Once the snapshot is written, the machine lets go of the process. status.node is empty, and the process receives nothing.
A snapshot holds the program's memory (only pages that are not all zero), its state, its timers and its schedule positions. It is sealed by the bucket like any object and is written as a new, numbered object, never over an old one. The two newest are kept.
3. Continue it
kubectl patch process echo --type merge -p '{"spec":{"desiredState":"Running"}}'
kubectl get process echo -o jsonpath='{.status.restoredFrom}'
# {"generation":1,"at":"2026-11-11T12:41:10Z","reason":"Resumed"}
The machine that serves the process's VPCs takes it back, restores the newest snapshot and calls the program's start with the reason Restored. restoredFrom.reason is Resumed. The process keeps its MAC and its addresses, so its neighbours need no change. A program that talks on the network should still announce itself again in start. For TCP, the SDK's Stack::announce does that.
The phase can show Hibernated for up to a minute after the process runs again, because the controller derives it on its next pass. status.node and restoredFrom are up to date at once.
What survives hibernation
| Survives | Does not |
|---|---|
| Memory of the program: variables, caches, protocol state, the program's whole value. | Frames queued for the process at that moment. They are dropped, as when a link goes down. |
Durable state set with set_state. | A call in progress. The snapshot is taken between calls. |
Timers and schedule positions. A timer that fell due while the process was away fires once, late. Ticks of a schedule that were missed arrive as one, with missed set. | Usage counters of the machine, and the memory and processor allowances: those come from the spec. |
| Open TCP connections of the SDK's stack. The peer sees a pause, TCP retransmits, and the same connection carries on. | Anything the program never put in its own memory. |
The program's clock (now) continues from where it was plus the time that passed, so a program that measures durations sees the real gap.
If something goes wrong
status.snapshotIssue has a reason and a message, and the process gets a condition Snapshots with that reason.
| Reason | Meaning |
|---|---|
CheckpointFailing | A snapshot could not be written (the bucket is unreachable or refuses). The process stays running and the machine retries. |
A snapshot is for continuity of the program, not a record to rely on. A program that must not lose a write stores it in a bucket or a database before it answers.
Limits
- You hibernate and continue a process with
desiredState. - A process hibernates and continues on the machine that serves its VPCs.
- A process that is deleted leaves its snapshots in the bucket. Set it to
Stoppedfirst, and the snapshots are deleted. - A program that rewrites its tables at run time cannot be snapshotted.
Clean up
kubectl patch process echo --type merge -p '{"spec":{"desiredState":"Stopped"}}'
kubectl delete process echo
kubectl delete bucket snaps
Stopped deletes the state and the snapshots. Deleting a bucket makes every object in it unreadable at once (see Delete things safely).
Next
Wake a process on a timer or a schedule, or the Compute program interface.