Kibotos

API 概览

Kibotos 的 API 让你自己的程序不经过 kibo 创建和使用 Workspace、运维整套部署。本页介绍各个包、两个入口及其协议，给出第一个请求，并列出讲解每个服务的页面。

概述

API 是一组 protobuf 服务，任何有 Connect、gRPC 或 gRPC-Web 客户端的语言都能调用。程序需要完整能力或兼容承诺时，用 API 而不用 kibo：kibo 的参数与输出不在兼容承诺之内。

你在写的是用什么
手工操作、shell 脚本、排查kibo 命令行
需要完整能力与兼容承诺的程序，任何语言API，按本组页面调用
Go 程序Go SDK，生成代码在其中，证书与数据面凭证由它处理
已经按 E2B SDK 写好的程序E2B 兼容

本组页面包括：

  • 认证：获得 Operator 身份，以及两个入口的 TLS 设置。
  • 写操作与错误：能力、幂等键、版本校验与错误格式。
  • 数据面：会话凭证，以及调用运行 Workspace 的 node。

Workspace、执行代、Volume 等概念与状态见核心概念，数据在什么情况下保留见保证与边界。

第一个请求

下面用 curl 和现有的 kibo context 身份查询服务端的能力，同时验证证书和地址是否正确：

ctx="${KIBO_CONTEXT_DIR:-$HOME/.config/kibo/context}"
cert=$(ls "$ctx"/identity-*.pem)
curl --http2 --tlsv1.3 \
  --cert "$cert" --key "${cert%.pem}.key" --cacert "$ctx/server-ca.pem" \
  -H 'Content-Type: application/json' --data '{}' \
  https://ctrl.example.com:18092/kibotos.ctrl.v1.ServerInfoService/GetServerInfo

响应里是服务端构建所用的源码版本和它的能力名列表。你自己的程序使用自己的身份，见认证。Go 程序用 Go SDK 从身份建立这个客户端。

包与入口

proto 包

接口定义在 Kibotos 仓库的 proto/ 下：

proto 包文件内容
kibotos.ctrl.v1ctrl.protoWorkspace API，以及运行在 node 上的文件、进程、桌面与服务连接接口
kibotos.operator.v1operator.protoOperator API：发布、批准、节点管理、注册密钥
kibotos.enrollment.v1enrollment.proto用注册密钥换取身份、续期
kibotos.service.v1service.proto服务连接的目标与消息类型

这些包的每个服务、方法、消息与枚举见由 proto 文件及其注释生成的 API 参考。

前三个包，以及数据面用到的 kibotos.service.v1 类型，承担兼容承诺，见兼容承诺。

两个入口

Workspace 的文件、进程、桌面与服务连接直接访问运行它的 node，其余一律访问 ctrl：

                 mTLS（Operator 身份）                     Bearer（会话凭证）
第三方程序 ───────────────────────────► ctrl              ───────────────────────► node 数据面
           Workspace API / Operator API / 注册            文件 / 进程 / 桌面 / 服务连接 / /v1/files
入口地址认证方式详见
ctrl（控制面）ctrl 配置中的 [api].listen，如 https://ctrl.example.com:18092mTLS，客户端证书是注册得到的 Operator 身份认证
node（数据面）CreateDataPlaneSession 响应中的 session.endpointHTTP 头 Authorization: Bearer <credential>数据面

协议

两个入口都使用 Connect 协议，HTTP/2 over TLS 1.3。

  • 请求格式：POST https://<host>/<package>.<Service>/<Method>。
  • 一元调用的 Content-Type 可以是 application/proto 或 application/json；流式调用使用 application/connect+proto 或 application/connect+json。
  • 服务端由 connect-go 实现，同时接受 gRPC 与 gRPC-Web。本组页面的示例使用 Connect 协议。
  • 不需要额外的请求头。没有 API 版本头，也没有 User-Agent 要求。客户端与服务端的兼容性通过能力列表判断，见写操作与错误。
  • ctrl 限制每条请求消息的大小，按所用编码、解压后计算：ArtifactPublicationService 16 MiB，EnrollmentService 64 KiB，其他服务 4 MiB。超出时返回 resource_exhausted。这些上限高于各服务能接受的最大请求。
  • node 数据面的流式方法需要 HTTP/2。服务连接（ServiceConnectionService.Connect）的单条消息不超过 32 KiB。

