Volume 与导出恢复

Volume独立于任何 Workspace 存在的持久卷。一个 Workspace 最多绑定一个 Volume，默认挂载在 /data。 存放 Workspace 的数据，独立于任何 Workspace 存在。本页介绍创建 Workspace 时怎样选择 Volume，Volume 的创建与扩容、换绑，以及把 Workspace 的数据导出、恢复成新的 Workspace。

创建时的 Volume复制标题链接

每个 Workspace 默认带一个新建的 Volume，挂在 /data，并标记为随 Workspace 删除。只有这个路径承诺在停止、启动之间保留数据。

预先创建一个 Volume，在创建 Workspace 时把它绑定到另一个路径：

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

kibo workspace create 中与 Volume 有关的参数：

• --volume 与 --no-volume 互斥，--no-volume 也不能与 --mount-path、--delete-with-workspace 同时使用。
• 参数冲突或路径非法时，在发请求前就被拒绝。
• 预先创建 Volume 用 kibo volume create 或 kibo transfer import。

「随 Workspace 删除」是绑定的属性，不是 Volume 的种类。Workspace 停止后可以换绑、改路径、翻转这个开关或解绑，见绑定、换绑与解绑 Volume。

管理 Volume复制标题链接

kibo volume create、resize 与 delete 在请求内完成，输出显示结果状态。结果丢失时按命令 ID 查询，见结果未知时。

创建 Volume复制标题链接

创建一个不属于任何 Workspace 的 Volume：

kibo volume create --capacity 10G

• 不传 --capacity 时，容量由 node 的存储配置决定。
• --capacity 按二进制单位写大小，如 10G、512MiB。GB、MB 会被拒绝，改写成 G 或 GiB。这类写法、非正数与无法解析的值都在发请求前被拒绝，见大小与 CPU 的写法。
• 不传 --command-id 时，kibo 自动生成一个，并在输出的 command_id 中返回。
• 之后用 kibo workspace create --volume 或 kibo workspace volume bind 绑定。删除 Workspace 时默认只解除绑定。

查看 Volume复制标题链接

列出 Volume，或查看其中一个：

kibo volume list
kibo volume get "$volume_id"

• 两条命令都显示 Volume 的容量与当前绑定的 Workspace。
• 所有 Volume 都有确定的容量，包括随 Workspace 创建的；服务端没有返回容量时显示 unknown。
• 列表默认不显示已删除的 Volume，见列表过滤。

扩容 Volume复制标题链接

先停止使用这个 Volume 的 Workspace，再把 Volume 扩到总共 20 GiB：

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

• --capacity 必填，是扩容后的总容量，只能增大。
• 等于当前容量时命令成功但不做任何事；小于当前容量时返回 invalid_argument。
• 只有未挂载的 Volume 能扩容。Volume 仍挂载在 node 上，或它所属的 Workspace 正在运行时，返回 failed_precondition。
• 扩容期间 Volume 状态为 RESIZING。node 同时扩大 Volume 中的文件系统，Workspace 再次启动后 guest 即可使用新容量。

删除 Volume复制标题链接

删除不再需要的 Volume：

kibo volume delete "$volume_id"

kibo 会先请求确认，--yes 跳过确认。除了这条命令，只有在删除 Workspace 且绑定设置为随 Workspace 删除时，Volume 才会被删除，见删除。

结果未知时复制标题链接

create、delete、resize 的响应丢失时，按命令 ID 查询结果：

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

输出给出 status、error 与对应的 result。不要换 ID 重新提交。用法与 kibo workspace command get 相同。

绑定、换绑与解绑 Volume复制标题链接

kibo workspace volume bind 把一个已有的 Volume 绑定到已停止的 Workspace。目标是完整的绑定：换成另一个 Volume、只改挂载路径、只翻转「随 Workspace 删除」开关，都是再次执行这条命令并写出想要的最终值。

把一个新的 Volume 绑定到 /srv/data，再带着它启动 Workspace：

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"

解除已停止 Workspace 的绑定：

kibo workspace volume unbind "$workspace_id"

前提条件复制标题链接

• 与调整资源相同：Workspace 不持有执行。运行中返回 failed_precondition，先执行 kibo workspace stop。
• 目标 Volume 必须存在、处于 AVAILABLE、没有被其他未删除的 Workspace 绑定，并且所在的存储池能被这个 Workspace 当前放置的 node 访问。不满足时分别返回 not_found 与 failed_precondition，绑定不变。

改绑定的效果复制标题链接

