Snapshots

Description and operation

General

A snapshot is a saved, read-only copy of a workspace or an environment at one time. It holds the files of the disk and the definition of its source. You push a snapshot to save one. Each push adds one snapshot to the lineage of the volume of its source. The new snapshot names the snapshot before it as its parent. For a push after a restore, see Restore and clone.

before the push:   backend-base@2 ← backend-base@1after the push:    backend-base@3 ← backend-base@2 ← backend-base@1      "before the refactor"

Later you restore a workspace or an environment from a snapshot. A clone is not a snapshot: it copies the live state of a workspace or an environment.

A snapshot stays when its workspace or environment is deleted. The snapshots of one source are kept on one volume. The first push names the volume. See Names and versions.

The platform shows no size for one snapshot. The volume shows the disk that it uses with all its snapshots. For the parts of a snapshot, see Lineage.

A snapshot belongs to the owner of its source. A snapshot of a team workspace or a team environment counts against the quota of the team. You read the snapshots of your own volumes and of the volumes of your teams.

To do these tasks with an AI agent, see Agentic workflows – Volumes.

Snapshot types

The source sets the type of a snapshot. The type sets what the snapshot freezes and how you use it.

A workspace snapshot cannot make an environment, and an environment snapshot cannot make a workspace.

Snapshot parameters

A request to push a snapshot has a body. A request with no body is valid after the volume has a name.

The answer is 202 with id, phase, volume, name, version and expires_at. volume is the volume id. name and version are the volume name and the number of this push. expires_at is null when never is true. Only the versions list of a named volume shows expires_at later.

States

Lifecycle

• Push. A push is the only operation that makes a snapshot.
• Sync points. Between snapshots, the platform keeps internal copies of each running workspace and environment. These sync points are not snapshots. They are never listed, are not a restore target and cannot be deleted by hand.
• Expiry. A snapshot lives for the region default, 30 days, unless the request gives ttl_secs or never. An administrator can change the default.
• Use. A restore or a clone from a snapshot moves its expiry to a full default lifetime from now. An expiry never becomes shorter.
• Expired snapshots. Every 10 minutes the platform deletes expired snapshots, with the rules of a delete by hand. The platform keeps a snapshot that a running workspace or environment uses, or that a pipeline reads.
• Source deleted. A snapshot stays when its workspace or environment is deleted. The volume then stays too, detached, so that you can restore from it.
• Delete. You delete one snapshot at a time, as in Delete a snapshot from the lineage.

Quota and limits

Two quota dimensions apply to snapshots. See Quota and requests.

Tasks

Push a snapshot of a workspace

Reason for the task: Save the files and the definition of a workspace in a snapshot.

Job set-up

• Access: you. A team workspace needs team membership.
• References: POST /v1/workspaces/{id}/snapshots.

Procedure

1. Push a snapshot of the workspace. Give a note in message and a name in volume.

   PythonCopy

   snap = kl.workspaces.take_snapshot(workspace="backend", message="before the refactor", volume="backend-base")print(snap["id"], snap["phase"], snap["expires_at"])

   TypeScriptCopy

   const snap = (await kl.workspaces.takeSnapshot({ workspace: "backend", message: "before the refactor", volume: "backend-base" })) as Record<string, unknown>;console.log(snap.id, snap.phase, snap.expires_at);

   GoCopy

   snap, err := kl.Workspaces.TakeSnapshot(kloudlite.TakeWorkspaceSnapshot{Workspace: "backend", Message: "before the refactor", Volume: "backend-base"})if err != nil {    log.Fatal(err)}fmt.Println(snap["id"], snap["phase"], snap["expires_at"])

   RubyCopy

   snap = kl.workspaces.take_snapshot(workspace: "backend", message: "before the refactor", volume: "backend-base")puts snap.values_at("id", "phase", "expires_at").join(" ")

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String snap = kl.workspaces().takeSnapshot(new Kloudlite.TakeWorkspaceSnapshot().workspace("backend").message("before the refactor").volume("backend-base"));System.out.println(snap);

   CLICopy

   kloudlite snapshots push --workspace backend --message "before the refactor" --volume backend-base

2. Send ttl_secs or never in a raw request in place of step 1, to set the lifetime.

   PythonCopy

   ws = kl.workspaces.get(workspace="backend")kl.request("POST", f"/v1/workspaces/{ws['id']}/snapshots", body={"ttl_secs": 604800})

   TypeScriptCopy

   const ws = (await kl.workspaces.get({ workspace: "backend" })) as { id: string };await kl.request("POST", `/v1/workspaces/${ws.id}/snapshots`, { ttl_secs: 604800 });

   GoCopy

   ws, err := kl.Workspaces.Get("backend")if err != nil {    log.Fatal(err)}err = kl.Request("POST", fmt.Sprintf("/v1/workspaces/%v/snapshots", ws["id"]), kloudlite.RequestOptions{    Body: map[string]any{"ttl_secs": 604800},})if err != nil {    log.Fatal(err)}

   RubyCopy

   ws = kl.workspaces.get(workspace: "backend")kl.request("POST", "/v1/workspaces/#{ws['id']}/snapshots", body: { ttl_secs: 604800 })

   JavaCopy

   // The path takes the name of the workspace in place of its id.kl.request(new Kloudlite.RawRequest()    .method("POST")    .path("/v1/workspaces/backend/snapshots")    .body("{\"ttl_secs\":604800}"));

   CLICopy

   kloudlite request POST /v1/workspaces/ws-0a1b2c3d4e5f6a7b/snapshots --body '{"ttl_secs": 604800}'

Close-out

1. Show the lineage, as in Show the lineage. Make sure that the first row shows your note and the phase ready.

Push a snapshot of an environment

Reason for the task: Save the services and the data of an environment in a snapshot.

Job set-up

• Access: you. A team environment needs team membership.
• References: POST /v1/environments/{id}/snapshots.

Procedure

1. Push a snapshot of the environment. Use team/name for a team environment, and give volume.

   PythonCopy

   snap = kl.environments.take_snapshot(environment="acme/dev", message="before the schema change", volume="dev-data")print(snap["id"], snap["phase"], snap["expires_at"])

   TypeScriptCopy

   const snap = (await kl.environments.take_snapshot({ environment: "acme/dev", message: "before the schema change", volume: "dev-data" })) as Record<string, unknown>;console.log(snap.id, snap.phase, snap.expires_at);

   GoCopy

   snap, err := kl.Environments.TakeSnapshot(kloudlite.TakeEnvironmentSnapshot{Environment: "acme/dev", Message: "before the schema change", Volume: "dev-data"})if err != nil {    log.Fatal(err)}fmt.Println(snap["id"], snap["phase"], snap["expires_at"])

   RubyCopy

   snap = kl.environments.take_snapshot(environment: "acme/dev", message: "before the schema change", volume: "dev-data")puts snap.values_at("id", "phase", "expires_at").join(" ")

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String snap = kl.environments().takeSnapshot(new Kloudlite.TakeEnvironmentSnapshot().environment("acme/dev").message("before the schema change").volume("dev-data"));System.out.println(snap);

   CLICopy

   kloudlite snapshots push --environment acme/dev --message "before the schema change" --volume dev-data

Close-out

1. Show the lineage, as in Show the lineage. Make sure that the first row shows your note and the phase ready.

Troubleshooting