服务一览

每个服务名链到它生成的参考页，那里列出方法、消息与枚举。服务做什么、前提条件与结果写在主题页里。Workspace 相关的主题页先讲 kibo 的用法，API 的细节在其后的「用 API」一节。

Workspace API（kibotos.ctrl.v1）

这些服务运行在 ctrl 上。

服务用途详见
ServerInfoService源码版本与能力列表写操作与错误、能力名
TemplateService只读 Template 目录查看 Template
WorkspaceServiceWorkspace 生命周期与配置创建与列表、生命周期、资源与运行状况、到期时间、网络策略、labels 与 annotations
VolumeServiceVolumeVolume 与导出恢复
TransferService导出与恢复导出、导入与恢复
WorkspaceObservationService删除后的清理结果查看释放情况
WorkspaceMetricsService一段时间的宿主侧与 guest 内资源读数读取资源读数
DataPlaneSessionService获取数据面会话凭证数据面
ExposureService把 Workspace 内的端口发布为公开 HTTP 预览公开 URL
EgressService调用方自带的 SOCKS5 出口Egress
ResolverService调用方自选的 DNS 上游Resolver

数据面服务

这些服务定义在 ctrl.proto 中，但运行在 node 的数据面上，不在 ctrl 上。用会话凭证在会话的入口地址调用它们；这个地址还提供两个 HTTP 入口。

服务或入口用途详见
FilesystemService目录与元数据操作，监视目录文件
/v1/files传输单个文件的内容文件
ProcessService命令与终端命令与终端
DesktopService桌面画面与输入桌面
ServiceConnectionService连到 guest 里端口或 socket 的字节流服务与端口
/v1/service经 WebSocket 建立同样的连接服务与端口

Operator API（kibotos.operator.v1）

这些服务运行在 ctrl 上。

服务用途详见
ArtifactPublicationService发布 Template 与 Platform在构建机上构建并发布
TemplateLifecycleService在指定 node 上预热 Templatekibo template prepare
TemplateCatalogServiceTemplate 的批准与默认版本template 准入
PlatformCatalogServicePlatform 的批准与默认版本目录
NodeRegistrationService节点状态、drain、隔离、退役、存储池与池里的对象、宣告池丢失、对象在池之间搬迁、Workspace 位置、在指定 node 上创建与启动，以及超卖倍数node、存储池
ArtifactRetentionService回收不再使用的制品，以及保留指定的 Launchartifact 回收
EnrollmentGrantService签发与撤销注册密钥签发与撤销注册密钥

注册（kibotos.enrollment.v1）

服务用途详见
EnrollmentService用注册密钥换取身份，以及续期。在 ctrl 入口上提供认证

下一步

  • 认证：为你的程序获得身份。
  • 写操作与错误：每个写操作都遵循的规则。
  • 数据面：访问 Workspace 的文件、进程与服务。
  • conformance/ 下的验收套件只通过这些公开接口访问已部署的环境，可以作为调用方式的参考实现。

kibo 命令行

用 kibo 命令行可以创建 Workspace、在里面工作，并把这些操作写进脚本。本页介绍最常用的命令、kibo 怎样等待结果，以及怎样安全地重复一条命令。每条命令的全部参数见 kibo 命令。

认证

访问 ctrl 的请求经 mTLS 用 Operator 身份认证，访问 node 数据面的请求带一张短期的会话凭证。本页介绍程序怎样获得 Operator 身份、两个入口的 TLS 怎样配置，以及怎样持续续期。

本页内容

概述第一个请求包与入口proto 包两个入口协议服务一览Workspace API（kibotos.ctrl.v1）数据面服务Operator API（kibotos.operator.v1）注册（kibotos.enrollment.v1）下一步