软件版本与重建

两个 Terraform 变量用于设置 Customer Edge 的软件：ce_os_version 用于操作系统，ce_sw_version 用于 F5 Distributed Cloud 构建版本。两者的行为与直观理解恰好相反——留空字段会获取最新构建而非不安装任何内容，而在一个节点上能成功安装的版本，可能因磁盘较小而在另一个完全相同的节点上失败。

版本字段的作用，分两个阶段

区分两个阶段是理解全部内容的关键。若将两者混为一谈，其行为看起来会自相矛盾。

在首次启动时，节点会安装 ce_sw_version 所指定的版本。 terraform/modules/ce-node 使用 version = "latest" 部署市场镜像，因此节点到达时携带的构建版本取决于该镜像当时的内容——而这会随时间变化。ce_sw_version 决定的是目标版本，而非是否执行任何操作；留空意味着由服务端决定，而非节点保持原状。ce_os_version 同理。

不要假设变更方向是向上的。观测于 2026-07-28，镜像携带的构建版本为 20260703-e2c462a——比该机群的 crt-20250613-3382 更新，也比租户所通告的 crt-20260201-0179 更新。指定一个比镜像携带版本更旧的构建，意味着要求节点向后回退，这是常见操作：该机群正是以此方式创建并正常运行的。

将版本字段留空是风险最高的选择，而非中立选择。 创建时，服务端不会忽略空字段——它会将其填充为最新通告版本并进行安装。一个在两个字段均未设置的情况下创建的站点，最终被固定到 crt-20260201-0179 和 OS 9.2026.14（即租户当时通告的两个版本），随后安装失败。观测于 2026-07-29。

这带来两个后果：留空意味着”给我最新版本”，因此未固定版本的部署最可能触及下文所述的磁盘限制。此外，你无法通过留空其中一个字段来单独隔离它，因为服务端会将其填充——请有意识地同时设置两个字段，或接受各自的最新版本。

首次启动后，不会自动升级任何内容。 F5 Distributed Cloud 通告较新的构建后会等待。“节点保持在其落地版本”这一说法适用于创建之后，而非创建过程中。

两个阶段在站点对象上均可见。观测于 2026-07-28，该机群：

volterra_software_status.available_version   crt-20260201-0179
operating_system_status.available_version    9.2026.14

而节点运行的是 crt-20250613-3382 和 OS 9.2024.6。更新的构建已提供但未被采用——这是稳定状态，而非停滞的升级。

Terraform 无法更改版本，但 API 可以

这是两个独立的事实，将其混淆会导致错误的计划。

Terraform 无法更改。 ce_os_version 和 ce_sw_version 实际上仅在创建时有效。更改其中任何一个并执行 apply，API 将以 [BAD_REQUEST] Invalid request parameters 拒绝更新。观测于 2026-07-29，在临时站点上测试了全部三个方向——向前固定到更新的构建、向后固定到更旧的构建，以及通过清空两个字段来取消固定。向前固定并非特殊情况。

API 可以更改。 F5 Distributed Cloud 为每个站点提供专用的升级操作，可就地启动变更——无需重建，也无需 Terraform 参与：

# 软件构建
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<software-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_sw"

# 操作系统
curl -X POST -H "Authorization: APIToken $TOKEN" -H 'Content-Type: application/json' \
  --data '{"version": "<os-version>"}' \
  "$API_URL/api/config/namespaces/system/sites/<site-name>/upgrade_os"

观测于 2026-07-29：软件调用返回 200，站点进入 UPGRADING 状态，deployment_state.phase 为 UPGRADE_IN_PROGRESS，站点对象的请求版本更改为所提交的版本。省略字段会返回 400，错误信息为 version empty in the request，字段名称由此得到确认。

预留数小时而非数分钟，并且不要在出现失败时慌乱。 在默认磁盘节点上，升级到 crt-20260201-0179 运行了约一小时，中途报告 UPGRADE_FAILED，result 为 Failed，然后成功完成并运行在新构建版本上。平台会自动重试。

这对监控升级或编写升级脚本的人有直接影响：Failed 结果是需要等待的状态，而非最终判决。将第一次失败视为最终结论，会把一次即将成功的升级报告为失败。

注意路径中的分组：这些接口位于 config 下，而非 operate。operate 下的相同路径返回 404 API Group could not be determined，这是路由消息，并非表示不存在升级操作——这一区别曾让本项目得出错误结论。

通过 API 升级会使 Terraform 配置与实际状态不同步

固定变量仍保持原来的值，因此实时站点现在运行的是配置中未指定的版本。Terraform 不会对其进行协调——因为更新会被拒绝——因此请将 API 升级视为有意脱离 Terraform 控制的操作，并在下次重建时将固定版本更新为匹配值。

本页面此前的两个说法，现已撤回

本页面此前声称将 CE 迁移到不同版本意味着需要重建站点，以及被拒绝的更新”仍会在服务端清除该字段”，导致 Terraform 持续提出失败的变更。这两点均未能通过测试验证：上述 API 升级可就地启动版本变更，无需重建任何内容；而在三次被拒绝的更新后，站点的 spec 均未改变，站点保持 ONLINE。provider issue xcsh#1387 中描述的差异是在站点已自动升级超过其固定版本后观测到的，因此可能需要该差异起始状态；在 spec 与固定版本匹配的站点上未能复现。

如果选择重建而非升级，替换 CE 的所有后果均会适用。

替换 CE 的所有后果均会适用

