在 Azure Stack Hub 上使用 AKS 引擎升級 Kubernetes 叢集

發行項
03/20/2025

AKS 引擎可讓您升級原本使用 Azure Stack Hub 上的工具部署的 Kubernetes 叢集。您可以使用 AKS 引擎來維護叢集。您的維護工作類似於任何 IaaS 系統。您應該知道新更新的可用性，並使用 AKS 引擎來套用這些更新。

升級集群

升級命令會更新 Kubernetes 版本和基底 OS 映像。每次執行升級命令時，針對叢集的每個節點，AKS 引擎都會使用與所使用 aks 引擎版本相關聯的 AKS 基底映像來建立新的 VM。

針對 AKS 引擎 0.73.0 版和以下版本，您可以使用 aks-engine upgrade 命令來維護叢集中每個主要和代理程式節點的貨幣。

針對 AKS 引擎 0.75.3 版和更新版本，您可以使用 aks-engine-azurestack upgrade 命令來維護叢集中每個主要和代理程式節點的貨幣。

Microsoft不會管理您的叢集。但Microsoft提供可用來管理叢集的工具和 VM 映像。

針對已部署的叢集，升級涵蓋：

Kubernetes
Azure Stack Hub Kubernetes 提供者
基礎作業系統

升級生產叢集時，請考慮：

您是否針對目標叢集使用正確的叢集規格（apimodel.json）和資源群組？
您是否使用可靠的客戶機來運行 AKS 引擎，並從該客戶機執行升級作業？
請確定您有備份叢集，且其運作正常。
可能的話，請從 Azure Stack Hub 環境內的 VM 執行命令，以減少網路躍點和潛在的連線失敗。
請確定您的訂用帳戶有足夠的空間可供整個程式使用。進程會在其過程中配置新的虛擬機。
未規劃任何系統更新或排程的工作。
在設定完全與生產叢集相同的叢集上進行分段升級，並先在該叢集上測試升級，再在生產叢集上執行。

升級至較新 Kubernetes 版本的步驟

注意

如果您使用較新版本的 aks 引擎，且映像可在市集中使用，也會升級 AKS 基底映射。

下列指示會使用最低步驟來執行升級。如果您想要更多詳細數據，請參閱升級 Kubernetes 叢集一文。

您必須先確認可供升級的目標版本。此版本取決於您目前擁有的版本，然後使用該版本值來執行升級。您可以執行下列命令來列出 AKS 引擎支援的 Kubernetes 版本：

注意

針對 AKSe 0.75.3 版和更新版本，取得 AKS 引擎版本的命令為 aks-engine-azurestack get-versions。
```
aks-engine get-versions --azure-env AzureStackCloud
```
如需 AKS 引擎、AKS 基底映像和 Kubernetes 版本的完整對應關係圖，請參閱支援的 AKS 引擎版本。

收集您需要執行 upgrade 命令的資訊。此指令 upgrade 會使用下列參數：

參數	範例	描述
azure-env	AzureStackCloud	若要向 AKS 引擎指出您的目標平臺是 Azure Stack Hub 使用 `AzureStackCloud`。
位置	本地	Azure Stack Hub 的區域名稱。針對 ASDK，區域會設定為 `local`。
資源群組	kube-rg	輸入新資源群組的名稱，或選取現有的資源群組。資源名稱必須是英數位元和小寫。
訂閱識別碼	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	輸入您的訂用帳戶標識碼。如需詳細資訊，請參閱訂閱優惠
API 模型	./kubernetes-azurestack.json	叢集組態檔或 API 模型的路徑。
客戶識別碼	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	輸入服務主體識別碼 GUID。當您的 Azure Stack Hub 系統管理員建立服務主體時，用戶端識別符會識別為應用程式識別碼。
用戶密鑰	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	輸入服務主體密碼。這是您在建立服務時設定的客戶端密碼。
身份系統	adfs	選擇性。如果您使用 Active Directory 同盟服務（AD FS），請指定您的身分識別管理解決方案。

設定好您的參數後，執行下列命令：

注意

針對 AKSe 0.75.3 版和更新版本，升級 AKS 引擎的命令為 aks-engine-azurestack upgrade。

aks-engine upgrade \
--azure-env AzureStackCloud \
--location <for an ASDK is local> \
--resource-group kube-rg \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--api-model kube-rg/apimodel.json \
--upgrade-version 1.18.15 \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--identity-system adfs # required if using AD FS

如果因為任何原因，升級作業發生失敗，您可以在解決問題之後重新執行 upgrade 命令。 AKS 引擎會繼續先前失敗的作業。

僅升級操作系統映像的步驟

檢閱 supported-kubernetes-versions 數據表，並判斷您是否有您規劃升級的 aks-engine 和 AKS 基底映射版本。如果您是在 AKS 引擎 0.73.0 版或更新版本上，則檢視 aks-engine 執行的版本： aks-engine version。如果您是在 AKS 引擎 0.75.3 版或更新版本上，則檢視 aks-engine 執行的版本： aks-engine-azurestack version。
在您已安裝 aks-engine 的計算機上升級您的 AKS 引擎，執行：./get-akse.sh --version vx.xx.x，並將 x.xx.x 替換為您的目標版本。
要求您的 Azure Stack Hub 操作員在您打算使用的 Azure Stack Hub Marketplace 中新增所需的 AKS 基底映射版本。
執行 aks-engine upgrade 命令，使用您目前正在使用的 Kubernetes 版本，但要新增 --force。您可以在強制升級中看到範例。

將叢集更新至OS Ubuntu 20.04版的步驟

使用 AKS 引擎 0.75.3 版和更新版本，您可以將叢集 VM 從 Ubuntu 18.04 升級至 20.04。執行下列步驟:

