跳至主要内容

升級使用 Docker 安裝的 Rancher

Docker 安裝支援

Docker 安裝僅支援開發和測試環境。對於生產環境，請在 Kubernetes 叢集上安裝 Rancher。

以下說明將引導您升級使用 Docker 安裝的 Rancher 伺服器。

先決條件​

佔位符檢視​

在升級期間，您將輸入一系列指令，並使用來自您環境的資料填入佔位符。這些佔位符以角括號和全部大寫字母表示（<EXAMPLE>）。

以下是包含佔位符的指令範例：

docker stop <RANCHER_CONTAINER_NAME>

在此指令中，<RANCHER_CONTAINER_NAME> 是您的 Rancher 容器的名稱。

取得升級指令的資料​

若要取得用於替換佔位符的資料，請執行：

docker ps

在開始升級之前，請記下或複製此資訊。

終端機 docker ps 指令，顯示在哪裡找到 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME>

Placeholder Reference

佔位符範例描述
<RANCHER_CONTAINER_TAG>v2.1.3您為初始安裝拉取的 rancher/rancher 映像。
<RANCHER_CONTAINER_NAME>festive_mestorf您的 Rancher 容器的名稱。
<RANCHER_VERSION>v2.1.3您要為其建立備份的 Rancher 版本。
<DATE>2018-12-19建立資料容器或備份的日期。

您可以透過遠端連線登入 Rancher 伺服器並輸入檢視正在執行的容器的指令來取得 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME>：docker ps。您也可以使用不同的指令檢視已停止的容器：docker ps -a。在建立備份時，隨時使用這些指令來獲得幫助。

升級​

危險

如果偵測到任何 RKE1 相關資源，升級到 Rancher 2.12.0 版及更高版本將被阻止，因為 Rancher Kubernetes Engine (RKE/RKE1) 已於 2025 年 7 月 31 日終止生命週期。有關詳細的清理和復原步驟，請參閱 Rancher v2.12 中的 RKE1 資源驗證和升級要求。

在升級期間，您會從當前 Rancher 容器建立資料副本，並在發生問題時建立備份。然後，您使用現有資料在新容器中部署新版本的 Rancher。

1. 從您的 Rancher 伺服器容器建立資料副本​

  1. 使用遠端終端機連線，登入執行 Rancher 伺服器的節點。

  2. 停止目前執行 Rancher 伺服器的容器。將 <RANCHER_CONTAINER_NAME> 替換為您的 Rancher 容器的名稱。

    docker stop <RANCHER_CONTAINER_NAME>

  3. 使用以下指令（替換每個佔位符）從您剛停止的 Rancher 容器建立資料容器。

    docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>

2. 建立備份 tarball​

  1. 從您剛建立的資料容器 (rancher-data) 建立備份 tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz)。

    如果升級期間出現問題，此 tarball 將作為回滾點。使用以下指令，替換每個佔位符。

    docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

    步驟結果： 當您輸入此指令時，應該會執行一系列指令。

  2. 輸入 ls 指令以確認已建立備份 tarball。它將具有類似 rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz 的名稱。

    [rancher@ip-10-0-0-50 ~]$ ls
    rancher-data-backup-v2.1.3-20181219.tar.gz

  3. 將您的備份 tarball 移至 Rancher 伺服器外部的安全位置。

3. 拉取新的 Docker 映像​

拉取您要升級到的 Rancher 版本的映像。

佔位符描述
<RANCHER_VERSION_TAG>您要升級到的 Rancher 版本的發行標籤。
docker pull rancher/rancher:<RANCHER_VERSION_TAG>

4. 啟動新的 Rancher 伺服器容器​

使用 rancher-data 容器中的資料啟動新的 Rancher 伺服器容器。記得傳入您在啟動原始容器時使用的所有環境變數。

危險

不要在啟動升級後停止升級，即使升級過程似乎比預期的時間長。停止升級可能會導致未來升級期間出現資料庫遷移錯誤。

如果您使用了代理，請參閱 HTTP 代理設定。

如果您設定了自訂 CA 根憑證以存取您的服務，請參閱自訂 CA 根憑證。

如果您正在使用 Rancher API 記錄所有交易，請參閱 API 稽核

若要查看啟動新 Rancher 伺服器容器時要使用的指令，請從以下選項中選擇：

  • Docker 升級
  • 離線安裝的 Docker 升級

選擇您安裝 Rancher 伺服器的選項

選項 A：預設自簽憑證​

點擊展開

如果您選擇使用 Rancher 產生的自簽憑證，請將 --volumes-from rancher-data 新增到您啟動原始 Rancher 伺服器容器的指令中。

佔位符描述
<RANCHER_VERSION_TAG>您要升級到的 Rancher 版本的發行標籤。
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

必須使用特權存取。

選項 B：使用您自己的憑證：自簽​

點擊展開

如果您選擇使用自己的自簽憑證，請將 --volumes-from rancher-data 新增到您啟動原始 Rancher 伺服器容器的指令中，並且需要存取您最初安裝時使用的相同憑證。

憑證先決條件提醒：

憑證檔案必須為 PEM 格式。在您的憑證檔案中，包含鏈中的所有中繼憑證。以您的憑證排在最前，後面跟著中繼憑證的順序排列憑證。

佔位符描述
<CERT_DIRECTORY>包含憑證檔案的目錄路徑。
<FULL_CHAIN.pem>完整憑證鏈的路徑。
<PRIVATE_KEY.pem>憑證私密金鑰的路徑。
<CA_CERTS.pem>憑證授權單位憑證的路徑。
<RANCHER_VERSION_TAG>您要升級到的 Rancher 版本的發行標籤。
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

