从 v0.2.x 升级到 v0.3.0

本页说明从 v0.2.x 升级到 v0.3.0 时，在通用的跨版本升级步骤之外要做的事。文中的「第 N 步」指跨版本升级的步骤表。

按跨版本升级的步骤停机替换。v0.3.0 增加了调用方自带的出口（Egress）与调用方自选的 DNS 上游（Resolver），guest 的 DNS 改为只发往链路上的一个地址，替换前后按下表处理：

项	要做什么	不处理的后果
ctrl 数据库	第 6 步按检查报告执行 `kibotos-ctrl migrate`	ctrl 拒绝启动
ctrl 的 `database.max_connections`	默认值从 `3 × execution_concurrency + 32` 改为固定的 32，下限从 `3 × execution_concurrency + 16` 改为 8，不再随并发变化。显式写了的继续生效，可以调低	无，只是占着用不上的连接
经过连接代理或连接池连接 PostgreSQL	现在受支持，条件是全部读写都发到主库，见数据库的连接方式。`kibotos-ctrl migrate` 仍要直连主库	经事务级连接池迁移，迁移工具的会话级锁可能留在别的会话上，下一次迁移一直等待
同时运行两个 ctrl	现在第二个只回答读取，写入返回可重试的 `unavailable`，见执行权。替换时仍先停旧的再启新的	无
连接池指标	`kibotos_ctrl_db_connections`、`kibotos_ctrl_db_max_connections`、`kibotos_ctrl_db_acquire_waits_total`、`kibotos_ctrl_db_acquire_seconds_total` 去掉了 `pool` 标签。按 `pool` 过滤或分组的查询与告警要改，重新导入 Grafana 看板	查询没有数据
调用方的命令 ID	看 `kibotos_ctrl_nonconforming_command_ids_total` 是否增长。增长时，ctrl 的 WARN 日志 `request carries a command ID that v0.4.0 refuses` 写明 `principal`、`procedure` 与 ID 的开头；让这些调用方改用符合规则的 ID	`v0.3.x` 照常工作，升级到 `v0.4.0` 后这些请求返回 `invalid_argument`
ctrl 的 `storage.root`	新版本的 ctrl 第一次启动时在这里生成 `credential-keys/`，它加密数据库里保存的 Egress 用户名与口令。启动之后把它和 `pki/` 一起加入备份，见初始化与启动	密钥丢失后，已保存的 Egress 凭证无法解密，只能由调用方用 `UpdateEgress` 重新写入口令
node 宿主机的内核	支持 nftables 的 `tproxy` 与 `socket` 表达式（内核模块 `nft_tproxy`、`nft_socket`），见前提条件	这台 node 不宣告出口能力，引用 Egress 的 Workspace 不会放到它上面
node 的系统账户与 slice	node 包创建系统账户 `kibotos-egress` 并带上 `kibotos-egress.slice`。自行管理账户的，保留这个账户；按单元名采集日志的，加上这个 slice 里的单元。见出口进程	出口进程启动不了，或收不到它的日志
第一个部署 DNS 服务器是 IPv6 地址的部署：Platform	第 8 步恢复写入之前，发布并 approve 本版本的 Platform，用 `kibo platform set-default` 把它设为在用的每个 PlatformKey 的默认 revision，见目录。Workspace 启动时换到默认 revision。第一个部署 DNS 服务器是 IPv4 地址的部署不需要这一步	升级后启动的 Workspace 的 nameserver 写作 `fe80::1%eth0`，`v0.3.0` 之前发布的 Platform 里的 guest 拒绝这种带接口标识的地址，Workspace 启动失败
E2B 网关写的 label 与 annotation	网关启动后自行把本部署已有 sandbox、Volume 与 Egress 的 key 从 `e2b.kibotos.io/`、`m.e2b.kibotos.io/` 改写为 `e2b.kibotos.app/`、`m.e2b.kibotos.app/`，日志 `gateway keys migrated` 记每类改写了多少个。按旧前缀筛选资源的运维脚本改用新前缀	脚本找不到已改写的资源。`v0.4.0` 起网关不再读旧前缀，届时仍带旧前缀的资源对网关不存在
node 本地的 Instance 记录	第 5 步报告为 `has version 8, this build reads [9 10]` 的记录是 `v0.1.x` 写下、`v0.2.x` 没有改写过的。运行中的 Instance，用当前版本正常停止一次；已结束的，停止 node 后把这个文件移到 `storage.root` 之外留档，这个 Workspace 的启动、停止与删除不受影响，清理状态里与这个 Instance 有关的几项显示为未知	`check-upgrade` 与 node 启动失败
集群指标的取值	`kibotos_cluster_node_status` 的 `status` 多了 `retired`，`kibotos_cluster_volumes` 的 `state` 多了 `lost`。按全部取值求和或枚举的告警，把它们算进去或排除掉	退役 node 或已丢失的 Volume 被算作异常
被撤销的 node	它们不再列为池成员，也不再算作别的 node 进入 `DRAINED` 时的另一台接入 node。升级前用 `kibo node list` 找出 `REVOKED` 的 node：共用池上只剩一台未撤销的 node 时，那台 drain 不到 `DRAINED`，要先搬走或删除池里的对象	drain 一直停在 `DRAINING`
集群指标	用到 `kibotos_cluster_node_allocatable_ephemeral_disk_bytes` 与 `kibotos_cluster_node_allocated_ephemeral_disk_bytes` 的查询与告警改用 `kibotos_cluster_storage_pool_capacity_bytes` 与 `kibotos_cluster_storage_pool_reserved_bytes`，重新导入 `grafana-cluster.json`，见Grafana	这两个序列不再更新，旧看板的临时盘面板为空
ctrl 的 `[metrics]`	E2B 部署把 `instance_info_labels` 写成 `["e2b.kibotos.app/namespace", "e2b.kibotos.io/namespace"]`，重新导入两个 Grafana 看板，见实例指标	缺新 key 时所有 sandbox 的指标都是空数组；旧看板按命名空间的面板为空