找出並編輯 api-model.json 部署期間產生的檔案。這應該是任何使用 aks-engine 的升級或伸縮作業所用的相同檔案。在 AKS 引擎 0.75.3 版和更新版本中，使用 aks-engine-azurestack。
定位masterProfile和agentPoolProfiles的區段，在這些區段中將distro的值變更為aks-ubuntu-20.04。
儲存 api-model.json 檔案並在命令中使用 api-model.json 檔案，如同在升級至較新版的 Kubernetes 時所用的步驟一樣。

如果您使用記憶體磁碟區搭配 AKS 引擎 v0.70.0 和更新版本，升級叢集的步驟

適用於 Azure 的雲端提供者專案（也稱為cloud-controller-manager樹狀架構外雲端提供者或外部雲端提供者）會實作 Azure 雲端的 Kubernetes 雲端提供者介面。樹外建置是用來取代已被淘汰的樹內建置。

在 Azure Stack Hub 上，從 Kubernetes v1.21 開始，AKS 引擎型叢集將獨佔使用 cloud-controller-manager。因此，若要部署 Kubernetes v1.21+ 叢集，必須在 API 模型中將設定 orchestratorProfile.kubernetesConfig.useCloudControllerManager 為 true （範例）。 AKS 引擎的升級程式會自動更新 useCloudControllerManager 旗標。

注意

升級考慮： 將 Kubernetes 叢集從 v1.20（或更低版本）升級至 v1.21（或更高版本）的過程，會導致依賴 kubernetes.io/azure-disk 內建磁碟區佈建器的工作負載停機。升級至 Kubernetes v1.21+ 之前，強烈建議您執行應用程式數據的完整備份，並在生產前環境中驗證叢集記憶體資源（PV 和PVC）可以移轉至新的磁碟區布建器。在這裡瞭解如何移轉至 Azure 磁碟 CSI 驅動程式。

磁碟區配置程式

樹狀結構內磁碟區布建器只與樹狀結構中的雲端提供者相容。因此，如果使用者工作負載依賴永續性記憶體，v1.21+ 叢集必須包含容器記憶體介面（CSI）驅動程式。此處列出一些 Azure Stack Hub 上可用的解決方案。

AKS 引擎預設不會在 Azure Stack Hub 上啟用任何 CSI 驅動程式。對於需要 CSI 驅動程式的工作負載，您可以明確啟用azuredisk-csi-driver附加元件（僅限 Linux 叢集），或使用 Helm 來安裝azuredisk-csi-driver圖表（Linux 和/或 Windows 叢集）。

將持續性儲存遷移至 Azure 磁碟 CSI 驅動程式

將 AKS 引擎型叢集從 v1.20（或較低版本）升級至 v1.21（或更高版本）的過程會導致依賴kubernetes.io/azure-disk 內嵌卷配置器的工作負載停機，因為此配置器不是 Azure 雲端提供者的一部分。

如果應該保留基礎 Azure 磁碟的數據，則完成叢集升級程序之後，需要執行下列額外步驟：

1.手動安裝 Azure 磁碟 CSI 驅動程式

下列文稿會使用 Helm 來安裝 Azure 磁碟 CSI 驅動程式：

DRIVER_VERSION=v1.10.0
helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts
helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver \
  --namespace kube-system \
  --set cloud=AzureStackCloud \
  --set controller.runOnMaster=true \
  --version ${DRIVER_VERSION}

2.取代記憶體類別

kube-addon-manager將在手動刪除樹狀儲存類別（kubernetes.io/azure-disk）後，自動建立 Azure 磁碟 CSI 驅動程式的儲存類別（disk.csi.azure.com）。

IN_TREE_SC="default managed-premium managed-standard"

# Delete deprecated "kubernetes.io/azure-disk" storage classes
kubectl delete storageclasses ${IN_TREE_SC}

# Wait for addon manager to create the "disk.csi.azure.com" storage class resources
kubectl get --watch storageclasses

3.重新建立永續性磁碟區

安裝 Azure 磁碟 CSI 驅動程式並取代儲存類別之後，下一個步驟是使用 Azure 磁碟 CSI 驅動程式（或替代的 CSI 解決方案）重新建立永續性磁碟區（PV）和永續性磁碟區申請（PVC）。

這是多步驟程式，視這些資源一開始的部署方式而定，可能會有所不同。高階步驟如下：

刪除參考 PV + PVC 配對以移轉的部署或具狀態設置（如有必要，請備份資源定義）。
確定 PVs 的 persistentVolumeReclaimPolicy 屬性設定為 value Retain （example）。
刪除 PV +PVC 配對以移轉（如有必要，請備份資源定義）。
若要移轉，請更新 PVs 的資源定義，方法是移除 azureDisk 物件並新增 csi 物件，該物件參考原始的 AzureDisk（範例）。
依下列順序重新建立 PV 資源、PVC 資源（如果有需要），最後是部署或 StatefulSet。

提供下列的遷移腳本作為範本。

執行移轉腳本之後，如果 Pod 遇到錯誤「無法連結或掛接儲存區域」，請確定已安裝 Azure 磁碟 CSI 驅動程式，並重新建立儲存類別。

強制升級

可能會有某些情況讓您想要強制升級您的叢集。例如，第一天，您會使用最新的 Kubernetes 版本，在中斷聯機的環境中部署叢集。第二天，Ubuntu 發行針對一個弱點的修補程式，Microsoft 隨後生成一個新的 AKS 基礎映像。您可以使用您已部署的相同 Kubernetes 版本來強制升級，以套用新的映像。

注意事項