跳至主要内容

升級 Harvester

Harvester 採用了一種新的生命週期策略,簡化了版本管理和升級。此策略包括以下內容:

  • 四個月的次要版本發布週期(4 月、8 月和 12 月)
  • 兩個月的補丁版本發布週期(盡力而為)
  • 元件採用政策
備註

Harvester 不支援降級。此限制有助於防止與功能不相容、棄用和移除相關的意外系統行為和問題。

升級路徑​

下表概述了支援的升級路徑。

已安裝版本支援的升級版本
v1.6.xv1.6.y(y 大於 x)
v1.5.xv1.6.x
v1.5.0v1.5.1
v1.4.2/v1.4.3v1.5.0 和 v1.5.1
v1.4.1/v1.4.2v1.4.3
v1.4.1v1.4.2
v1.4.0v1.4.1
v1.3.2v1.4.0
v1.3.1v1.3.2
v1.2.2/v1.3.0v1.3.1
v1.2.1v1.2.2
v1.1.2/v1.1.3/v1.2.0v1.2.1

最新的 Harvester 版本允許以下操作:

  • 從一個次要版本升級到下一個次要版本(例如,從 v1.5.2 到 v1.6.1),而無需安裝兩個版本之間發布的補丁。這是可能的,因為 Harvester 允許底層元件最多升級一個次要版本。
  • 升級到更新的補丁版本(例如,從 v1.6.0 到 v1.6.1),假設在給定次要版本的發布中使用相同的元件版本。

下表概述了這些版本中使用的元件:

元件Harvester v1.5.xHarvester v1.6.x
KubeVirtv1.4v1.5
Longhornv1.8v1.9
Rancherv2.11v2.12
RKE2v1.32v1.33
備註

上游不支援跳過多個 Kubernetes 次要版本,這是升級路徑受限的主要原因。如需更多資訊,請參閱 Kubernetes 文件中的 Version Skew Policy。

Rancher 升級​

如果您使用 Rancher 管理 Harvester 叢集,則必須在升級 Harvester 之前先升級 Rancher。

important

Harvester 和 Rancher 的升級過程彼此獨立。在 Rancher 升級期間,您仍然可以使用虛擬 IP 存取 Harvester 叢集。Harvester 不會自動升級。

當 Rancher 版本達到其維護結束日期(EOM)時,Harvester 僅提供影響整合功能(虛擬化管理)的關鍵安全相關問題的修復。如需更多資訊,請參閱 Harvester & Rancher Support Matrix。

升級過程中的虛擬機管理​

可即時遷移的虛擬機​

可即時遷移的虛擬機在目前節點升級之前會透過批次遷移自動遷移到其他節點。這些虛擬機在遷移期間不會停機。

不可遷移的虛擬機​

當觸發升級時,Harvester 會根據 upgrade-config 設定的 restoreVM 選項值執行特定操作。

  • false:當不可遷移的虛擬機仍在執行時,Harvester 不會執行升級。您必須手動關閉虛擬機。

  • true:當節點升級時,Harvester 會自動關閉不可遷移的虛擬機,然後在節點重新啟動後恢復它們。

警告

不可遷移的虛擬機在遷移期間會停機。

如需更多資訊,請參閱 Phase 4: Upgrade Nodes。

開始升級前​

查看可用的 upgrade-config 設定以調整最適合您叢集環境的升級策略和行為。

開始升級​

警告
  • 在升級 Harvester 叢集之前,我們強烈建議:
    • 如有需要,備份您的虛擬機。
  • 在升級期間不要操作叢集。例如,建立新虛擬機、上傳新映像檔等。
  • 確保您的硬體符合建議的硬體需求。這是因為升級會消耗中間資源。
  • 確保每個節點至少有 30 GiB 的可用系統分割區空間(df -h /usr/local/)。如果叢集中任何節點的可用系統分割區空間少於 30 GiB,升級將被拒絕。查看可用系統分割區空間需求以獲取更多資訊。
  • 在 Harvester 控制平面節點上執行預檢查腳本。請根據您叢集的版本選擇腳本:https://github.com/harvester/upgrade-helpers/tree/main/pre-check。
  • 將在 harvester-system 和 cattle-system 命名空間中建立多個一次性的特權 Pod 以執行主機級別的升級操作。如果啟用了 pod security admission,請調整這些政策以允許這些 Pod 執行。