• 被换掉或解绑的 Volume 不会被删除：它回到 AVAILABLE，数据原样保留，可以绑到别的 Workspace，或用 kibo volume delete 显式删除。这与它的开关无关；开关只决定 kibo workspace delete 的行为。
• 新绑定在下一次 kibo workspace start 时挂载。
• 解绑后的 Workspace 没有承诺持久的路径，不能 kibo transfer export。
• 换路径后，旧挂载点留在可写层里，只是一个普通目录。

绑定版本复制标题链接

该命令使用乐观锁，版本是 binding_revision，即 workspace get --wide 中 Revisions 一节的 Volume binding。

• 不传 --expected-revision 时，kibo 先读取当前版本再提交。
• 提交时版本已变化则返回 aborted，不自动重试。
• 脚本需要重放时，把 --command-id 与 --expected-revision 一起传入。
• 提交与当前完全相同的绑定不改变版本。这个版本与 update 用的资源版本各自独立。

导出、导入与恢复复制标题链接

Transfer把已停止 Workspace 的 Volume 导出成归档。归档可以导入为新的 Volume，再恢复成新的 Workspace。 把一个已停止 Workspace 的 Volume 内容复制成新的 Volume，再用它创建新的 Workspace。它分三步，每一步在 ctrl 接受之后由 ctrl 自己执行到底，ctrl 重启或 node 短暂不可达时 ctrl 自行重试。

导出已停止的 Workspace，把归档导入成新的 Volume，再用它恢复出 Workspace：

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

导出复制标题链接

• export 要求 Workspace 处于 STOPPED 且绑定了 Volume。
• 完成后 Transfer 为 COMPLETE，输出里的 manifest 给出文件数、归档大小、SHA-256 和过期时间。
• .kibotos/credentials 和 .kibotos/browser-state 两个目录不会被导出。
• 归档不压缩，大小与其中的文件相当。单个归档默认不超过 1 GiB，部署方可以修改这个上限。
• 归档超过上限的导出以 resource_exhausted 失败，Transfer 进入 FAILED。减少 Volume 里的数据，或请部署方调高上限，再重新导出。

导入复制标题链接

• import 创建一个新的 Volume。默认落在被导出 Volume 所在的存储池；--storage-pool 指定另一个池。
• 由哪台 node 执行导入由部署决定，只要它接入目标池。
• 因为没有可用的 node 或池容量不足而失败的导入不消耗 Transfer，它仍是 COMPLETE，稍后换一个命令 ID 再导入。
• 在 node 上失败的导入让 Transfer 进入 FAILED，需要重新导出。

恢复复制标题链接

• restore 用导入得到的 Volume 和你给出的规格创建新的 Workspace，--cpu、--memory、--disk 的写法与 workspace create 相同。
• 会话、凭证、进程和登录状态需要重新建立。

等待 Transfer 完成复制标题链接

大的 Volume 导出与导入要几分钟。kibo 用同一个命令 ID 重发，直到命令完成或到 --wait-timeout：

等待结束或按 Ctrl-C 不会撤回命令。用原来的 --command-id 再运行，接着等它的结果。

归档的保留复制标题链接

归档存放在部署的 artifact store 里，默认保留 24 小时，部署方可以修改保留时间。大小上限见导出。

• 过了保留时间还没有导入的 Transfer 变为 EXPIRED，之后 import 返回 failed_precondition，需要重新导出。
• 已经导入或恢复的 Transfer 不受过期影响，导入得到的 Volume 和恢复出的 Workspace 照常使用。
• kibo transfer delete 立即删除归档，不需要任何 node 在线。导出、导入或恢复还在进行时返回 failed_precondition。

用 API复制标题链接

Volume复制标题链接

Volume 用 VolumeService 管理：创建、扩容与删除在请求内完成，响应带回结果状态。

Transfer复制标题链接

TransferService 的方法是 ExportWorkspace、ImportTransfer、RestoreWorkspace、GetTransfer 与 DeleteTransfer。

三个写方法最长等命令完成 1 分钟，超时返回可重试的 unavailable，命令继续执行，见幂等键。

注意复制标题链接

• 部署方可以用 kibo volume move 与 kibo workspace move-layer 把 Volume 或可写层搬到另一个存储池，见在池之间搬迁对象。
• 搬迁期间，启动所属或绑定它的 Workspace、扩容、绑定或解绑、删除与导出都返回可重试的 unavailable（退出码 15），搬迁结束后再试。

下一步复制标题链接

• 创建与列表：kibo workspace create 的其他参数。
• 生命周期：删除 Workspace 时 Volume 会怎样。
• 保证与边界：哪些数据在什么情况下保留。