新的 SSH 主机密钥、重新分配的内部地址、全新注册，以及仅存在于节点上的所有内容的丢失。Cloud-init 会在新虚拟机上重新运行，因此通过该方式配置的 SSH 访问得以保留——但它仅在首次启动时运行，因此手动添加到旧节点的任何内容都将丢失。

在安排此操作之前，请阅读 SSH 以了解主机密钥和地址方面的后果。

固定的构建版本可能安装失败，站点随即卡死

接受固定版本与成功安装并不等同。在一个新创建的单节点 Azure Secure Mesh v2 Customer Edge 上，固定到 crt-20260201-0179 后，站点对象立即报告了固定版本——随后安装失败：

site_state        PROVISIONING
phase             UPGRADE_FAILED
result            Failed
last_installed    (empty)
message           stage: 10, app: voucher obj: voucher objKind: DaemonSet failed ...
                  required replicas: 1, current replicas: 0

观测于 2026-07-28，并于 2026-07-29 复现两次。操作系统固定版本在同一次运行中正常安装（9.2024.6 升级到 9.2026.14，状态为 UPGRADE_COMPLETED）；仅软件安装失败。站点始终未到达 ONLINE，last_installed_version 保持为空，因此没有任何内容回滚到可用构建——没有可供回滚的早期成功安装。

创建时的失败与升级过程中的失败不同。 两者行为不同，这在你决定是否介入时至关重要：

	创建时	API 升级过程中
是否会重试至成功？	否——连续两次保持 Failed 超过 20 分钟	是——已恢复并完成
节点最终处于何种状态？	PROVISIONING，未安装任何内容	ONLINE，运行可用构建
是否可以放任不管？	否，已卡死	是，会自行恢复或保留旧构建

因此，创建时的失败需要使用更大磁盘重建，而升级时报告 Failed 则应等待一段时间再下结论。

原因是磁盘，而非版本。 通过一个软件 × OS × 磁盘大小的矩阵测试，每种组合各创建一个临时的单节点 Azure Secure Mesh v2 站点，均使用相同的市场镜像，可以将问题隔离出来。观测于 2026-07-29：

软件	OS 9.2024.6（镜像自带版本）	OS 9.2026.14
crt-20250613-3382	安装成功	安装成功
crt-20260201-0179	安装成功	失败，仅在默认磁盘上

两个版本单独均不会失败。只有组合在一起，且仅在镜像默认磁盘上才会失败——同样的组合在 33 GB 及所有测试的更大规格上均能成功安装。因此，更新的构建在此并非不受支持，更新的操作系统也不是；两者合在一起所需的磁盘空间略超过默认节点的容量。

terraform/modules/ce-node 未设置 disk_size_gb，因此每个 Customer Edge 都使用镜像默认值——而这恰好是该组合会失败的唯一规格。若要运行该版本组合，请扩大磁盘。

差距出人意料地小，这也是为何这个问题长期被误认为版本问题。默认值为 31 GiB（health 命令报告 size_gb: 31，在失败状态节点上 /var 为 29 G，剩余 3.5 G）。33 GB 可以正常安装。 因此默认值的不足约为两个千兆字节，差距并不大。

不要将测量到的最小值作为目标

33 GB 是观测到的最小可用规格——针对该版本组合、该镜像、以及当前时间。若某个构建的负载稍大，在无任何配置变更、也无明显原因的情况下，33 GB 仍可能失败，与当前默认值的情况完全相同。请选择有余量的规格而非最低值：此处已验证的规格为 33、36、40、48 和 64 GB，使用较大规格所增加的成本仅为若干千兆字节的托管磁盘费用。

无论如何，在将版本变更应用到整个机群之前，请先在临时站点上进行测试：以此方式失败的机群会卡在 PROVISIONING，重建是唯一的出路。

不要根据 F5 的升级前数据来确定磁盘大小

F5 文档中的升级前检查要求至少有 20 GB 加 15% 容量的可用空间。该检查针对的是控制台 UI 升级，并明确说明不适用于 API 发起的升级，因此无法描述本次失败。按该公式推算，48 GB 磁盘将会失败；而实际上 48 GB 安装成功。请根据上述实测结果确定大小，而非该公式。

本页面此前提供的一种解释，现已撤回

本页面早期版本曾提出，安装失败是因为请求的构建版本比镜像携带的版本更旧——即节点被要求向后回退。这是错误的。该机群使用同一镜像创建，固定版本比镜像旧十三个月，安装正常；而当 OS 固定版本保持在镜像自带版本时，crt-20260201-0179 也能正常安装。版本变更方向不是决定因素。

本文档所描述的构建版本

本站点的命令参考描述的是 crt-20250613-3382，即该机群所运行的构建版本。仅存在于较新构建上的命令记录在 sitecli/command-classification.json 的 not_on_this_build 下，并单独记录在较新构建上的命令中，因此该文档中的内容不应被视为在当前版本可用。另请参阅节点上的命令。

升级到较新构建的方式已明确，且无需重建

此前本文记录为悬而未决的问题，并报告了较新构建在单节点 Azure Secure Mesh v2 站点上失败的情况，同时有一个反例显示其正常运行。现在两者均已得到解释：较新构建可在该拓扑上安装，而失败的原因是上述磁盘限制，而非构建本身。

因此，有两种方案可选，且两者本身都不需要重建——创建一个磁盘足够大的节点，或通过 API 升级现有节点。观测于 2026-07-29。