警告

  • 確保所有節點的時間同步。建議使用 NTP 伺服器同步時間。如果在安裝期間未配置 NTP 伺服器,您可以在每個節點上手動新增 NTP 伺服器:

    $ sudo -i

    # Add time servers
    $ vim /etc/systemd/timesyncd.conf
    [ntp]
    NTP=0.pool.ntp.org

    # Enable and start the systemd-timesyncd
    $ timedatectl set-ntp true

    # Check status
    $ sudo timedatectl status
警告
  • 連接到 PCI 橋接器的網路介面卡可能會在升級後重新命名。請查看知識庫文章以獲取更多資訊。

  1. 確保閱讀上述 caution。

  2. 在 Harvester UI Dashboard 畫面上,點擊 Upgrade。

    每當有可供升級的新 Harvester 版本時,Upgrade 按鈕就會出現。

    如果您的環境無法直接存取網際網路,請按照準備離線升級中的說明操作,該說明提供了一種高效下載 Harvester ISO 的方法。

  3. 選擇您要升級到的版本。

    如果您需要自訂,請參閱自訂版本。

  4. 點擊進度指示器(圓圈按鈕)以查看每個相關過程的狀態。

自訂版本​

  1. 下載版本檔案(https://releases.rancher.com/harvester/{version}/version.yaml)。

    範例:

    Harvester v1.5.0 版本檔案下載為 v1.5.0.yaml。

    apiVersion: harvesterhci.io/v1beta1
    kind: Version
    metadata:
      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
      namespace: harvester-system
    spec:
      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
      releaseDate: '20250425'

  2. 執行 kubectl create -f v1.5.0.yaml 以建立版本。

準備離線升級​

警告

請務必先查看升級路徑章節以了解可升級的版本。

準備 ISO 檔案​

  1. 從 Releases 頁面下載 Harvester ISO 檔案。

  2. 將 ISO 儲存到本地 HTTP 伺服器。假設檔案託管在 http://10.10.0.1/harvester.iso。

準備版本​

  1. 下載版本檔案(https://releases.rancher.com/harvester/{version}/version.yaml)。

    • 替換 version.yaml 檔案中的 isoURL 值:

      apiVersion: harvesterhci.io/v1beta1
      kind: Version
      metadata:
        name: v1.5.0
        namespace: harvester-system
      spec:
        isoChecksum: <SHA-512 checksum of the ISO>
        isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
        releaseDate: '20250425'

    • 假設檔案託管在 http://10.10.0.1/version.yaml。

    • 如果您需要自訂,請參閱自訂版本。

  2. 透過 SSH 存取其中一個控制平面節點並使用 root 帳戶登入。

  3. 建立版本物件。

    rancher@node1:~> sudo -i
    rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml

開始升級​

每當有可供升級的新 Harvester 版本時,Upgrade 按鈕就會出現在 Dashboard 畫面上。如果按鈕未出現,請重新整理畫面。

在 Harvester 官方升級可用之前手動開始升級​

新 Harvester 版本發布後,Upgrade 按鈕不會立即出現在 UI 上。如果您想在 UI 上提供該選項之前升級叢集,請按照準備離線升級中的步驟操作。

提示

在生產環境中,建議透過 Harvester UI 升級叢集。

可用系統分割區空間需求​

v1.5.0 起可用

Harvester 在升級期間在每個節點上載入映像檔。當磁碟使用率超過 kubelet 的垃圾收集閾值時,kubelet 會刪除未使用的映像檔以釋放空間。這可能會在離線環境中導致問題,因為映像檔在節點上不可用。

Harvester 包含檢查以確保節點在載入新映像檔後不會觸發垃圾收集。

當磁碟空間不足時,Harvester 會阻止升級並返回類似以下的錯誤:

Node "harvester-node-0" will reach 92.84% storage space after loading new images. It's higher than kubelet image garbage collection threshold 85%.

如果您想嘗試升級,即使某些節點上的可用系統分割區空間不足,您可以更新 Upgrade 物件的 harvesterhci.io/skipGarbageCollectionThresholdCheck: true 註釋。

apiVersion: harvesterhci.io/v1beta1
kind: Upgrade
metadata:
  annotations:
    harvesterhci.io/skipGarbageCollectionThresholdCheck: true
  generateName: hvst-upgrade-
  namespace: harvester-system
spec:
  version: "1.6.0"
  logEnabled: true
警告

設定比預定義值更小的值可能會導致升級失敗,不建議在生產環境中使用。

以下章節描述了與此需求相關的問題的解決方案。

手動釋放系統分割區空間​

Harvester 在升級完成後會嘗試刪除不必要的容器映像檔。但是,由於各種原因,可能不會執行此自動映像檔清理。您可以使用此腳本手動刪除映像檔。如需更多資訊,請參閱 issue #6620。

設定私有容器映像庫並跳過映像檔預載​

即使您刪除了映像檔,系統分割區可能仍然缺乏可用空間。要解決此問題,請為目前和新映像檔設定私有容器映像庫,並使用以下值配置設定 upgrade-config:

{"imagePreloadOption":{"strategy":{"type":"skip"}}, "restoreVM": false}

Harvester 跳過升級映像檔預載過程。當節點上的部署升級時,容器執行時會載入儲存在私有容器映像庫中的映像檔。

警告

不要依賴公共容器映像庫。請注意任何潛在的網際網路服務中斷以及您距離達到 Docker Hub 速率限制的距離。無法下載任何所需的映像檔可能會導致升級失敗,並可能使叢集處於中間狀態。

憑證到期檢查​

v1.5.0 起可用

Harvester 檢查每個節點上憑證的有效期。此檢查消除了在升級過程中憑證到期的可能性。如果憑證將在 7 天內到期,則返回錯誤。可以透過設定 harvesterhci.io/minCertsExpirationInDay 註釋來覆蓋此行為。

範例:

apiVersion: harvesterhci.io/v1beta1
kind: Upgrade
metadata:
  annotations:
    harvesterhci.io/minCertsExpirationInDay: "14"
  generateName: hvst-upgrade-
  namespace: harvester-system
spec:
  version: "1.6.0"
  logEnabled: true

當此註釋新增到 Upgrade 物件時,Harvester 在偵測到將在 14 天內到期的憑證時會返回錯誤。

如需更多資訊,請參閱 auto-rotate-rke2-certs。

虛擬機備份相容性​

在 Harvester v1.4.2 及更高版本中,當建立和還原涉及外部儲存的備份時,您可能會遇到某些限制

Longhorn Manager 因 Backing Image 驅逐而當機​

警告

當升級到 Harvester v1.4.x 時,如果任何節點或磁碟上的 EvictionRequested 標誌設定為 true,Longhorn Manager 可能會當機。此問題是由 backing image spec 中磁碟的刪除與其狀態更新之間的競爭條件引起的。

要防止問題發生,請確保在開始升級過程之前將 EvictionRequested 標誌設定為 false。

重新啟用 RKE2 ingress-nginx Admission Webhooks(CVE-2025-1974)​

如果您停用了 RKE2 ingress-nginx admission webhooks 以緩解 CVE-2025-1974,您必須在升級到 Harvester v1.5.0 或更高版本後重新啟用 webhook。

  1. 確認 Harvester 正在使用 nginx-ingress v1.12.1 或更高版本。
$ kubectl -n kube-system get po -l"app.kubernetes.io/name=rke2-ingress-nginx" -ojsonpath='{.items[].spec.containers[].image}'
rancher/nginx-ingress-controller:v1.12.1-hardened1

  1. 執行 kubectl -n kube-system edit helmchartconfig rke2-ingress-nginx 以從 HelmChartConfig 資源刪除以下配置。

    • .spec.valuesContent.controller.admissionWebhooks.enabled: false
    • .spec.valuesContent.controller.extraArgs.enable-annotation-validation: true

  2. 驗證新的 .spec.ValuesContent 配置類似於以下範例。

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: rke2-ingress-nginx
  namespace: kube-system
spec:
  valuesContent: |-
    controller:
      admissionWebhooks:
        port: 8444
      extraArgs:
        default-ssl-certificate: cattle-system/tls-rancher-internal
      config:
        proxy-body-size: "0"
        proxy-request-buffering: "off"
      publishService:
        pathOverride: kube-system/ingress-expose
important

如果 HelmChartConfig 資源包含其他自訂 ingress-nginx 配置,您必須在編輯資源時保留它們。

  1. 退出 kubectl edit 命令執行以儲存配置。

Harvester 在儲存內容後自動套用變更。

  1. 驗證 rke2-ingress-nginx-admission webhook 配置已重新啟用。
$ kubectl get validatingwebhookconfiguration rke2-ingress-nginx-admission
NAME                           WEBHOOKS   AGE
rke2-ingress-nginx-admission   1          6s
  1. 驗證 ingress-nginx Pod 已成功重新啟動。
kubectl -n kube-system get po -lapp.kubernetes.io/instance=rke2-ingress-nginx
NAME                                  READY   STATUS    RESTARTS   AGE
rke2-ingress-nginx-controller-l2cxz   1/1     Running   0          94s

升級卡在「Pre-drained」狀態​

升級過程可能會卡在「Pre-drained」狀態。Kubernetes 應該清空節點上的工作負載,但某些因素可能會導致過程停滯。

一個可能的原因是與 Longhorn Instance Manager 的孤立引擎相關的程序。要確定這是否適用於您的情況,請執行以下步驟:

  1. 檢查卡住節點上 instance-manager Pod 的名稱。

    範例:

    卡住的節點是 harvester-node-1,Instance Manager Pod 的名稱是 instance-manager-d80e13f520e7b952f4b7593fc1883e2a。

    $ kubectl get pods -n longhorn-system --field-selector spec.nodeName=harvester-node-1 | grep instance-manager
    instance-manager-d80e13f520e7b952f4b7593fc1883e2a          1/1     Running   0              3d8h

  2. 檢查 Longhorn Manager 日誌以獲取資訊訊息。

    範例:

    $ kubectl -n longhorn-system logs daemonsets/longhorn-manager
    ...
    time="2025-01-14T00:00:01Z" level=info msg="Node instance-manager-d80e13f520e7b952f4b7593fc1883e2a is marked unschedulable but removing harvester-node-1 PDB is blocked: some volumes are still attached InstanceEngines count 1 pvc-9ae0e9a5-a630-4f0c-98cc-b14893c74f9e-e-0" func="controller.(*InstanceManagerController).syncInstanceManagerPDB" file="instance_manager_controller.go:823" controller=longhorn-instance-manager node=harvester-node-1

    instance-manager Pod 無法被清空是因為引擎 pvc-9ae0e9a5-a630-4f0c-98cc-b14893c74f9e-e-0。

  3. 檢查引擎是否仍在卡住的節點上執行。

    範例:

    $ kubectl -n longhorn-system get engines.longhorn.io pvc-9ae0e9a5-a630-4f0c-98cc-b14893c74f9e-e-0 -o jsonpath='{"Current state: "}{.status.currentState}{"\nNode ID: "}{.spec.nodeID}{"\n"}'
    Current state: stopped
    Node ID:

    如果輸出顯示引擎未執行或甚至未找到引擎,則問題可能存在。

  4. 檢查所有卷是否健康。

    kubectl get volumes -n longhorn-system -o yaml | yq '.items[] | select(.status.state == "attached")| .status.robustness'

    所有卷必須標記為 healthy。如果不是這種情況,請協助報告問題。

  5. 刪除 instance-manager Pod 的 PodDisruptionBudget(PDB)。

    範例:

    kubectl delete pdb instance-manager-d80e13f520e7b952f4b7593fc1883e2a -n longhorn-system

相關 issue:#7366、#6764、#8977 和 #11605

不支援週期性 Longhorn 快照和備份​

週期性 Longhorn 快照和備份未整合到 Harvester 中。如果您決定使用此功能,則必須在開始升級之前停用 Longhorn 中的所有週期性快照和備份任務。

如需有關不相容性的更多資訊,請參閱排程虛擬機備份和快照。