35 Migración a Edge 3.5 #

En esta sección se explica cómo migrar los clústeres de gestión y descendentes de Edge 3.4 a Edge 3.5.0.

Importante

Realice siempre las migraciones de clústeres desde la última versión z-stream de Edge 3.4.

Migre siempre a la versión Edge 3.5.0. Para actualizaciones posteriores a la migración, consulte las secciones sobre los clústeres de gestión (Capítulo 36, Clúster de gestión) y los clústeres descendentes (Capítulo 37, Clústeres descendentes).

En la tabla siguiente se muestran los diferentes tipos de clústeres y los métodos para actualizarlos:

Tabla 35.1: Clústeres y métodos para actualizar clústeres descendentes #

Tipo de clúster	Método
Clústeres aprovisionados por EIB	Consulte Sección 35.1.3, “Fleet” para obtener más información.
Clústeres aprovisionados por Metal³	Para obtener más información, consulte Actualización de clústeres descendentes (Sección 44.3, “Actualización de clústeres descendentes”).
Clústeres aprovisionados por sistema "phone home"	Consulte Actualización de la versión de Kubernetes para ver cómo se actualiza la versión de Kubernetes y los clústeres descendentes (Capítulo 37, Clústeres descendentes) para SUC, el sistema operativo y otros componentes.

35.1 Clúster de gestión #

En esta sección se tratan los temas siguientes:

Sección 35.1.1, “Requisitos previos”: pasos previos que deben completarse antes de iniciar la migración.

Sección 35.1.2, “Upgrade Controller”: cómo migrar un clúster de gestión con Capítulo 22, Upgrade Controller.

Sección 35.1.3, “Fleet”: cómo migrar un clúster de gestión con Capítulo 8, Fleet.

35.1.1 Requisitos previos #

35.1.1.1 Actualización de las CRD del operador bare metal #

Nota

Solo se aplica a clústeres de gestión CAPI/Metal3 que requieren que se actualice el chart de Capítulo 10, Metal³.

El chart de Helm de Metal³ incluye las CRD de Bare Metal Operator (BMO) obtenidas del directorio CRD de Helm.

Sin embargo, este enfoque tiene ciertas limitaciones, en particular la imposibilidad de actualizar las CRD de este directorio utilizando Helm. Para obtener más información, consulte la documentación de Helm.

Como resultado, antes de actualizar Metal³ a una versión compatible de Edge 3.5.0, los usuarios deben actualizar manualmente las CRD de BMO subyacentes.

En un equipo con Helm instalado y kubectl configurado que apunte al clúster de gestión:

Aplique manualmente las CRD de BMO:

helm show crds oci://registry.suse.com/edge/charts/metal3 --version 305.0.21+up0.13.0 | kubectl apply -f -

35.1.1.2 Preparación de la migración de SUSE Storage #

Al actualizar a Edge 3.5.0, es necesario migrar del chart de Longhorn anterior al chart de SUSE Storage que se mantiene en la colección de aplicaciones de SUSE.

Nota

Este procedimiento solo se aplica a los clústeres de gestión que requieren una actualización del chart de Longhorn.

Debe asegurarse de que el clúster de gestión se actualiza primero a la última versión z-stream de Edge 3.4, que contiene la versión 1.9.2 necesaria de SUSE Storage.

El chart de SUSE Storage ya no tiene un chart de Helm de CRD independiente, sino que se han agrupado en uno solo, por lo que es necesario seguir algunos pasos de migración adicionales, tal y como se describe en la documentación de SUSE Storage

En primer lugar, comprobamos si la versión actual de las CRD de Longhorn está instalada.

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

Luego se clona el repositorio de rancher/charts para la versión específica de Longhorn que tenemos instalada. Para ello, primero debe descargar este guion.
El guion se ejecuta así:
```
./download-longhorn-crd-chart.sh 107.1.1+up1.9.2
```
Ahora, el chart longhorn-crd se descargará en el directorio local ./107.1.1+up1.9.2.

