Volumes, export, and restore

A VolumeA persistent volume that exists independently of any Workspace. A Workspace binds at most one Volume, mounted at /data by default. stores a Workspace's data and exists independently of any Workspace. This page shows how to choose a Volume when you create a Workspace, create and resize Volumes, rebind them, and export a Workspace's data to restore it as a new Workspace.

Volumes at creationCopy Anchor Link

By default each Workspace gets a new Volume mounted at /data and marked for deletion with the Workspace. Only this path is guaranteed to keep data across stop and start.

Create a Volume ahead of time and bind it at another path when you create the Workspace:

volume_id=$(kibo volume create --capacity 10G -q)
kibo workspace create --template "$template_id" --volume "$volume_id" --mount-path /srv/data

The Volume parameters of kibo workspace create:

• --volume and --no-volume are mutually exclusive. --no-volume also excludes --mount-path and --delete-with-workspace.
• Conflicts and invalid paths are rejected before the request is sent.
• To create a Volume ahead of time, use kibo volume create or kibo transfer import.

"Delete with the Workspace" is a property of the binding, not a kind of Volume. After the Workspace stops, you can rebind, change the path, flip this setting, or unbind. See Binding, rebinding, and unbinding Volumes.

Managing VolumesCopy Anchor Link

kibo volume create, resize, and delete complete within the request, and the output shows the resulting state. If the result is lost, query it by command ID. See Unknown results.

Creating a VolumeCopy Anchor Link

Create a Volume that belongs to no Workspace:

kibo volume create --capacity 10G

• Without --capacity, the capacity is set by the node's storage configuration.
• --capacity takes a binary size such as 10G or 512MiB. GB and MB are rejected; use G or GiB. These, non-positive values, and values that cannot be parsed are rejected before the request is sent. See Size and CPU formats.
• Without --command-id, kibo generates one and returns it in the command_id of the output.
• Bind the Volume afterwards with kibo workspace create --volume or kibo workspace volume bind. Deleting the Workspace only unbinds it by default.

Viewing VolumesCopy Anchor Link

List Volumes, or show one of them:

kibo volume list
kibo volume get "$volume_id"

• Both show a Volume's capacity and the Workspace currently bound to it.
• Every Volume has a defined capacity, including Volumes created with a Workspace. When the server returns no capacity, the output shows unknown.
• The list does not show deleted Volumes by default. See Filtering lists.

Resizing a VolumeCopy Anchor Link

Stop the Workspace that uses the Volume, then grow the Volume to a total of 20 GiB:

kibo workspace stop "$workspace_id"
kibo volume resize "$volume_id" --capacity 20G

• --capacity is required. It is the total capacity after resizing and can only grow.
• When it equals the current capacity, the command succeeds and does nothing. When it is smaller than the current capacity, the command returns invalid_argument.
• Only an unmounted Volume can be resized. When the Volume is still mounted on a node, or the Workspace it belongs to is running, the command returns failed_precondition.
• During the resize, the Volume state is RESIZING. The node also grows the file system in the Volume, and the guest can use the new capacity once the Workspace starts again.

Deleting a VolumeCopy Anchor Link

Delete a Volume you no longer need:

kibo volume delete "$volume_id"

kibo asks for confirmation first, and --yes skips it. Apart from this command, a Volume is deleted only when you delete its Workspace and the binding says to delete it. See Delete.

Unknown resultsCopy Anchor Link

When the response to a create, delete, or resize is lost, query the result by command ID:

kibo volume command get "$volume_id" "$command_id"

The output gives status, error, and the corresponding result. Do not resubmit with a different ID. It works the same way as kibo workspace command get.

Binding, rebinding, and unbinding VolumesCopy Anchor Link

kibo workspace volume bind binds an existing Volume to a stopped Workspace. The target is the complete binding: to switch to another Volume, change only the mount path, or only flip the "delete with Workspace" switch, run this command again with the final values you want.

Bind a new Volume at /srv/data and start the Workspace with it:

workspace_id=workspace-example
volume_id=$(kibo volume create --capacity 10G -q)
kibo workspace stop "$workspace_id"
kibo workspace volume bind "$workspace_id" --volume "$volume_id" --mount-path /srv/data
kibo workspace start "$workspace_id"

Remove the binding of a stopped Workspace:

kibo workspace volume unbind "$workspace_id"

RequirementsCopy Anchor Link

• The prerequisites are the same as for Adjusting resources: the Workspace must not hold an execution. While it is running, the command returns failed_precondition. Run kibo workspace stop first.
• The target Volume must exist, be AVAILABLE, not be bound by another Workspace that is not deleted, and be in a storage pool that the node where this Workspace is currently placed can access. Otherwise the command returns not_found or failed_precondition respectively, and the binding does not change.

