labels 与 annotations

labels 与 annotations 是你保存在 Workspace、Volume、Egress 与 Resolver 上的自有键值数据。本页介绍怎样设置和修改它们，以及怎样按 label 查找资源。

概述复制标题链接

这几种资源各有两组字符串到字符串的映射，给上层调用方存自己的数据。ctrl 不解释它们，不据此调度、授权或计费。规则沿用 Kubernetes。

创建时给出复制标题链接

创建 Workspace、Volume、Egress 或 Resolver 时传 --label 与 --annotation：

kibo workspace create --template "$template_id" --label team=infra --annotation note='nightly build'
kibo volume create --capacity 10G --label team=infra
kibo egress create --address proxy.example.com:1080 --label team=infra
kibo resolver create --https https://dns.example.com/dns-query --label team=infra

• 两个参数都可重复，格式 key=value。
• 只在第一个 = 处切分，所以 annotation 的值可以含 =；key= 表示值为空。
• 同一个 key 重复给出时，在发请求前就被拒绝。
• labels 与 annotations 与创建命令在同一个事务里写入，也参与幂等比较：同一个幂等键换一份数据重放会冲突。

按 label 筛选复制标题链接

在 kibo workspace list、volume list、egress list 或 resolver list 上传 -l 或 --label：

kibo workspace list --label team=infra --label tier=gold
kibo volume list --include-deleted -l team=infra
kibo egress list -l team=infra

• 每个条目要求 label 存在且值逐字节相等，多个条目须同时满足。
• annotations 不参与筛选。
• 在 Workspace 与 Volume 的列表上，可以与其他过滤条件、--include-deleted 组合。已删除的 Workspace 与 Volume 仍返回两组数据，也能被选中。
• kibo 的下一页提示里带着同样的筛选条件。

修改复制标题链接

set 替换资源的 labels 或 annotations，clear 删除全部：

kibo workspace labels set "$workspace_id" team=infra tier=gold
kibo workspace labels clear "$workspace_id"
kibo workspace annotations set "$workspace_id" note='nightly build'
kibo volume labels set "$volume_id" team=infra
kibo volume annotations clear "$volume_id"
kibo egress labels set "$egress_id" team=infra
kibo resolver labels set "$resolver_id" team=infra

• 内容与当前相同时，修改成功且版本不变。
• 已删除的 Workspace 与 Volume 不接受修改，返回 failed_precondition。

版本复制标题链接

每次修改都带期望版本，与当前版本不符时返回 aborted，内容不变。

• labels 与 annotations 各有自己的版本，互不影响，也不影响资源的其他版本，例如 Workspace 的资源版本与绑定版本。
• 不传 --expected-revision 时，kibo 先读取当前版本再提交；提交时版本已变化则返回冲突，不自动重试。
• 脚本需要重放修改时，把 --command-id 与 --expected-revision 一起传入。

kibo 的输出复制标题链接

哪些列表命令接受 --wide 与 -L、-L 的列怎样命名，见命令自带的通用参数。

key 与 value复制标题链接

• 违反字符规则或上限时返回 invalid_argument，并指出字段与 key。
• kibotos.app 及其子域名形式的前缀留给 Kibotos 自己的组件使用，ctrl 不据此拒绝请求。例如 E2B 兼容网关使用 e2b.kibotos.app/。

用 API复制标题链接

• 翻页时，label_selector 必须与取得游标的那次请求相同。
• 能力名是 workspace.labels、workspace.annotations、volume.labels、volume.annotations。老版本的服务端会静默丢掉未知字段，写入前先确认能力名存在；缺少时 kibo 以退出码 14 失败，不会创建一个丢了字段的资源。
• Egress 与 Resolver 的 labels、annotations 没有单独的能力名，随资源本身的能力 workspace.network_policy.egress.socks5 与 workspace.network_policy.resolver 提供。

下一步复制标题链接

• 创建与列表：create 的其他参数与列表过滤。
• kibo 命令行：幂等键与怎样安全地重放命令。
• Egress 与 DNS 与 Resolver：其他带 labels 的资源。