Cuando se descargue, asegúrese de que se trata de la versión correcta abriendo Chart.yaml y verificando que el valor de appVersion sea v1.9.2:

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

A continuación, debemos aplicar a la anotación helm.sh/resource-policy el parche con el valor keep en el archivo templates/crds.yaml del chart longhorn-crd que se ha clonado. De esta forma, nos aseguramos de que Helm no elimine las CRD cuando la versión se desinstale.

Para ello, descargue este guion para aplicar el parche automáticamente a la anotación:

./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

Para verificar que se han aplicado los parches correctamente a las CRD, compruebe las diferencias entre la plantilla original y la que se ha parcheado para asegurarse de que el valor keep se ha definido en helm.sh/resource-policy:
```
vim -d /tmp/crds.yaml.original 107.1.1+up1.9.2/templates/crds.yaml
```
Después, actualice la versión de Helm de longhorn-crd con el chart parcheado localmente:
```
helm upgrade longhorn-crd -n longhorn-system ./107.1.1+up1.9.2
```

Ahora, desinstale la versión de Helm de longhorn-crd del sistema. Dado que se ha aplicado el parche, se conservarán las 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

Asegúrese de que el chart longhorn-crd se ha desinstalado volviendo a ejecutar el mismo comando que antes: helm list --all-namespaces | grep longhorn-crd para comprobar que longhorn-crd no está presente.
Seguidamente, debe actualizar las etiquetas de propiedad en las CRD de Longhorn existentes para preparar la actualización al chart de Helm de SUSE Storage.
Aplique este guion para realizar la sustitución.
```
./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
```
Nota
Las credenciales de inicio de sesión para el registro de la colección de aplicaciones de Rancher se pueden encontrar en la sección de tokens de acceso de su configuración (debe tener la sesión iniciada).
También hay documentación adicional sobre la colección de aplicaciones de Rancher aquí.
Una vez preparadas todas las CRD, inicie sesión en la colección de aplicaciones de Rancher para poder extraer el chart de Helm:
```
helm registry login dp.apps.rancher.io -u ${APPS.RANCHER.IO_USERNAME} -p ${APPS.RANCHER.IO_ACCESS_TOKEN}
```

Luego, cree un secreto de registro de docker para poder extraer las imágenes de contenedor:

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}"

Para terminar, actualice su instalación de Longhorn a 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

Si lo desea, puede proporcionar un archivo values.yaml anexando -f values.yaml al comando de actualización.

35.1.1.3 Preparación de la actualización de Rancher Turtles #

Nota

Solo se aplica a los clústeres de gestión CAPI/Metal3 que requieren una actualización del chart de Rancher Turtles.

Debe asegurarse de que el clúster de gestión se actualiza primero a la última versión z-stream de Edge 3.4, que contiene la versión 0.24.3 necesaria de Rancher Turtles.

A partir de Rancher 2.13, Rancher Turtles se instala por defecto, por lo que es necesario seguir algunos pasos adicionales para la migración, como se describe en la documentación de Rancher Turtles.

Primero, se eliminan los recursos CAPIProvider instalados:

kubectl delete capiprovider -A --all

Cuando se complete el paso anterior, se elimina el chart de rancher-turtles instalado y los recursos rancher-turtles-airgap-resources (si los hubiera). Si se instala mediante Edge Image Builder, es necesario eliminar los recursos HelmChart correspondientes:

kubectl delete -n kube-system helmchart rancher-turtles
kubectl delete -n kube-system helmchart rancher-turtles-airgap-resources

A continuación, se deben aplicar parches a los recursos de CRD, como se describe en la documentación de Rancher Turtles.

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"}]'

Ahora, se siguen los pasos habituales para actualizar el clúster de gestión a Edge 3.5.0.

35.1.1.4 Pasos posteriores a la actualización de Rancher Turtles #

Después de seguir los pasos siguientes para actualizar a Edge 3.5.0, es necesario instalar el nuevo chart de Helm rancher-turtles-providers. De esta forma, se crean recursos CAPIProvider nuevos para sustituir a las que se han eliminado en los pasos anteriores a la actualización.