Effects of a binding changeCopy Anchor Link

• A Volume that is replaced or unbound is not deleted. It returns to AVAILABLE with its data intact, and you can bind it to another Workspace or delete it explicitly with kibo volume delete. This does not depend on its switch; the switch only decides what kibo workspace delete does.
• The new binding is mounted at the next kibo workspace start.
• An unbound Workspace has no guaranteed persistent path, so you cannot run kibo transfer export on it.
• After you change the path, the old mount point stays in the writable layer as an ordinary directory.

Binding revisionCopy Anchor Link

The command uses optimistic locking with the revision binding_revision, shown as Volume binding in the Revisions section of workspace get --wide.

• Without --expected-revision, kibo reads the current revision first and then submits.
• If the revision changed by the time of submission, the command returns aborted and does not retry automatically.
• When a script needs to replay, pass --command-id and --expected-revision together.
• Submitting a binding identical to the current one does not change the revision. This revision is independent of the resources revision used by update.

Export, import, and restoreCopy Anchor Link

A TransferAn export of the Volume of a stopped Workspace to an archive. You can import the archive as a new Volume and restore it as a new Workspace. copies the Volume contents of a stopped Workspace into a new Volume, then creates a new Workspace from it. It has three steps. Once ctrl accepts a step, ctrl carries it out to the end on its own and retries by itself when ctrl restarts or a node is briefly unreachable.

Export a stopped Workspace, import the archive as a new Volume, and restore a Workspace from it:

kibo transfer export "$workspace_id"
kibo transfer import "$transfer_id"
kibo transfer restore "$transfer_id" --volume "$volume_id" --template "$template_id"

ExportCopy Anchor Link

• export requires the Workspace to be STOPPED with a Volume bound.
• When it completes, the Transfer is COMPLETE, and the manifest in the output gives the file count, archive size, SHA-256, and expiration time.
• The two directories .kibotos/credentials and .kibotos/browser-state are not exported.
• The archive is not compressed, so it is about as large as the files it contains. It is at most 1 GiB by default, and the deployer can change this limit.
• An export whose archive exceeds the limit fails with resource_exhausted, and the Transfer moves to FAILED. Reduce the data in the Volume, or ask the deployer to raise the limit, then export again.

ImportCopy Anchor Link

• import creates a new Volume. By default it lands in the storage pool of the exported Volume; --storage-pool chooses another pool.
• The deployment decides which node runs the import, as long as that node is connected to the target pool.
• An import that fails because no node is available or the pool lacks capacity does not consume the Transfer. The Transfer stays COMPLETE; import again later with a different command ID.
• An import that fails on the node moves the Transfer to FAILED, and you need to export again.

RestoreCopy Anchor Link

• restore creates a new Workspace from the imported Volume and the spec you give. --cpu, --memory, and --disk take the same form as in workspace create.
• Sessions, credentials, processes, and sign-in state need to be established again.

Waiting for a TransferCopy Anchor Link

Exporting and importing a large Volume takes a few minutes. kibo resends with the same command ID until the command completes or --wait-timeout is reached:

Ending the wait or pressing Ctrl-C does not withdraw the command. Run it again with the original --command-id to keep waiting for its result.

Archive retentionCopy Anchor Link

Archives are stored in the deployment's artifact store. By default they are kept for 24 hours, and the deployer can change this period. For the size limit, see Export.

• A Transfer not imported before the retention period ends becomes EXPIRED. After that, import returns failed_precondition, and you need to export again.
• Transfers that were already imported or restored are not affected by expiration. The imported Volume and the restored Workspace keep working as usual.
• kibo transfer delete deletes the archive immediately and needs no node to be online. While an export, import, or restore is still in progress, it returns failed_precondition.

With the APICopy Anchor Link

VolumesCopy Anchor Link

Volumes are managed with VolumeService. Create, resize, and delete complete within the request, and the response carries the resulting state.

TransfersCopy Anchor Link

The methods on TransferService are ExportWorkspace, ImportTransfer, RestoreWorkspace, GetTransfer, and DeleteTransfer.

The three write methods wait at most 1 minute for the command to complete. A timeout returns a retryable unavailable and the command keeps running. See Command IDs.

NotesCopy Anchor Link

• The deployer can move a Volume or writable layer to another storage pool with kibo volume move and kibo workspace move-layer. See Moving objects between pools.
• While a move is in progress, starting a Workspace that owns or binds the object, resizing, binding or unbinding, deleting, and exporting all return a retryable unavailable (exit code 15). Try again after the move settles.

Next stepsCopy Anchor Link

• Creating and listing: the other parameters of kibo workspace create.
• Lifecycle: what deleting a Workspace does to its Volume.
• Guarantees and limits: which data is kept in which case.