Volumes

Description and operation

General

A volume is the saved storage of one workspace or one environment. It holds the disk of the source and the chain of snapshots taken of that disk. The volume field of a workspace or an environment names its volume.

A volume stays after its workspace or environment is deleted, while it holds a snapshot. The volume is then detached. You can still restore a workspace from a detached volume. When a volume has no working copy and no snapshot, the platform deletes it.

The snapshots of a volume form its lineage. Each snapshot names the snapshot that came before it. The lineage shows newest first:

backend-base@3 ← backend-base@2 ← backend-base@1      tip (main) = backend-base@3

You take a snapshot to add one to the lineage. A restore starts a working copy at a past snapshot of the lineage.

A clone is not a volume. A clone of a workspace is a second working copy on the volume of its source. A clone of the live state of an environment gets its own new volume with no snapshots.

The list shows only volumes with at least one snapshot that is not in error. It takes the filters kind and owner. owner is you or a team that you belong to.

Names and versions

A volume gets a name on its first push. A name has 1 to 40 characters of a-z, 0-9 and -. It starts with a letter and ends with a letter or a digit. A name cannot start with ws-, env-, sbx-, bench-, bld- or ci-. The words history, refs, snapshots and versions are reserved.

The name is unique among the volumes of one owner, a user or a team. A name stays with its volume until the volume is deleted. There is no rename.

Each push of a named volume is a version, numbered 1, 2, 3 and so on. A number is never reused, and a deleted version leaves a gap. Pushes of a clone or a restore continue the numbers of the volume that they share. A version has the same lifetime as a push.

A reference selects a version. go-base is the highest numbered ready version, and go-base@3 is version 3. A snapshot id is also a reference. Restore, clone, sandbox from_snapshot and pipeline fromSnapshot take a reference.

A reference reads only the volumes of one owner. A volume of another owner is never restored, cloned or started into your owner, by name or by id. The call answers 404. To restore the volume of a team, give the team to the call. In the restore of a workspace the field is team.

An existing volume with no name keeps working by its id. Its next push must name it. Its old pushes have no number, and the first numbered push is version 1.

Owner and quota

A volume belongs to the owner of its workspace or environment. Its disk counts under diskGb against the quota of the owner, also when it is detached. To release that disk, delete snapshots or the detached volume.

Delete rules

A delete of a volume removes all its snapshots. It is refused while a workspace or an environment uses the volume. It is also refused when the volume holds a snapshot of another owner.

A delete is also refused while a pipeline reads the volume or a version. A pipeline reads a volume when its latest version names it in fromSnapshot. A queued or running run reads it from its own version. The refusal names the readers.

A saveTo alone does not block a delete. The next run makes the volume again. When you delete the last snapshot of a detached volume, the volume is deleted and its name is free.

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

Tasks

Show the volumes

Reason for the task: Find the volumes that hold your snapshots, and which of them are detached.

Job set-up

• Access: you.
• References: GET /v1/volumes, GET /v1/volumes/{key}/{name}.

Procedure

1. Show the volumes. Use kind and owner to filter the list.

   PythonCopy

   for v in kl.volumes.list(kind="environment", owner="acme"):    print(v["id"], v["name"], v["latest_version"], v["display_name"], v["deleted"], v["snapshots"], v["last_push_at"])

   TypeScriptCopy

   const volumes = (await kl.volumes.list({ kind: "environment", owner: "acme" })) as Record<string, unknown>[];for (const v of volumes) {  console.log(v.id, v.name, v.latest_version, v.display_name, v.deleted, v.snapshots, v.last_push_at);}

   GoCopy

   volumes, err := kl.Volumes.List(kloudlite.ListVolumes{Kind: "environment", Owner: "acme"})if err != nil {    log.Fatal(err)}for _, v := range volumes {    fmt.Println(v["id"], v["name"], v["latest_version"], v["display_name"], v["deleted"], v["snapshots"], v["last_push_at"])}

   RubyCopy

   kl.volumes.list(kind: "environment", owner: "acme").each do |v|  puts v.values_at("id", "name", "latest_version", "display_name", "deleted", "snapshots", "last_push_at").join(" ")end

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String volumes = kl.volumes().list(new Kloudlite.ListVolumes().kind("environment").owner("acme"));System.out.println(volumes);

   CLICopy

   kloudlite volumes list --kind environment --owner acme

2. Show one volume by its name.

   PythonCopy

   print(kl.volumes.get(owner="acme", name="go-base"))

   TypeScriptCopy

   console.log(await kl.volumes.get({ owner: "acme", name: "go-base" }));

   GoCopy

   v, err := kl.Volumes.Get("acme", "go-base")if err != nil {    log.Fatal(err)}fmt.Println(v)

   RubyCopy

   puts kl.volumes.get(owner: "acme", name: "go-base")

   JavaCopy

   System.out.println(kl.volumes().get("acme", "go-base"));

   CLICopy

   kloudlite volumes get acme/go-base

Close-out

1. Write down the name of the volume, or its id when name is null. Where deleted is true, the volume is detached.

Delete a volume

Reason for the task: Remove a detached volume and all its snapshots to free disk.

Job set-up

• Access: you, or a member of the team that owns the volume.
• Conditions: deleted is true. See Show the volumes.
• References: DELETE /v1/volumes/{key}/{name}, DELETE /v1/volumes/{key}.

Procedure

1. Delete the volume by owner and name, or by id when it has no name.

   PythonCopy

   kl.volumes.delete(owner="acme", name="stack-data")# no name: kl.volumes.delete_by_id(volume="env-1f2e3d4c5b6a7988")

   TypeScriptCopy

   await kl.volumes.delete({ owner: "acme", name: "stack-data" });// no name: await kl.volumes.deleteById({ volume: "env-1f2e3d4c5b6a7988" });

   GoCopy

   if err := kl.Volumes.Delete("acme", "stack-data"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.volumes.delete(owner: "acme", name: "stack-data")# no name: kl.volumes.delete_by_id(volume: "env-1f2e3d4c5b6a7988")

   JavaCopy

   kl.volumes().delete("acme", "stack-data");// no name: kl.volumes().deleteById("env-1f2e3d4c5b6a7988");

   CLICopy

   kloudlite volumes delete acme/stack-data

Close-out

1. Show the volumes as in task 001. Make sure that the name is gone.

Troubleshooting