使用 Azure Stack Hub 上的 AKS 引擎升级 Kubernetes 群集

项目
10/30/2024

使用 AKS 引擎可升级最初使用 Azure Stack Hub 上的工具部署的 Kubernetes 群集。可使用 AKS 引擎维护群集。维护任务类似于任何 IaaS 系统。需要注意新更新的可用性并使用 AKS 引擎应用这些更新。

升级群集

升级命令将更新 Kubernetes 版本和基本 OS 映像。每次运行升级命令时，AKS 引擎会使用与所使用的 aks-engine 版本相关联的 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 提供程序
基本 OS

升级生产群集时，请考虑以下事项：

是否为目标群集使用了正确的群集规范 (apimodel.json) 和资源组？
是否为客户端计算机使用了可靠的计算机来运行 AKS 引擎并从中执行升级操作？
请确保拥有可操作的备份群集。
如果可能，请从 Azure Stack Hub 环境中的 VM 运行命令，以减少网络跃点和潜在的连接故障。
请确保订阅有足够的空间来完成整个过程。相应进程将在此过程中分配新的 VM。
未规划系统更新或计划的任务。
在精确配置为生产群集的群集上，设置分阶段升级，并在生产群集中执行此操作之前，在该群集上测试升级

升级到更新的 Kubernetes 版本的步骤

注意

如果使用的是较新版本的 aks-engine 且应用市场提供映像，也会升级 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`。
location	local	Azure Stack Hub 的区域名称。对于 ASDK，此区域设置为 `local`。
resource-group	kube-rg	输入新资源组的名称，或者选择现有资源组。资源名称必须为字母数字，且必须小写。
subscription-id	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入订阅 ID。有关详细信息，请参阅订阅套餐
api-model	./kubernetes-azurestack.json	群集配置文件的路径或 API 模型。
client-id	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入服务主体 GUID。 Azure Stack Hub 管理员创建服务主体时标识为应用程序 ID 的客户端 ID。
client-secret	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	输入服务主体密码。这是在创建服务时设置的客户端机密。
identity-system	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 引擎将继续从之前失败的操作开始运行。

仅升级 OS 映像的步骤

查看 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 引擎，在安装了 aks-engine 的计算机中运行：./get-akse.sh --version vx.xx.x，并将 x.xx.x 替换为目标版本。
要求 Azure Stack Hub 操作员在 Azure Stack Hub 市场中添加所需的计划使用的 AKS 基础映像版本。
使用正在使用的 Kubernetes 版本运行 aks-engine upgrade 命令，但添加 --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 文件，并在 aks-engin upgrade 命令中使用 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. 替换存储类

手动删除树内存储类 (kubernetes.io/azure-disk) 后，kube-addon-manager 将自动创建 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 对的部署或 StatefulSet（根据需要备份资源定义）。
确保 PV 的 persistentVolumeReclaimPolicy 属性设置为值 Retain（示例）。
删除要迁移的 PV + PVC 对（根据需要备份资源定义）。
若要迁移，请通过删除 azureDisk 对象并添加引用原始 AzureDisk 的 csi 对象来更新 PV 的资源定义（示例）。
依次重新创建 PV 资源、PVC 资源（如果需要）、部署或 StatefulSet。

以下迁移脚本是作为模板提供的。

运行迁移脚本后，如果 Pod 停滞在“无法附加或装载卷”错误状态，请确保已安装 Azure 磁盘 CSI 驱动程序并已重新创建存储类。

强制升级

在某些情况下，可能需要强制实施群集升级。例如，在第一天，你使用最新 Kubernetes 版本在断开连接的环境中部署群集。第二天，Ubuntu 发布了一个漏洞修补程序，Microsoft 为其生成了新的 AKS 基础映像。这时就可以使用已部署的 Kubernetes 版本强制进行升级来应用新映像。

注意