判断 E2B 网关的改写是否完成：网关启动几分钟后，kibo workspace list -l e2b.kibotos.io/namespace=<命名空间> 与 kibo volume list -l e2b.kibotos.io/namespace=<命名空间> 应当为空。仍有输出的，看网关日志：

gateway key migration incomplete：这一遍没改完，网关过一分钟左右再试。
gateway keys left in legacy spelling：ctrl 因 key 变长超出 labels 总长上限而拒绝改写。网关在 v0.3.x 照常读取它；升级到 v0.4.0 之前删除这个 sandbox 或 Volume。

改写还带来两处可见的差别：

升级前带 Idempotency-Key 发起、升级后才重试的创建 sandbox 请求，因请求生成的 label 不同而返回冲突。换一个 key 重新创建。
v0.3.0 之前写入的实例指标样本带的是 label_e2b_kibotos_io_namespace。网关查询 sandbox 指标时两个标签都认，Grafana 看板按命名空间的面板只显示新标签的样本。

新版本的 node 把 Instance 记录改写为第 10 版，v0.2.x 的 node 读不了。替换文件之前用第 5 步的检查处理完全部阻塞项。

v0.2.x 构建的 Platform 归档、Template 清单与构建结果用的格式标识在 kibotos.io/ 下，本版本照常读取，v0.4.0 起不再读取。

升级后 PUBLIC_INTERNET 的 Workspace 有一处行为不同：不以 SYN 开始的新 TCP 流会被重置。连接跟踪状态丢失的旧连接（例如宿主的连接跟踪表被清空之后）因此被重置，不再继续传输，guest 里的程序要重新建立连接。

guest 的 DNS 配置随 Workspace 的启动确定，升级时分两类：

Workspace	DNS 配置	能否引用 Resolver
升级前启动、升级后继续运行的	不变：`/etc/resolv.conf` 仍列出部署的 DNS 服务器，node 重启时按当前 node 配置同步	不能。`UpdateWorkspaceNetworkPolicy` 返回 `failed_precondition`，期望与生效的策略都不变
升级后启动或重启的	`/etc/resolv.conf` 只有链路 DNS 地址：第一个部署 DNS 服务器所在地址族的 guest 网关地址，IPv6 是 `fe80::1%eth0`，要求本版本的 Platform（见上表）	能

要引用 Resolver 的 Workspace，在升级后停止再启动一次。
换到链路 DNS 地址后，不引用 Resolver 的 Workspace 只使用与链路地址同族的第一个部署 DNS 服务器，其余的不再使用；第一个的地址族决定链路地址的地址族。配置了多个部署 DNS 服务器、依赖其余几个做备用的，把最可靠的写在第一个。
DENY_ALL 的 Workspace 的 DNS 查询立即失败，guest 直接发往部署 DNS 服务器的 UDP 被拒绝。
部署方在宿主上限制 node 自身出站的，直出的 Resolver 上游也一并受限。