身份与注册

本页介绍如何安装 kibo、用注册密钥（enrollment key）建立与 ctrl 的连接，以及如何为其他 Operator 和 node 签发或撤销注册密钥。

• 身份、证书与配置的完整规则见身份、配置与连接。
• 注册之后的集群管理见node、存储池、目录与 artifact 回收。
• Workspace 的日常操作见kibo 命令行，全局参数与退出码见 kibo CLI 参考。

概述复制标题链接

kibo 是 Kibotos 的命令行工具，通过 ctrl 的 API 完成 Workspace 操作、Template 发布和节点管理。它只经 ctrl 的 API 工作，不要求工作机与部署同一个系统：

macOS 的两个构建与 Linux 的出自同一次发布构建，功能相同；目前只核对了构建身份，没有在 macOS 上做过运行验收。

kibo 用 Operator 身份访问 ctrl。身份保存在本机的一个目录里，称为 context。建立 context 的过程叫注册：拿到一把一次性的注册密钥，交给 kibo context enroll，它向 ctrl 换取正式的客户端证书并保存下来。

kibo 从发布包安装，本文的示例直接调用它。

安装 Operator 并注册 node复制标题链接

这是首次部署时在 Operator 工作机上的完整步骤。

前提条件：ctrl 宿主机的管理员已经用 kibotos-ctrl enrollment create 签发了第一把 Operator 注册密钥，并通过安全渠道交给你。见安装与初始化 ctrl。

sudo install -m 0755 kibo_VERSION_linux_amd64 /usr/local/bin/kibo
umask 077
kibo context enroll --endpoint https://ctrl.kibotos.example:18092 --key-file operator-enrollment.key
rm operator-enrollment.key
kibo context show
kibo enrollment create --node node-a --data-plane-extra-host node-a.example.com --output node-enrollment.key --json

• kibo 取自已校验的发布包目录；macOS 工作机换成对应架构的那个文件，同样装成 /usr/local/bin/kibo。
• 最后一步生成 node 的注册密钥。把它安全地传到 node 宿主机，由 kibotos-node join 使用，然后删除两边的密钥文件。node 侧的步骤见安装 node。
• context 目录只保存在 Operator 工作机上。Template 构建机使用独立账户，不共用这个目录。
• 不要把这个目录复制给网关或其他程序。它们各自需要一份身份，用 kibo enrollment create --operator 另外签发。

连接配置（context）复制标题链接

kibo 的远程命令都经过 ctrl 的 mTLS 端口，用 context 中的 Operator 身份认证。没有默认的服务器地址，必须先注册。

kibo context enroll --endpoint https://ctrl.example.com:18092  # 无回显提示输入密钥
kibo context show                                             # 查看本地 context，不联系 ctrl
kibo version                                                 # 查询当前 ctrl

服务器地址复制标题链接

• --endpoint 必须是 HTTPS。主机部分是小写的完整域名或 IP，并且要与 ctrl 配置中的 [identity].host 一致。
• enroll 从密钥中取出 ctrl 的服务端 CA，验证 ctrl 后把地址、身份和 CA 一起保存。

密钥、代理与 context 目录复制标题链接

enroll 的全部参数见 kibo context enroll。

• 不给密钥参数时，enroll 无回显地提示输入密钥。在脚本里用 --key-file、--key-stdin 或 --key-fd 提供。各种来源的读取方式见注册密钥的规则。
• 需要经正向代理时，在 enroll 命令上加 --proxy，例如 --proxy http://proxy.example:3128。代理设置保存在 context 中。接受的代理类型与代理环境变量见正向代理。
• enroll 把 context 写到默认目录，或 KIBO_CONTEXT_DIR 指定的绝对路径。目录已存在时 enroll 拒绝覆盖；需要重新注册时先删除旧目录。见 context 目录。
• 注册成功后删除密钥文件。

有效期与续期复制标题链接

正式身份有效期 30 天。kibo 在它过期前自动续期，kibo context renew 可以手动续期。身份已过期时无法续期，需要用新的注册密钥重新注册。见有效期。

排查复制标题链接

两种情况重试都不会成功，需要先修正 context 或身份状态。

签发与撤销注册密钥复制标题链接

已注册的 Operator 可以用 kibo enrollment 为其他 Operator 或 node 签发注册密钥，也可以撤销他们的身份。示例中的 ID 请替换为实际值：

kibo enrollment create --node node-a --ttl 1h --data-plane-extra-host 127.0.0.1 --output node-a.key
kibo enrollment create --operator teammate --ttl 1h --output teammate.key
kibo --json enrollment create --node node-b --output node-b.key
kibo enrollment revoke --node node-a --yes
kibo enrollment revoke --operator teammate --yes

create复制标题链接

全部参数见 kibo enrollment create。参数遵循下面的规则：

• --operator 与 --node 二选一。node ID 必须是小写的域名形式，见身份规则。
• 密钥只写入 --output 指定的文件，权限 0600。文件必须不存在；不接受 - 或符号链接。
• --data-plane-extra-host 给 node 的数据面证书追加一个名称。node 对外公布的数据面地址必须是证书中的名称之一。名称如何合并见node 的数据面证书。
• 命令输出（包括 --json）只包含摘要：grant ID、主体、有效期和 output_file。ctrl 不保存完整密钥。

幂等重放复制标题链接

• 带 --command-id 重复执行同一个 create 时，ctrl 返回原来的 grant 但不再返回密钥。kibo 以非零退出，不写输出文件。
• 相同的幂等键配不同的主体、类型或额外主机名，返回 already_exists。
• 写输出文件失败后，先检查 grant 和文件的状态，不要直接重复 create。

revoke复制标题链接

• 撤销是不可逆的，必须加 --yes。它让该主体的正式身份和所有未使用的注册密钥立即失效。影响范围见撤销。
• 需要让它回来时，重新签发一把密钥，再执行 kibotos-node join 或 kibo context enroll。
• 只是想让 node 暂停接收新的 Workspace，用 kibo node drain，不要撤销。

第一位 Operator复制标题链接

集群里还没有任何 Operator 时，由 ctrl 宿主机的管理员用本机命令签发：

sudo -u kibotos-ctrl kibotos-ctrl enrollment create \
  --config /etc/kibotos/ctrl/config.toml --operator operator-b \
  --output /var/lib/kibotos/ctrl/operator-b-enrollment.key

所有 Operator 的身份都丢失时，也用这条命令恢复。