35 Edge 3.5 迁移 #
本章介绍如何将管理群集和下游群集从 Edge
3.4 迁移到 Edge 3.5.0。
始终从 Edge 3.4 的最新 z-stream 版本执行群集迁移。
始终迁移到 Edge 3.5.0 版本。对于迁移后的后续升级，请参见管理群集（第 36 章 “管理群集”）和下游群集（第 37 章 “下游群集”）章节。
下表列出了不同类型的群集及其对应的升级方法：
| 群集类型 | 方式 |
|---|---|
EIB 置备的群集 | 有关详细信息，请参见第 35.1.3 节 “Fleet”。 |
Metal3 置备的群集 | 有关详细信息，请参见第 44.3 节 “下游群集升级”。 |
Phone-home 置备的群集 | 请参见 Kubernetes 版本升级了解 Kubernetes 版本升级流程，参见第 37 章 “下游群集”了解 SUC、操作系统及其他组件的升级流程。 |
35.1 管理群集 #
本节将介绍以下主题：
第 35.1.1 节 “先决条件” - 开始迁移前需要完成的先决步骤。
第 35.1.2 节 “升级控制器” - 如何使用第 22 章 “升级控制器”执行管理群集迁移。
第 35.1.3 节 “Fleet” - 如何使用第 8 章 “Fleet”执行管理群集迁移。
35.1.1 先决条件 #
35.1.1.1 升级裸机操作器 CRD #
Metal3 Helm chart 利用 Helm 的
CRD
目录来包含裸机操作器
(BMO) CRD。
然而，这种方法存在一定的局限性，特别是无法使用 Helm 升级此目录中的 CRD。有关详细信息，请参见 Helm 文档。
因此，在将 Metal3 升级到与 Edge 3.5.0
兼容的版本之前，用户必须手动升级底层的 BMO CRD。
在安装了 Helm 且 kubectl
已配置为指向管理群集的计算机上：
手动应用 BMO CRD：
helm show crds oci://registry.suse.com/edge/charts/metal3 --version 305.0.21+up0.13.0 | kubectl apply -f -
35.1.1.2 SUSE Storage 迁移的准备工作 #
升级到 Edge 3.5.0 版本时，需要从原先的 Longhorn chart 迁移到 SUSE
Application Collection 中维护的 SUSE Storage chart。
此过程仅适用于需要升级 Longhorn chart 的管理群集。
您必须先将管理群集更新至最新的 3.4 z-stream 版本，该版本包含所需的 SUSE Storage 1.9.2 版本。
SUSE Storage chart 不再单独提供 CRD Helm chart，而是将其整合为一个整体，因此需要按照 SUSE Storage 文档中的说明，执行额外的迁移步骤。
首先，可检查当前已安装的 Longhorn CRD 版本。
helm list --all-namespaces | grep longhorn-crd longhorn-crd longhorn-system 1 2026-01-16 02:17:16.7804359 +0000 UTC deployed longhorn-crd-107.1.1+up1.9.2 v1.9.2接下来，克隆与当前已安装 Longhorn 版本对应的 rancher/chart 代码库，操作前必须先下载该脚本。
该脚本的执行命令如下：
./download-longhorn-crd-chart.sh 107.1.1+up1.9.2执行后，longhorn-crd chart 会被下载至本地目录
./107.1.1+up1.9.2下载完成后，打开
Chart.yaml文件，验证appVersion字段是否为 v1.9.2，以确认 chart 版本正确：cat 107.1.1+up1.9.2/Chart.yaml annotations: catalog.cattle.io/certified: rancher catalog.cattle.io/hidden: "true" catalog.cattle.io/namespace: longhorn-system catalog.cattle.io/release-name: longhorn-crd apiVersion: v1 appVersion: v1.9.2 description: Installs the CRDs for longhorn. name: longhorn-crd version: 107.1.1+up1.9.2随后，需要在克隆得到的
longhorn-crdchart的templates/crds.yaml文件中，将helm.sh/resource-policy注解的值修改为keep。该配置可确保 Helm 在卸载版本时，不会删除对应的 CRD。您可以下载该脚本，实现注解的自动修改：
./patch-resource-policy-annotation.sh 107.1.1+up1.9.2/templates/crds.yaml Processing CRDs in '107.1.1+up1.9.2/templates/crds.yaml'... Creating backup: '/tmp/crds.yaml.original' Successfully processed the file Original file backed up to: '/tmp/crds.yaml.original' Modified file saved as: '107.1.1+up1.9.2/templates/crds.yaml' Found 22 CustomResourceDefinition(s) Added 22 helm.sh/resource-policy: keep annotation(s) Original file: 4575 lines, Modified file: 4597 lines验证 CRD 是否已正确修改，可对比原始模板与修改后的模板，确认
helm.sh/resource-policy注解的值已设为keep：vim -d /tmp/crds.yaml.original 107.1.1+up1.9.2/templates/crds.yaml接下来，使用本地修改后的 chart，升级 longhorn-crd Helm 版本：
helm upgrade longhorn-crd -n longhorn-system ./107.1.1+up1.9.2完成后，从系统中卸载 longhorn-crd Helm 版本。由于已进行上述修改，对应的 CRD 将会保留：
helm uninstall longhorn-crd --namespace longhorn-system These resources were kept due to the resource policy: [CustomResourceDefinition] backingimagedatasources.longhorn.io [CustomResourceDefinition] backingimagemanagers.longhorn.io [CustomResourceDefinition] nodes.longhorn.io [CustomResourceDefinition] orphans.longhorn.io [CustomResourceDefinition] recurringjobs.longhorn.io [CustomResourceDefinition] replicas.longhorn.io [CustomResourceDefinition] settings.longhorn.io [CustomResourceDefinition] sharemanagers.longhorn.io [CustomResourceDefinition] snapshots.longhorn.io [CustomResourceDefinition] supportbundles.longhorn.io [CustomResourceDefinition] systembackups.longhorn.io [CustomResourceDefinition] systemrestores.longhorn.io [CustomResourceDefinition] backingimages.longhorn.io [CustomResourceDefinition] volumeattachments.longhorn.io [CustomResourceDefinition] volumes.longhorn.io [CustomResourceDefinition] backupbackingimages.longhorn.io [CustomResourceDefinition] backups.longhorn.io [CustomResourceDefinition] backuptargets.longhorn.io [CustomResourceDefinition] backupvolumes.longhorn.io [CustomResourceDefinition] engineimages.longhorn.io [CustomResourceDefinition] engines.longhorn.io [CustomResourceDefinition] instancemanagers.longhorn.io release "longhorn-crd" uninstalled重新运行以下命令确认
longhorn-crd不存在，以确保longhorn-crdchart 已成功卸载：helm list --all-namespaces | grep longhorn-crd。完成上述操作后，需要更新现有 Longhorn CRD 的所属标签，为升级到 SUSE Storage Helm chart 做准备。
执行该脚本，完成标签替换操作。
./migrate-crd-ownership.sh # The output will look like the following for each CRD. The most important thing to note is that each operation says "Successfully updated CRD..." at the end: Processing CRD: volumes.longhorn.io Warning: resource customresourcedefinitions/volumes.longhorn.io is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically. customresourcedefinition.apiextensions.k8s.io/volumes.longhorn.io configured Successfully updated CRD: volumes.longhorn.io注意Rancher Application Collection 仓库的登录凭证可在您的设置中的访问令牌部分查看（必须先登录）。
此外，您可在此处查看 Rancher Application Collection 的更多相关文档。
当所有 CRD 准备就绪后，登录到 Rancher Application Collection 中，以便拉取对应的 Helm chart：
helm registry login dp.apps.rancher.io -u ${APPS.RANCHER.IO_USERNAME} -p ${APPS.RANCHER.IO_ACCESS_TOKEN}随后，创建 docker-registry 机密，用于拉取容器映像：
kubectl create secret docker-registry rancher-app-collection \ --namespace longhorn-system \ --docker-server=dp.apps.rancher.io \ --docker-username="${APPS.RANCHER.IO_USERNAME}" \ --docker-password="${APPS.RANCHER.IO_ACCESS_TOKEN}"最后，将您的 Longhorn 实例升级到 SUSE Storage：
helm upgrade longhorn oci://dp.apps.rancher.io/charts/suse-storage \ --namespace longhorn-system \ --version 1.10.1 \ --set privateRegistry.registrySecret=rancher-app-collection如果需要，可在升级命令后附加
-f values.yaml，指定自定义的values.yaml文件。
35.1.1.3 Rancher Turtles 升级的准备工作 #
此过程仅适用于需要升级 rancher turtles chart 的 CAPI/Metal3 管理群集。
您必须先将管理群集更新至最新的 3.4 z-stream 版本，该版本包含所需的 Rancher Turtles 0.24.3 版本。
从 Rancher 2.13 版本开始，安装 Rancher 时会默认安装 Rancher Turtles，因此需要按照 Rancher Turtles 文档中的说明，执行额外的迁移步骤。
首先，去除已安装的 CAPIProvider 资源：
kubectl delete capiprovider -A --all等待上述步骤完成后，去除已安装的 rancher-turtles chart 以及
rancher-turtles-airgap-resources（如果已安装）。如果该组件是通过 Edge Image Builder
安装的，还需要去除对应的 HelmChart 资源：
kubectl delete -n kube-system helmchart rancher-turtles
kubectl delete -n kube-system helmchart rancher-turtles-airgap-resources随后，按照 Rancher Turtles 文档中的说明，修改 CRD 资源的配置：
kubectl patch crd capiproviders.turtles-capi.cattle.io --type=json -p='[{"op": "add", "path": "/metadata/annotations/meta.helm.sh~1release-namespace", "value": "cattle-turtles-system"}]'
kubectl patch crd clusterctlconfigs.turtles-capi.cattle.io --type=json -p='[{"op": "add", "path": "/metadata/annotations/meta.helm.sh~1release-namespace", "value": "cattle-turtles-system"}]'接下来，按照常规步骤，将管理群集升级到 Edge 3.5.0 版本。
35.1.1.4 Rancher Turtles 升级后操作 #
完成以下步骤将群集升级到 Edge 3.5.0 版本后，需要安装新版
rancher-turtles-providers Helm chart，该操作将创建新的
CAPIProvider 资源，替换升级前步骤中去除的资源。
该 chart 需要通过 HelmChart 资源进行安装，以便后续通过升级控制器实现自动升级：
helm pull oci://registry.suse.com/edge/charts/rancher-turtles-providers --version 305.0.4+up0.25.1
cat > turtles-providers-helmchart.yaml <<EOF
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
annotations:
edge.suse.com/repository-url: oci://registry.suse.com/edge/charts/rancher-turtles-providers
name: rancher-turtles-providers
namespace: kube-system
spec:
chartContent: $(base64 -w 0 rancher-turtles-providers-305.0.4+up0.25.1.tgz)
failurePolicy: reinstall
createNamespace: true
targetNamespace: cattle-turtles-system
version: 305.0.4+up0.25.1
EOF
kubectl apply -f turtles-providers-helmchart.yaml等待数分钟后，可观察到类似以下的输出信息：
kubectl get capiprovider -A
NAMESPACE NAME TYPE PROVIDERNAME INSTALLEDVERSION PHASE
capm3-system metal3 infrastructure metal3 v1.10.4 Ready
cattle-capi-system cluster-api core cluster-api v1.10.6 Ready
fleet-addon-system fleet addon rancher-fleet v0.12.0 Ready
metal3-ipam-system metal3ipam ipam metal3ipam v1.10.4 Ready
rke2-bootstrap-system rke2-bootstrap bootstrap rke2 v0.21.1 Ready
rke2-control-plane-system rke2-control-plane controlPlane rke2 v0.21.1 Ready35.1.2 升级控制器 #
升级控制器目前仅支持非隔离管理群集的
Edge 版本迁移。
本节将介绍以下主题：
第 35.1.2.1 节 “先决条件” -
针对升级控制器的先决条件。
第 35.1.2.2 节 “迁移步骤” -
使用升级控制器将管理群集迁移到新 Edge 版本的步骤。
35.1.2.1 先决条件 #
35.1.2.1.1 Edge 3.5 升级控制器 #
使用升级控制器之前，必须先确保其运行的版本能够迁移到目标 Edge 版本。
操作步骤如下：
如果您已在之前的 Edge 版本中部署了
升级控制器，请升级其 chart：helm upgrade upgrade-controller -n upgrade-controller-system oci://registry.suse.com/edge/charts/upgrade-controller --version 305.0.3+up0.1.3如果您尚未部署
升级控制器，请按照第 22.3 节 “安装升级控制器”中所述操作。
35.1.2.2 迁移步骤 #
使用升级控制器执行管理群集迁移本质上与执行升级类似。
唯一的区别是，UpgradePlan 必须指定 3.5.0 版本：
apiVersion: lifecycle.suse.com/v1alpha1
kind: UpgradePlan
metadata:
name: upgrade-plan-mgmt
# Change to the namespace of your Upgrade Controller
namespace: CHANGE_ME
spec:
releaseVersion: 3.5.0有关如何使用上述 UpgradePlan 进行迁移的信息，请参见升级控制器升级过程（第 36.1 节 “升级控制器”）。
35.1.3 Fleet #
使用 Fleet 执行管理群集迁移本质上与执行升级类似。
主要区别在于：
必须使用 release-3.5.0 版本
suse-edge/fleet-examples储存库中的 Fleet。安排升级的 chart 必须升级到与
Edge 3.5.0版本兼容的版本。有关Edge 3.5.0组件的列表，请参见第 53.3 节 “3.5.0 版本”。
为确保 Edge 3.5.0 迁移成功，用户必须遵守上述要点。
鉴于上述要点，用户可参考管理群集 Fleet（第 36.2 节 “Fleet”）文档，获取执行迁移需要完成的步骤的全面指南。
35.2 下游群集 #
第 35.2.1 节 “Fleet” - 如何使用第 8 章 “Fleet”执行下游群集迁移。
35.2.1 Fleet #
使用 Fleet 执行下游群集迁移本质上与执行升级类似。
主要区别在于：
必须使用 release-3.5.0 版本
suse-edge/fleet-examples储存库中的 Fleet。安排升级的 chart 必须升级到与
Edge 3.5.0版本兼容的版本。有关Edge 3.5.0组件的列表，请参见第 53.3 节 “3.5.0 版本”。
为确保 Edge 3.5.0 迁移成功，用户必须遵守上述要点。
鉴于上述要点，用户可参考下游群集 Fleet（第 37.1 节 “Fleet”）文档，获取执行迁移需要完成的步骤的全面指南。