必須使用特權存取。

選項 C：使用您自己的憑證：由認可的 CA 簽署​

點擊展開

如果您選擇使用由認可的 CA 簽署的憑證，請將 --volumes-from rancher-data 新增到您啟動原始 Rancher 伺服器容器的指令中，並且需要存取您最初安裝時使用的相同憑證。記得將 --no-cacerts 作為容器的參數以停用 Rancher 產生的預設 CA 憑證。

憑證先決條件提醒：

憑證檔案必須為 PEM 格式。在您的憑證檔案中，包含認可的 CA 提供的所有中繼憑證。以您的憑證排在最前，後面跟著中繼憑證的順序排列憑證。有關範例，請參閱憑證疑難排解。

佔位符描述
<CERT_DIRECTORY>包含憑證檔案的目錄路徑。
<FULL_CHAIN.pem>完整憑證鏈的路徑。
<PRIVATE_KEY.pem>憑證私密金鑰的路徑。
<RANCHER_VERSION_TAG>您要升級到的 Rancher 版本的發行標籤。
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --no-cacerts

必須使用特權存取。

選項 D：Let's Encrypt 憑證​

點擊展開
警告

Let's Encrypt 對請求新憑證提供速率限制。因此，請限制建立或銷毀容器的頻率。有關更多資訊，請參閱 Let's Encrypt 關於速率限制的文件。

如果您選擇使用 Let's Encrypt 憑證，請將 --volumes-from rancher-data 新增到您啟動原始 Rancher 伺服器容器的指令中，並且需要提供您最初安裝 Rancher 時使用的網域。

憑證先決條件提醒：
  • 在您的 DNS 中建立一筆記錄，將您的 Linux 主機 IP 位址綁定到您要用於 Rancher 存取的主機名稱（例如 rancher.mydomain.com）。
  • 在您的 Linux 主機上開啟連接埠 TCP/80。Let's Encrypt http-01 挑戰可以來自任何來源 IP 位址，因此連接埠 TCP/80 必須對所有 IP 位址開放。
佔位符描述
<RANCHER_VERSION_TAG>您要升級到的 Rancher 版本的發行標籤。
<YOUR.DNS.NAME>您最初啟動時使用的網域位址
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --acme-domain <YOUR.DNS.NAME>

必須使用特權存取。

結果： 您已升級 Rancher。來自升級伺服器的資料現在已儲存到 rancher-data 容器，以供未來升級使用。

5. 驗證升級​

登入 Rancher。透過檢查瀏覽器視窗左下角顯示的版本來確認升級成功。

升級後使用者叢集中出現網路問題？

請參閱還原叢集網路。

6. 清理您的舊 Rancher 伺服器容器​

移除先前的 Rancher 伺服器容器。如果您只是停止先前的 Rancher 伺服器容器（而不移除它），該容器可能會在下次伺服器重新啟動後重新啟動。

Rancher v2.12 中的 RKE1 資源驗證和升級要求​

Rancher v2.12.0 及更高版本已移除對 Rancher Kubernetes Engine (RKE/RKE1) 的支援。在升級期間，Rancher 會驗證叢集資源，如果偵測到任何 RKE1 相關資源，則會阻止升級。

此驗證影響以下資源類型：

  • 具有 rkeConfig 的叢集 (clusters.management.cattle.io)
  • NodeTemplates (nodetemplates.management.cattle.io)
  • ClusterTemplates (clustertemplates.management.cattle.io)

這對於單節點 Docker 安裝特別相關，因為在升級期間 Rancher 未執行。在這種情況下，控制器無法自動清理已棄用的資源，升級過程將提前失敗並顯示列出阻止資源的錯誤。

1. 升級前（建議）​

在升級之前，當 Rancher 仍在執行時：

  • 執行 pre-upgrade-hook 清理腳本以刪除所有 RKE1 叢集和範本。您可以在 Rancher GitHub 儲存庫中找到該腳本：pre-upgrade-hook.sh。
  • 這允許 Rancher 清理關聯的資源和終結器。

2. 由於殘留的 RKE1 資源而導致升級後失敗​

如果嘗試升級到 Rancher v2.12.0 或更高版本而未事先清理 RKE1 資源：

  • 升級將失敗並顯示一個錯誤，列出阻止升級的資源名稱。
  • 發生這種情況是因為 Rancher 包含驗證以偵測並阻止升級，當不受支援的 RKE1 資源仍然存在時。
  • 要繼續，請回滾到先前的 Rancher 版本，刪除已識別的資源，然後在手動清理後重試。
基於 Helm 的 Rancher

基於 Helm 的 Rancher 安裝不受此問題影響，因為 Rancher 在升級期間保持可用，可以根據需要執行資源清理。

回滾後的手動清理​

使用者應在回滾到先前的 Rancher 版本後執行以下步驟：

  • 手動刪除升級錯誤訊息中列出的資源（例如，RKE1 叢集、NodeTemplates、ClusterTemplates）。
  • 如果由於終結器而阻止刪除，請編輯資源並移除 metadata.finalizers 欄位。
  • 如果驗證 webhook 阻止刪除（例如，對於 system-project），請參閱繞過 Webhook 文件。

回滾​

如果您的升級未成功完成，您可以將 Rancher 伺服器及其資料回滾到其最後的健康狀態。有關更多資訊，請參閱 Docker 回滾。