跳到內容
多雲網路

軟體版本與重建

兩個 Terraform 變數設定 Customer Edge 的軟體：ce_os_version 用於作業系統，ce_sw_version 用於 F5 Distributed Cloud 版本組建。兩者的行為都與直覺相反——空白欄位會取得最新版本而非不安裝，且在某個節點上可成功安裝的版本，可能因磁碟較小而在另一個相同節點上失敗。

版本欄位的作用，分兩個階段

Section titled “版本欄位的作用，分兩個階段”

區分這兩個階段才是關鍵所在。若將兩者混淆，行為讀起來會自相矛盾。

在第一次開機時，節點會安裝 ce_sw_version 所指定的版本。 terraform/modules/ce-node 以 version = "latest" 部署 marketplace 映像檔，因此節點初始攜帶的版本組建，取決於該映像檔目前所附的內容——而這會隨時間變動。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 可以

Section titled “Terraform 無法變更版本，但 API 可以”

這是兩個獨立的事實，若混淆則會產生錯誤的計劃。

Terraform 無法變更。 ce_os_version 和 ce_sw_version 實際上僅在建立時有效。變更任一欄位並套用後，API 會以 [BAD_REQUEST] Invalid request parameters 拒絕更新。觀測於 2026-07-29，於一次性站台上測試，涵蓋三個方向——向前釘選至較新版本組建、向後釘選至較舊版本組建，以及透過清除兩個欄位取消釘選。向前並非特例。

API 可以變更。 F5 Distributed Cloud 為每個站台提供專用的升級動作，可就地啟動變更——無需重建，也不涉及 Terraform：

Terminal window
# 軟體版本組建
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——這是路由訊息，並非表示升級不存在——這個區別曾讓本專案得出錯誤結論。

若您選擇重建而非升級，則替換 CE 的所有後果均適用。

已釘選的版本組建可能安裝失敗，站台因此卡住

Section titled “已釘選的版本組建可能安裝失敗，站台因此卡住”

接受釘選與安裝釘選版本是兩回事。在一個全新建立的單節點 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 站台，全部使用相同的 marketplace 映像檔，可以隔離出問題所在。觀測於 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 可成功安裝。 因此預設值約短缺兩個 GB，差距並不大。

無論如何，在將版本變更套用至機群之前，請先在一次性站台上進行測試：以此方式失敗的機群會卡在 PROVISIONING 狀態，重建是唯一的出路。

本文件所描述的版本組建

Section titled “本文件所描述的版本組建”

本站點的命令參考描述的是 crt-20250613-3382，即此機群所運行的版本組建。僅存在於較新版本組建上的命令，已記錄於 sitecli/command-classification.json 的 not_on_this_build 欄位下，並另行記錄於較新版本組建上的命令，因此該處不會有任何內容顯示為在此版本可執行。另請參閱機上命令。