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

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

SurvivesDoes 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.

ReasonMeaning
CheckpointFailingA 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

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.