Esta instalación de chart se debe realizar mediante un recurso HelmChart a fin de habilitar la actualización futura automatizada mediante Upgrade Controller:

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

Tras unos minutos, se observará un resultado similar al siguiente:

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            Ready

35.1.2 Upgrade Controller #

Importante

Upgrade Controller actualmente solo admite migraciones de versiones de Edge para clústeres de gestión que no estén en entornos aislados.

En esta sección se tratan los siguientes temas:

Sección 35.1.2.1, “Requisitos previos”: requisitos previos específicos de Upgrade Controller.

Sección 35.1.2.2, “Pasos de la migración”: pasos para migrar un clúster de gestión a una versión nueva de Edge mediante Upgrade Controller.

35.1.2.1 Requisitos previos #

35.1.2.1.1 Upgrade Controller de Edge 3.5 #

Antes de usar Upgrade Controller, debe asegurarse de que está ejecutando una versión que sea compatible con la migración a la versión de Edge deseada.

Para ello:

Si ya ha desplegado Upgrade Controller desde una versión anterior de Edge, actualice su chart:

helm upgrade upgrade-controller -n upgrade-controller-system oci://registry.suse.com/edge/charts/upgrade-controller --version 305.0.3+up0.1.3

Si no ha desplegado Upgrade Controller, siga la Sección 22.3, “Instalación de Upgrade Controller”.

35.1.2.2 Pasos de la migración #

Migrar un clúster de gestión con Upgrade Controller es básicamente igual a ejecutar una actualización.

La única diferencia es que su recurso UpgradePlan debe especificar la versión 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

Para obtener información sobre cómo usar el recurso UpgradePlan mencionado para realizar una migración, consulte el proceso de actualización de Upgrade Controller (Sección 36.1, “Upgrade Controller”).

35.1.3 Fleet #

Nota

Siempre que sea posible, use las instrucciones de la Sección 35.1.2, “Upgrade Controller” para la migración.

Consulte esta sección solo para los casos no cubiertos por la migración con Upgrade Controller.

Migrar un clúster de gestión con Fleet es básicamente igual a ejecutar una actualización.

Estas son las diferencias principales:

Fleet se debe usar desde la versión release-3.5.0 del repositorio suse-edge/fleet-examples.
Los charts cuya actualización esté programada, deben actualizarse a versiones compatibles con la versión Edge 3.5.0. Para ver una lista de los componentes de Edge 3.5.0, consulte la Sección 53.3, “Versión 3.5.0”.

Importante

Para garantizar que la migración a Edge 3.5.0 se realice correctamente, es importante que los usuarios cumplan con los puntos descritos anteriormente.

Teniendo en cuenta los puntos anteriores, los usuarios pueden seguir la documentación de Fleet (Sección 36.2, “Fleet”) sobre el clúster de gestión, que incluye todos los pasos necesarios para realizar la migración.

35.2 Clústeres descendentes #

Sección 35.2.1, “Fleet”: cómo migrar un clúster descendente con Capítulo 8, Fleet.

35.2.1 Fleet #

Migrar un clúster descendente con Fleet es básicamente igual a ejecutar una actualización.

Estas son las diferencias principales:

Fleet se debe usar desde la versión release-3.5.0 del repositorio suse-edge/fleet-examples.
Los charts cuya actualización esté programada, deben actualizarse a versiones compatibles con la versión Edge 3.5.0. Para ver una lista de los componentes de Edge 3.5.0, consulte la Sección 53.3, “Versión 3.5.0”.

Importante

Para garantizar que la migración a Edge 3.5.0 se realice correctamente, es importante que los usuarios cumplan con los puntos descritos anteriormente.

Teniendo en cuenta los puntos anteriores, los usuarios pueden seguir la documentación de Fleet (Sección 37.1, “Fleet”) sobre los clústeres descendentes para obtener una guía completa sobre los pasos necesarios para realizar la migración.