35 Migração do Edge 3.5 #

Esta seção explica como migrar os clusters de gerenciamento e downstream do Edge 3.4 para o Edge 3.5.0.

Importante

Sempre faça as migrações de cluster da versão do Z-stream mais recente do Edge 3.4.

Migre sempre para a versão Edge 3.5.0. Para as próximas atualizações após a migração, consulte as seções de cluster de gerenciamento (Capítulo 36, Cluster de gerenciamento) e downstream (Capítulo 37, Clusters downstream).

A seguinte tabela lista os diversos tipos de clusters e os métodos para fazer upgrade dos clusters:

Tabela 35.1: Clusters e métodos para fazer upgrade de clusters downstream #

Tipo de cluster	Método
Clusters provisionados por EIB	Para obter detalhes, consulte a Seção 35.1.3, “Fleet”.
Clusters provisionados por Metal³	Para obter detalhes, consulte Upgrades de cluster downstream (Seção 44.3, “Upgrades de cluster downstream”).
Clusters provisionados por "phone home"	Consulte Fazendo upgrade da versão do Kubernetes (em inglês) para upgrade de versão do Kubernetes, e Clusters downstream (Capítulo 37, Clusters downstream) para SUC, sistema operacional e outros componentes.

35.1 Cluster de gerenciamento #

Esta seção aborda os seguintes tópicos:

Seção 35.1.1, “Pré-requisitos”: etapas de pré-requisito para concluir antes de iniciar a migração.

Seção 35.1.2, “Controller de upgrade”: como migrar um cluster de gerenciamento usando o Capítulo 22, Controller de upgrade.

Seção 35.1.3, “Fleet”: como migrar um cluster de gerenciamento usando o Capítulo 8, Fleet.

35.1.1 Pré-requisitos #

35.1.1.1 Fazer upgrade das CRDs do Bare Metal Operator #

Nota

Aplica-se apenas a clusters de gerenciamento CAPI/Metal3 que exigem upgrade de gráfico Capítulo 10, Metal³.

O gráfico Helm do Metal³ inclui as CRDs do Bare Metal Operator (BMO) aproveitando o diretório CRD do Helm.

Entretanto, essa abordagem tem algumas limitações, especificamente a incapacidade de fazer upgrade das CRDs nesse diretório usando o Helm. Para obter mais informações, consulte a documentação do Helm.

Como resultado, antes de fazer upgrade do Metal³ para uma versão compatível do Edge 3.5.0, os usuários devem fazer upgrade manual das CRDs subjacentes do BMO.

Em uma máquina com o Helm instalado e o kubectl configurado para apontar para o cluster de gerenciamento:

Aplique manualmente as CRDs do 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 Preparar-se para migração do SUSE Storage #

Sempre que fizer upgrade para o Edge 3.5.0, é necessário migrar do gráfico do Longhorn anterior para o gráfico do SUSE Storage mantido na SUSE Application Collection

Nota

Esse procedimento aplica-se apenas a clusters de gerenciamento que exigem upgrade de gráfico do Longhorn.

Você deve garantir que o cluster de gerenciamento primeiro seja atualizado para a versão do Z-stream 3.4 mais recente, que contém a versão necessária do SUSE Storage 1.9.2.

O gráfico do SUSE Storage não tem mais um gráfico Helm de CRDs separado, eles são incluídos em um único pacote. No entanto, é necessário seguir algumas etapas de migração adicionais conforme descrito na Documentação do SUSE Storage

Primeiro podemos ver a versão atual da CRD do Longhorn 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

Agora vamos clonar o repositório rancher/charts para a versão específica do Longhorn recém-instalada. Para isso, primeiro faça download deste script.
O script é executado desta maneira:
```
./download-longhorn-crd-chart.sh 107.1.1+up1.9.2
```
O download do gráfico longhorn-crd será feito no diretório local ./107.1.1+up1.9.2.

Após o download, verifique se a versão está correta abrindo o Chart.yaml e conferindo se appVersion é 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

Na sequência, vamos corrigir a anotação helm.sh/resource-policy para o valor keep no templates/crds.yaml no gráfico longhorn-crd que foi clonado. Esse procedimento garante que o Helm não exclua as CRDs quando a versão for desinstalada.

Para isso, faça download deste script para corrigir automaticamente a anotação:

./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 se as CRDs foram devidamente corrigidas, confira a diferença entre o gabarito original e o corrigido para garantir que o valor keep esteja definido em helm.sh/resource-policy:
```
vim -d /tmp/crds.yaml.original 107.1.1+up1.9.2/templates/crds.yaml
```
Em seguida, faça upgrade da versão Helm de longhorn-crd usando o gráfico localmente corrigido:
```
helm upgrade longhorn-crd -n longhorn-system ./107.1.1+up1.9.2
```

Agora desinstale a versão Helm de longhorn-crd do seu sistema. Por causa do patch aplicado, as CRDs permanecerão:

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

Garanta que o gráfico longhorn-crd tenha sido desinstalado executando novamente o mesmo comando de antes: helm list --all-namespaces | grep longhorn-crd para verificar se longhorn-crd não está presente.

Depois disso, você precisa atualizar os rótulos de propriedade nas CRDs existentes do Longhorn a fim de se preparar para o upgrade para o gráfico Helm do SUSE Storage.

Aplique este script para efetuar a substituição.

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

As credenciais de login no registro da Rancher Application Collection estão disponíveis na seção de tokens de acesso em suas configurações (o login deve ser feito).

Há também outras documentações referentes à Rancher Application Collection disponíveis aqui.

