本文說明如何將 Spanner Omni 部署作業從舊版升級至新版。
Spanner Omni 採用非同步、分階段推出的狀態機器,確保升級作業安全無虞,不會中斷服務。分階段升級可讓您執行下列操作:
- 套用資料庫結構定義更新。
- 在滾動重新啟動期間驗證二進位檔相容性。
- 如果在完成前偵測到錯誤,請復原至先前版本。
支援的升級路徑
LTS 版本只能更新至下一個 LTS 版本。更新至較新的 LTS 版本時,無法略過任何版本。
如果兩個短期支援 (STS) 版本的發布日期之間沒有 LTS 版本,則從一個 STS 版本升級至另一個 STS 版本時,可以略過一個版本。
詳情請參閱「版本支援政策」。
升級工作流程
Spanner Omni 升級程序包含多個依序執行的階段:
- 結構定義階段:使用目標二進位檔版本執行內部資料庫結構定義遷移作業,為部署作業做好準備。結構定義遷移作業無法復原,但與先前的二進位檔版本回溯相容。
- 二進位檔階段:使用滾動式重新啟動,更新部署作業中所有伺服器的伺服器二進位檔或容器映像檔。如果偵測到錯誤,您可以在最終處理開始前的任何時間點,將二進位檔或容器映像檔復原至先前的版本。
- 啟用功能階段:啟用與版本相容的功能,並在所有伺服器上完成二進位檔升級後開始。如果升級不包含版本相容功能,則可能不適用這個階段;如果功能相互依賴,則可能需要多輪測試。對於支援復原的選用階段,您可以使用 Spanner Omni CLI 啟動復原。
- 完成階段:完成推出作業,並封存目標版本。進入完成階段後,就無法復原。
事前準備
升級 Spanner Omni 部署作業前,請確認符合下列必要條件:
- 您有執行中的 Spanner Omni 部署作業。詳情請參閱「在 Kubernetes 上建立部署作業」或「在 VM 上建立部署作業」。
- 下載並安裝 Spanner Omni CLI。
- 您可從執行 CLI 指令的機器,透過網路存取所有 Spanner Omni 內部通訊埠 (TCP 15000 至 15027),或透過網路存取部署端點。
- 如果部署作業使用傳輸層安全標準 (TLS) 或雙向 TLS (mTLS) 加密,請確認
BASE_DIR/tls下方的基本目錄中,或叢集內掛接的目錄中,有有效的憑證。 - 您已找出目標版本:
- 如果是 VM 部署作業:請下載目標版本套件
spanner-omni-server-TARGET_VERSION.tar.gz。 - 如果是 Helm 和 Kubernetes 部署作業:請在 Artifact Registry 中找出目標容器映像檔,例如
us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION。
- 如果是 VM 部署作業:請下載目標版本套件
- Spanner Omni 部署作業的管理員應安排維護期間,以便進行升級。貴組織應避免在升級維護期間進行部署。
步驟 1:準備升級結構定義
如要啟動升級,請準備推出目標版本。在這個階段,Spanner Omni 會執行內部資料庫結構定義遷移作業,而現有伺服器會繼續處理流量。
選取部署環境的分頁標籤:
VM
在 VM 部署作業中,下載並解壓縮目標版本套件,然後使用解壓縮的 Spanner Omni CLI 啟動推出準備作業。
登入部署作業中的伺服器,該伺服器必須能透過網路存取所有 Spanner Omni 內部通訊埠 (TCP 15000 至 15027)。
下載並解壓縮目標版本套件:
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR更改下列內容:
TARGET_VERSION:要升級至的目標版本,例如2026.r5。EXTRACT_DIR:解壓縮版本套件的目錄,例如/tmp/target_spanner/。
從擷取的 CLI 執行
rollouts prepare指令,開始準備推出作業:EXTRACT_DIR/bin/spanner deployment rollouts prepare \ --target-server-binary=EXTRACT_DIR/bin/spanner_server \ --root-server=ROOT_SERVERS \ --base-dir=BASE_DIR更改下列內容:
EXTRACT_DIR:包含目標bin/spannerCLI 和bin/spanner_server二進位檔的擷取目錄。ROOT_SERVERS:一個根伺服器端點,或以半形逗號分隔的多個根伺服器清單,例如localhost:15000或server1:15000,server2:15000,server3:15000。BASE_DIR:Spanner Omni 的基本目錄,例如/spanner。- 如果部署作業使用 TLS 或 mTLS 加密,請附加
--ca-certificate-file=CA_CERT_FILE和--client-certificate-directory=CERT_DIR,指向有效憑證。
Helm
在 Helm 部署作業中,結構定義準備作業取決於您執行的是多伺服器或單一伺服器部署作業:
多伺服器部署 (高可用性/正式環境):Helm 會自動處理結構定義準備作業。在步驟 3:更新二進位檔或容器映像檔中執行
helm upgrade時,Helm 圖表會觸發spanner-prepare-for-upgrade預先升級掛鉤工作,在更新任何 StatefulSet 之前執行結構定義遷移。直接前往步驟 2:確認推出作業的狀態為「有效」。單一伺服器部署作業 (
deployment.singleServer=true):由於單一伺服器模式會將內部服務嚴格繫結至回送介面 (127.0.0.1),因此網路工作無法連線至這些服務。使用含有目標容器映像檔的臨時偵錯容器,在執行中的 Pod 內執行結構定義遷移作業:kubectl debug pod/POD_NAME -n NAMESPACE \ --image=us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION \ --container=upgrade-prepare -i \ -- /google/spanner/bin/spanner_server prepare_for_upgrade --root_server=127.0.0.1更改下列內容:
POD_NAME:伺服器 Pod 的名稱,例如spanner-a-0。NAMESPACE:部署作業的 Kubernetes 命名空間,例如spanner-ns。TARGET_VERSION:要升級的目標版本,例如2026.r5。
獨立 Kubernetes
如果您在 Kubernetes 上部署 Spanner Omni 時未使用 Helm,請執行獨立 Kubernetes 批次工作,使用目標映像檔對使用中的根伺服器執行結構定義遷移作業。
建立名為
spanner-prepare-upgrade.yaml的檔案,並加入下列工作資訊清單:apiVersion: batch/v1 kind: Job metadata: namespace: NAMESPACE name: spanner-prepare-for-upgrade spec: # Fail fast on the first error to stop the rollout immediately. backoffLimit: 0 template: metadata: namespace: NAMESPACE spec: restartPolicy: Never containers: - name: spanner-upgrade image: us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION command: ["/google/spanner/bin/spanner_server"] args: - "prepare_for_upgrade" - "--root_server=ROOT_SERVER_ENDPOINT" volumeMounts: - name: tls-certs mountPath: "/spanner/tls" readOnly: true - name: spanner-data mountPath: /spanner volumes: - name: tls-certs secret: secretName: tls-certs optional: true defaultMode: 256 - name: spanner-data emptyDir: {}更改下列內容:
NAMESPACE:部署作業的 Kubernetes 命名空間,例如spanner-ns。TARGET_VERSION:要升級的目標版本,例如2026.r5。ROOT_SERVER_ENDPOINT:使用中根伺服器 Pod 的端點,例如spanner-a-0.pod.spanner-ns。
套用資訊清單,執行準備工作:
kubectl apply -f spanner-prepare-upgrade.yaml
步驟 2:確認推出作業的有效狀態
準備步驟完成後,請確認推出作業已建立,並檢查階段狀態。
列出有效的推出作業,擷取推出作業 ID:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINT將
DEPLOYMENT_ENDPOINT替換為部署作業中的伺服器端點,例如localhost:15000或spanner-a-0.pod.spanner-ns:15000。輸出結果會與下列內容相似:
NAME STATE TARGET_VERSION START_TIME END_TIME rollouts/1788942172101727 IN_PROGRESS 2026.r3-beta 2026-09-09T08:22:52.101727Z -檢查詳細的推出階段狀態:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINT更改下列內容:
ROLLOUT_ID:推出作業的數字 ID,例如1788942172101727。DEPLOYMENT_ENDPOINT:部署作業中伺服器的端點。
輸出結果會與下列內容相似:
name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: IN_PROGRESS - name: rollouts/1788942172101727/phases/finalize state: PENDING sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: IN_PROGRESS targetVersion: 2026.r3-beta請先確認下列階段狀態,再繼續操作:
schema:顯示SUCCEEDED,表示內部資料庫結構定義遷移作業已完成。binary:顯示IN_PROGRESS,表示推出引擎已準備好進行二進位檔更新。finalize:顯示PENDING,等待二進位階段完成。
步驟 3:更新二進位檔或容器映像檔
結構定義階段成功後,請將部署作業中所有節點上執行的伺服器二進位檔或容器映像檔更新至目標版本。
選取部署環境的分頁標籤:
VM
在 VM 部署作業中,使用滾動式重新啟動,更新所有 VM 的 spanner_server 二進位檔:
- 一次更新一個故障域或可用區:在多可用區部署中,先更新一個可用區中的伺服器並確認穩定性,再更新下一個可用區。這可確保 Paxos 共識群組保留仲裁。
- 逐步重新啟動:同時重新啟動的伺服器不超過 5%,以維持持續查詢可用性。
- 確認伺服器健康狀態:確認所有重新啟動的伺服器都健康,且已重新加入叢集,再更新下一個故障域。
Helm
在 Helm 部署作業中,執行 helm upgrade,同時保留現有設定值,方法是傳遞 --reuse-values 或提供值檔案:
多伺服器部署 (正式環境/高可用性):
helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \ --version CHART_VERSION \ -n NAMESPACE \ --reuse-values \ --set image.tag=TARGET_VERSION \ --timeout 30mHelm 會使用升級前掛鉤自動執行第 1 階段,然後啟動 StatefulSet (
rollout.staggered: true) 的逐可用區滾動式更新。單一伺服器部署作業 (
deployment.singleServer=true):明確傳遞
--set skipPrepareUpgrade=true,讓 Helm 略過升級前掛鉤工作,因為您已在本機完成階段 1:helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \ --version CHART_VERSION \ -n NAMESPACE \ --reuse-values \ --set skipPrepareUpgrade=true \ --set image.tag=TARGET_VERSION \ --timeout 30m
更改下列內容:
CHART_VERSION:目標 Helm 圖表版本,例如1.1.0。NAMESPACE:部署作業的 Kubernetes 命名空間,例如spanner-ns。TARGET_VERSION:目標容器映像檔標記,例如2026.r5。
獨立 Kubernetes
在不使用 Helm 的自訂 Kubernetes Deployment 中,將 StatefulSet 或 Deployment 規格中的容器映像檔更新為 TARGET_VERSION。
在故障域中執行滾動式更新,一次更新一個可用區,且同時重新啟動的 Pod 不超過 5%,以維持仲裁。
步驟 4:驗證二進位檔階段進度
將所有伺服器或 Pod 更新至目標版本後,請確認二進位檔階段已順利完成。
查看推出階段狀態:
spanner deployment rollouts describe ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
更改下列內容:
ROLLOUT_ID:推出作業的數字 ID,例如1788942172101727。DEPLOYMENT_ENDPOINT:部署作業中伺服器的端點。
輸出結果會與下列內容相似:
name: rollouts/1788942172101727
phases:
- name: rollouts/1788942172101727/phases/schema
startTime: "2026-09-09T08:22:52.101727Z"
state: SUCCEEDED
- name: rollouts/1788942172101727/phases/binary
startTime: "2026-09-09T08:23:29.585375Z"
state: SUCCEEDED
- name: rollouts/1788942172101727/phases/finalize
state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta
確認 binary 階段狀態變更為 SUCCEEDED。在所有剩餘階段完成前,整體推出狀態都會維持 IN_PROGRESS。phases/binary 轉換為 SUCCEEDED 後,部署作業即可繼續進行其餘階段。
步驟 5:安排並執行其餘階段
二進位階段成功且確認部署穩定後,請安排推出作業的其餘階段,直到 finalize 階段為止。finalize 階段 (推出作業的最後階段) 會在整個部署作業中封存新版本。只要指定 --deployment-endpoint,即可從任何可透過網路存取 Spanner Omni 服務的機器執行這項指令。
針對處於 PENDING 狀態的每個剩餘階段 (例如 enable_features (如有),接著是 finalize),請完成下列步驟:
排定階段時程:
spanner deployment rollouts phases schedule PHASE_NAME \ --rollout=ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINT更改下列內容:
PHASE_NAME:要排程的階段名稱,例如finalize或enable_features。ROLLOUT_ID:推出作業的數字 ID,例如1788942172101727。DEPLOYMENT_ENDPOINT:部署作業中伺服器的端點。
輸出內容會指出排定的階段為
IN_PROGRESS:name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/finalize state: IN_PROGRESS sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: IN_PROGRESS targetVersion: 2026.r3-beta等待階段成功,並驗證其狀態:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINT對其餘階段重複執行上述步驟,直到完成所有階段 (包括
finalize)。最後一個階段 (
finalize) 完成後,所有階段和整體推出作業狀態都會轉換為SUCCEEDED:endTime: "2026-09-09T08:45:43.949702Z" name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/finalize startTime: "2026-09-09T08:45:43.898111Z" state: SUCCEEDED sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED targetVersion: 2026.r3-beta在推出作業清單中確認完成狀態:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINT輸出內容會確認推出作業已完成:
NAME STATE TARGET_VERSION START_TIME END_TIME rollouts/1788942172101727 SUCCEEDED 2026.r3-beta 2026-09-09T08:22:52.101727Z 2026-09-09T08:45:43.949702Z
復原升級
如果在升級期間遇到問題,是否可以復原升級取決於目前的推出階段:
- 結構定義階段:無法復原。準備期間套用的內部資料庫結構定義遷移作業只能向前執行,無法還原。不過,結構定義遷移與來源版本回溯相容,因此舊版伺服器二進位檔可繼續正常運作。
- 二進位檔階段:在最終處理開始前,隨時可以復原為舊版。詳情請參閱「復原二進位檔或容器映像檔」。
- 選用推出階段:對於支援自動復原的選用階段 (例如功能啟用),請使用 Spanner Omni CLI 啟動復原。
- 完成階段:無法復原。完成程序開始後,目標版本會在整個部署作業中永久封存,無法復原。
復原二進位檔或容器映像檔
如要在最終處理開始前復原二進位檔階段,請在所有伺服器或 Pod 執行滾動式重新啟動,還原至先前的 (來源) 版本。
VM
在 VM 部署作業中,復原所有 VM 的 spanner_server 二進位檔:
- 將舊版
spanner_server二進位檔部署至主機。 - 在故障域中逐步重新啟動伺服器,一次更新一個可用區,且同時重新啟動的伺服器不超過 5%,以保留 Paxos 仲裁。
- 確認所有重新啟動的伺服器都運作正常,且已重新加入叢集,再繼續處理下一個故障域。
Helm
在 Helm 部署作業中,將容器映像檔標記更新回舊版本:
helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
--version CHART_VERSION \
-n NAMESPACE \
--reuse-values \
--set image.tag=SOURCE_VERSION \
--timeout 30m
更改下列內容:
CHART_VERSION:Helm 圖表版本,例如1.1.0。NAMESPACE:部署作業的 Kubernetes 命名空間,例如spanner-ns。SOURCE_VERSION:要還原的舊版容器映像檔標記,例如2026.r2-beta.3。
獨立 Kubernetes
在不使用 Helm 的自訂 Kubernetes 部署作業中,將 StatefulSet 或 Deployment 規格中的容器映像檔更新回 SOURCE_VERSION。
在故障域中執行滾動式更新,一次更新一個可用區,且同時重新啟動的 Pod 不超過 5%,以維持仲裁。
復原選用的推出階段
如果是支援復原的選用推出階段 (例如功能啟用階段),請執行 rollouts rollback 指令來啟動復原:
spanner deployment rollouts rollback ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
更改下列內容:
ROLLOUT_ID:推出作業的數字 ID。DEPLOYMENT_ENDPOINT:部署作業中伺服器的端點。
後續步驟
- 瞭解如何維護部署作業。
- 瞭解如何調度 Kubernetes 部署作業資源或調度 VM 部署作業資源。
- 瞭解監控總覽。