Após a preparação de todas as CRDs, faça login na Rancher Application Collection para que você possa extrair o gráfico Helm:
```
helm registry login dp.apps.rancher.io -u ${APPS.RANCHER.IO_USERNAME} -p ${APPS.RANCHER.IO_ACCESS_TOKEN}
```

Em seguida, crie um segredo docker-registry para que você possa extrair as imagens de contêiner:

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

Por fim, faça upgrade da instalação do Longhorn para o 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

Você pode fornecer um arquivo values.yaml anexando -f values.yaml ao comando de upgrade se desejado.

35.1.1.3 Preparar-se para o upgrade do Rancher Turtles #

Nota

Aplica-se apenas a clusters de gerenciamento CAPI/Metal3 que requerem upgrade de gráfico do Rancher Turtles.

Você deve garantir que o cluster de gerenciamento primeiro seja atualizado para a versão do Z-stream 3.4 mais recente, que contém a versão necessária do Rancher Turtles 0.24.3.

A partir do Rancher 2.13, o Rancher Turtles é instalado por padrão. No entanto, é necessário seguir algumas etapas de migração adicionais conforme descrito na Documentação do Rancher Turtles

Em primeiro lugar, removemos os recursos do CAPIProvider instalados:

kubectl delete capiprovider -A --all

Depois de esperar a conclusão da etapa acima, removeremos o gráfico rancher-turtles instalado e os rancher-turtles-airgap-resources (se instalados). Quando instalado pelo Edge Image Builder, é necessário remover os recursos de HelmChart correspondentes:

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

Em seguida, devemos corrigir os recursos de CRD conforme descrito na Documentação do 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"}]'

Agora siga as etapas comuns para fazer upgrade do cluster de gerenciamento para o Edge 3.5.0

35.1.1.4 Após o upgrade do Rancher Turtles #

Depois de seguir as etapas abaixo para fazer upgrade para o Edge 3.5.0, será necessário instalar o novo gráfico Helm rancher-turtles-providers, o que cria novos recursos de CAPIProvider para substituir aqueles que foram removidos nas etapas pré-upgrade acima.

Faça a instalação deste gráfico por meio do recurso HelmChart para habilitar o upgrade automatizado pelo Controller de upgrade:

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

Após alguns minutos, observe se há uma saída semelhante a esta:

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 Controller de upgrade #

Importante

O Controller de upgrade oferece suporte a migrações de versão do Edge somente para clusters de gerenciamento não air-gapped.

Os seguintes tópicos são abordados como parte desta seção:

Seção 35.1.2.1, “Pré-requisitos”: pré-requisitos específicos para o Controller de upgrade.

Seção 35.1.2.2, “Etapas de migração”: etapas para migrar o cluster de gerenciamento para uma nova versão do Edge usando o Controller de upgrade.

35.1.2.1 Pré-requisitos #

35.1.2.1.1 Controller de upgrade do Edge 3.5 #

Antes de usar o Controller de upgrade, verifique se ele executa uma versão com capacidade de migração para o lançamento desejado do Edge.

Para fazer isso:

Se você já tem o Controller de upgrade implantado de uma versão anterior do Edge, faça upgrade do respectivo gráfico:

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

Se você não tem o Controller de upgrade implantado, siga a Seção 22.3, “Instalando o Controller de upgrade”.

35.1.2.2 Etapas de migração #

A execução da migração de um cluster de gerenciamento com o Controller de upgrade é basicamente similar à execução de um upgrade.

A única diferença é que o UpgradePlan deve especificar a versão de lançamento 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 obter informações sobre como usar o UpgradePlan acima para fazer uma migração, consulte Processo de upgrade do Controller de upgrade (Seção 36.1, “Controller de upgrade”).

35.1.3 Fleet #

Nota

Sempre que possível, siga as instruções da Seção 35.1.2, “Controller de upgrade” para a migração.

Consulte esta seção apenas para casos de uso não cobertos pelo Controller de upgrade.

A execução da migração de um cluster de gerenciamento com o Fleet é basicamente similar a de um upgrade.

As principais diferenças são:

As instâncias do Fleet devem ser usadas a partir da versão release-3.5.0 do repositório suse-edge/fleet-examples.
O upgrade dos gráficos agendados deve ser feito para versões compatíveis com o Edge 3.5.0. Para ver a lista de componentes do Edge 3.5.0, consulte a Seção 53.3, “Versão 3.5.0”.

Importante

Para garantir a migração bem-sucedida do Edge 3.5.0, é importante que os usuários cumpram os pontos descritos acima.

Considerando os pontos acima, os usuários podem seguir a documentação do Fleet sobre cluster de gerenciamento (Seção 36.2, “Fleet”) para obter um guia completo das etapas necessárias à migração.

35.2 Clusters downstream #

Seção 35.2.1, “Fleet”: como migrar um cluster downstream usando o Capítulo 8, Fleet.

35.2.1 Fleet #

A execução da migração de um cluster downstream com o Fleet é basicamente similar a de um upgrade.

As principais diferenças são:

As instâncias do Fleet devem ser usadas a partir da versão release-3.5.0 do repositório suse-edge/fleet-examples.
O upgrade dos gráficos agendados deve ser feito para versões compatíveis com o Edge 3.5.0. Para ver a lista de componentes do Edge 3.5.0, consulte a Seção 53.3, “Versão 3.5.0”.

Importante

Para garantir a migração bem-sucedida do Edge 3.5.0, é importante que os usuários cumpram os pontos descritos acima.

Considerando os pontos acima, os usuários podem seguir a documentação do Fleet sobre cluster downstream (Seção 37.1, “Fleet”) para obter um guia completo das etapas necessárias à migração.