35 Cluster de gerenciamento #

Atualmente, há duas maneiras de realizar as operações de "dia 2" no cluster de gerenciamento:

Usando o Capítulo 23, Controller de upgrade: Seção 35.1, “Controller de upgrade”
Usando o Capítulo 8, Fleet: Seção 35.2, “Fleet”

35.1 Controller de upgrade #

Importante

O Controller de upgrade oferece suporte apenas a operações de dia 2 em clusters de gerenciamento não air-gapped.

Esta seção explica como realizar as diversas operações de dia 2 relacionadas ao upgrade do cluster de gerenciamento de uma versão da plataforma Edge para outra.

O Controller de upgrade (Capítulo 23, Controller de upgrade) automatiza as operações de dia 2, o que inclui:

Upgrade de sistema operacional SUSE Linux Micro (Capítulo 9, SUSE Linux Micro)
Upgrade de Kubernetes com Capítulo 16, RKE2 ou Capítulo 15, K3s
Upgrade de componentes adicionais do SUSE (SUSE Rancher Prime, SUSE Security etc.)

35.1.1 Pré-requisitos #

Antes de fazer upgrade do cluster de gerenciamento, é necessário cumprir os seguintes pré-requisitos:

Nós registrados do SCC: assegure que os nós do cluster do seu sistema operacional sejam registrados com uma chave de assinatura compatível com a versão de sistema operacional especificada no lançamento do Edge (Seção 52.1, “Resumo”) para o qual você pretende fazer upgrade.
Controller de upgrade: garanta que o Controller de upgrade tenha sido implantado no cluster de gerenciamento. Para ver as etapas de instalação, consulte a Seção 23.3, “Instalando o Controller de upgrade”.

35.1.2 Fazer upgrade #

Determine a versão de lançamento do Edge (Seção 52.1, “Resumo”) para a qual você quer fazer upgrade do seu cluster de gerenciamento.
No cluster de gerenciamento, implante um UpgradePlan que especifique a versão de lançamento desejada. É necessário implantar o UpgradePlan no namespace do Controller de upgrade.
```
kubectl apply -n <upgrade_controller_namespace> -f - <<EOF
apiVersion: lifecycle.suse.com/v1alpha1
kind: UpgradePlan
metadata:
  name: upgrade-plan-mgmt
spec:
  # Version retrieved from release notes
  releaseVersion: 3.X.Y
EOF
```
Nota
Em alguns casos de uso, talvez você queira fazer configurações adicionais no UpgradePlan. Para saber todas as configurações possíveis, consulte a Seção 23.5.1, “UpgradePlan”.
A implantação do UpgradePlan no namespace do Controller de upgrade inicia o processo de upgrade.
Nota
Para obter mais informações sobre o processo de upgrade real, consulte a Seção 23.4, “Como funciona o Controller de upgrade?”.
Para obter informações sobre como acompanhar o processo de upgrade, consulte a Seção 23.6, “Acompanhando o processo de upgrade”.

35.2 Fleet #

Esta seção apresenta informações sobre como executar operações de "dia 2" usando o componente Fleet (Capítulo 8, Fleet).

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

Seção 35.2.1, “Componentes”: componentes padrão usados para todas as operações de "dia 2".
Seção 35.2.2, “Determinar seu caso de uso”: apresenta uma visão geral dos recursos personalizados do Fleet que serão usados e como se adaptam aos diferentes casos de uso das operações de "dia 2".
Seção 35.2.3, “Fluxo de trabalho de dia 2”: fornece um guia de fluxo de trabalho para execução de operações de "dia 2" com o Fleet.
Seção 35.2.4, “Upgrade de sistema operacional”: descreve como fazer upgrades de sistema operacional com o Fleet.
Seção 35.2.5, “Upgrade da versão do Kubernetes”: descreve como fazer upgrades de versão do Kubernetes com o Fleet.
Seção 35.2.6, “Upgrade do gráfico Helm”: descreve como fazer upgrades de gráficos Helm com o Fleet.

35.2.1 Componentes #

Veja a seguir uma descrição dos componentes padrão que você deve configurar no cluster de gerenciamento para realizar operações de "dia 2" com sucesso pelo Fleet.

35.2.1.1 Rancher #

(Opcional) Responsável por gerenciar os clusters downstream e implantar o System Upgrade Controller no cluster de gerenciamento.

Para obter mais informações, consulte o Capítulo 5, Rancher.

35.2.1.2 System Upgrade Controller (SUC) #

System Upgrade Controller é responsável por executar tarefas em nós especificados com base nos dados de configuração fornecidos por um recurso personalizado chamado plano.

O SUC é ativamente usado para fazer upgrade do sistema operacional e da distribuição Kubernetes.

Para obter mais informações sobre o componente SUC e como ele se adapta à pilha do Edge, consulte o Capítulo 22, System Upgrade Controller.

35.2.2 Determinar seu caso de uso #

O Fleet usa dois tipos de recursos personalizados para permitir o gerenciamento de recursos do Kubernetes e do Helm.

Veja a seguir as informações sobre a finalidade desses recursos e para quais casos de uso eles são mais adequados no contexto das operações de "dia 2".

35.2.2.1 GitRepo #

O GitRepo é um recurso do Fleet (Capítulo 8, Fleet) que representa um repositório Git do qual o Fleet pode criar Bundles. Cada Bundle é criado com base nos caminhos de configuração definidos no recurso GitRepo. Para obter mais informações, consulte a documentação do GitRepo.

No contexto das operações de "dia 2", os recursos GitRepo costumam ser usados para implantar o SUC ou os planos do SUC em ambientes não air-gapped que usam a abordagem GitOps do Fleet.

Se preferir, use os recursos GitRepo para implantar o SUC ou os planos do SUC em ambientes air-gapped, desde que você espelhe a configuração do seu repositório por um servidor Git local.

35.2.2.2 Bundle #

Os Bundles armazenam recursos brutos do Kubernetes que serão implantados no cluster de destino. Normalmente, eles são criados de um recurso GitRepo, mas há casos de uso em que podem ser implantados manualmente. Para obter mais informações, consulte a documentação do Bundle.

No contexto das operações de "dia 2", os recursos Bundle costumam ser usados para implantar o SUC ou planos do SUC em ambientes air-gapped que não usam nenhuma forma de procedimento do GitOps local (por exemplo, um servidor git local).

Se o seu caso de uso não possibilita um fluxo de trabalho GitOps (por exemplo, usando um repositório Git), a alternativa é usar os recursos Bundle para implantar o SUC ou os planos do SUC em ambientes não air-gapped.

35.2.3 Fluxo de trabalho de dia 2 #

Veja a seguir um fluxo de trabalho de "dia 2" que deve ser seguido para fazer upgrade de um cluster de gerenciamento para uma versão específica do Edge.

Upgrade de sistema operacional (Seção 35.2.4, “Upgrade de sistema operacional”)
Upgrade de versão do Kubernetes (Seção 35.2.5, “Upgrade da versão do Kubernetes”)
Upgrade de gráfico Helm (Seção 35.2.6, “Upgrade do gráfico Helm”)

35.2.4 Upgrade de sistema operacional #

Esta seção descreve como fazer upgrade de um sistema operacional usando o Capítulo 8, Fleet e o Capítulo 22, System Upgrade Controller.

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

Seção 35.2.4.1, “Componentes”: componentes adicionais usados pelo processo de upgrade.
Seção 35.2.4.2, “Visão geral”: visão geral do processo de upgrade.
Seção 35.2.4.3, “Requisitos”: requisitos do processo de upgrade.
Seção 35.2.4.4, “Upgrade de sistema operacional: implantação do plano do SUC”: informações de como implantar os planos do SUC, responsáveis por acionar o processo de upgrade.

35.2.4.1 Componentes #

Esta seção aborda os componentes personalizados que o processo de upgrade de sistema operacional usa com os componentes de "dia 2" padrão (Seção 35.2.1, “Componentes”).

35.2.4.1.1 systemd.service #

O upgrade de sistema operacional em um nó específico é executado pelo systemd.service.

É criado um serviço diferente dependendo do tipo de upgrade que o sistema operacional requer de uma versão do Edge para outra:

Para versões do Edge que requerem a mesma versão de sistema operacional (por exemplo, 6.0), o os-pkg-update.service é criado. Ele usa o transactional-update para fazer upgrade de um pacote normal.
Para versões do Edge que requerem a migração da versão de sistema operacional (por exemplo, 6.0 → 6.1), o os-migration.service é criado. Ele usa o transactional-update para fazer o seguinte:
1. O upgrade de pacote normal, que garante que todos os pacotes sejam atualizados para mitigar falhas na migração relacionadas a versões antigas dos pacotes.
2. A migração de sistema operacional usando o comando zypper migration.

Os serviços mencionados acima são distribuídos para cada nó por meio de um plano do SUC, que deve estar localizado no cluster de gerenciamento que precisa do upgrade de sistema operacional.

35.2.4.2 Visão geral #

O upgrade do sistema operacional para nós de cluster de gerenciamento é feito pelo Fleet e pelo System Upgrade Controller (SUC).

O Fleet é usado para implantar e gerenciar os planos do SUC no cluster desejado.

Nota

Os planos do SUC são recursos personalizados que descrevem as etapas que o SUC precisa seguir para execução de uma tarefa específica em um conjunto de nós. Para ver um exemplo de como é um plano do SUC, consulte o repositório upstream.

Os planos do SUC de sistema operacional são enviados a cada cluster por meio da implantação de um recurso GitRepo ou Bundle em um espaço de trabalho do Fleet específico. O Fleet recupera o GitRepo/Bundle implantado e implanta seu conteúdo (os planos do SUC de sistema operacional) no(s) cluster(s) desejado(s).

Nota

Os recursos GitRepo/Bundle sempre são implantados no cluster de gerenciamento. O uso do recurso GitRepo ou Bundle depende do seu caso de uso. Consulte a Seção 35.2.2, “Determinar seu caso de uso” para obter mais informações.

Os planos do SUC de sistema operacional descrevem o seguinte fluxo de trabalho:

Sempre use o comando cordon nos nós antes dos upgrades de sistema operacional.
Sempre faça upgrade dos nós do plano de controle antes dos nós do worker.
Sempre faça upgrade do cluster um nó de cada vez.

Depois que os planos do SUC de sistema operacional forem implantados, o fluxo de trabalho terá esta aparência:

O SUC reconcilia os planos do SUC de sistema operacional implantados e cria um Kubernetes Job em cada nó.
O Kubernetes Job cria um systemd.service (Seção 35.2.4.1.1, “systemd.service”) para upgrade de pacote ou migração de sistema operacional.
O systemd.service criado aciona o processo de upgrade de sistema operacional no nó específico.
Importante
Após o término do processo de upgrade do sistema operacional, o nó correspondente será reinicializado para aplicar as atualizações ao sistema.

Veja a seguir um diagrama da descrição acima:

35.2.4.3 Requisitos #

Geral:

Máquina registrada no SCC: todos os nós do cluster de gerenciamento devem ser registrados no https://scc.suse.com/ para que o respectivo systemd.service possa se conectar com sucesso ao repositório RPM desejado.
Importante
Para lançamentos do Edge que exigem a migração da versão do sistema operacional (por exemplo, 6.0 → 6.1), verifique se a chave do SCC oferece suporte à migração para a nova versão.
Garantir que as tolerâncias do plano do SUC correspondam às do nó: se os nós do cluster Kubernetes têm taints personalizados, adicione tolerâncias a esses taints nos planos do SUC. Por padrão, os planos do SUC têm tolerâncias apenas para nós do plano de controle. As tolerâncias padrão incluem:
- CriticalAddonsOnly=true:NoExecute
- node-role.kubernetes.io/control-plane:NoSchedule
- node-role.kubernetes.io/etcd:NoExecute
  Nota
  As tolerâncias adicionais devem ser incluídas na seção .spec.tolerations de cada plano. Os planos do SUC relacionados a upgrade de sistema operacional estão disponíveis no repositório suse-edge/fleet-examples em fleets/day2/system-upgrade-controller-plans/os-upgrade. Use os planos de uma tag de versão válida do repositório.
  Um exemplo de definição de tolerâncias personalizadas para o plano do SUC de plano de controle tem esta aparência:
  apiVersion: upgrade.cattle.io/v1 kind: Plan metadata: name: os-upgrade-control-plane spec: ... tolerations: # default tolerations - key: "CriticalAddonsOnly" operator: "Equal" value: "true" effect: "NoExecute" - key: "node-role.kubernetes.io/control-plane" operator: "Equal" effect: "NoSchedule" - key: "node-role.kubernetes.io/etcd" operator: "Equal" effect: "NoExecute" # custom toleration - key: "foo" operator: "Equal" value: "bar" effect: "NoSchedule" ...

Air-gapped:

Espelhar repositórios RPM do SUSE: os repositórios RPM de sistema operacional devem ser espelhados localmente para que o systemd.service tenha acesso a eles. Para isso, use RMT ou SUMA.

35.2.4.4 Upgrade de sistema operacional: implantação do plano do SUC #

Importante

Em ambientes que já passaram por upgrade usando esse procedimento, os usuários devem garantir que uma das seguintes etapas seja concluída:

Remover os planos do SUC que já foram implantados relacionados a versões de lançamento mais antigas do Edge do cluster de gerenciamento: para fazer isso, remova o cluster desejado da configuração de destino do GitRepo/Bundle, ou remova o recurso GitRepo/Bundle completamente.
Reutilizar o recurso GitRepo/Bundle existente: para fazer isso, aponte a revisão do recurso para uma nova tag que inclua as instâncias do Fleet corretas para a versão desejada de suse-edge/fleet-examples.

Isso é feito para evitar conflitos entre os planos do SUC de versões de lançamento mais antigas do Edge.

Se os usuários tentarem fazer upgrade e já houver planos do SUC no cluster de gerenciamento, eles verão o seguinte erro no Fleet:

Not installed: Unable to continue with install: Plan <plan_name> in namespace <plan_namespace> exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error..

Conforme mencionado na Seção 35.2.4.2, “Visão geral”, os upgrades de sistema operacional são feitos enviando os planos do SUC ao cluster desejado de uma destas maneiras:

Recurso GitRepo do Fleet: Seção 35.2.4.4.1, “Implantação do plano do SUC: recurso GitRepo”.
Recurso Bundle do Fleet: Seção 35.2.4.4.2, “Implantação do plano do SUC – recurso Bundle”.

Para determinar o recurso que você deve usar, consulte a Seção 35.2.2, “Determinar seu caso de uso”.

Para casos de uso de implantação dos planos do SUC de sistema operacional de uma ferramenta GitOps de terceiros, consulte a Seção 35.2.4.4.3, “Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros”.

35.2.4.4.1 Implantação do plano do SUC: recurso GitRepo #

Um recurso GitRepo, que distribui os planos do SUC de sistema operacional necessários, pode ser implantado de uma das seguintes maneiras:

Pela IU do Rancher: Seção 35.2.4.4.1.1, “Criação do GitRepo: IU do Rancher” (quando o Rancher está disponível).
Pela implantação manual do recurso (Seção 35.2.4.4.1.2, “Criação do GitRepo: manual”) em seu cluster de gerenciamento.

Após a implantação, para monitorar o processo de upgrade do sistema operacional dos nós do cluster de destino, consulte a Seção 22.3, “Monitorando os planos do System Upgrade Controller”.

35.2.4.4.1.1 Criação do GitRepo: IU do Rancher #

Para criar um recurso GitRepo pela IU do Rancher, siga a documentação oficial dele.

A equipe do Edge mantém uma instância do Fleet pronta para uso. Dependendo do seu ambiente, ela pode ser usada diretamente ou como gabarito.

Importante

Use sempre essa instância do Fleet de uma tag de versão válida do Edge.

Para casos de uso em que não há necessidade de incluir alterações personalizadas nos planos do SUC que a instância do Fleet envia, os usuários podem fazer referência à instância do Fleet de os-upgrade do repositório suse-edge/fleet-examples.

Nos casos em que as alterações personalizadas são necessárias (por exemplo, para adicionar tolerâncias personalizadas), os usuários devem fazer referência à instância do Fleet de os-upgrade de um repositório separado, para que possam adicioná-las aos planos do SUC conforme necessário.

Há um exemplo de como configurar o GitRepo para usar a instância do Fleet de um repositório suse-edge/fleet-examples disponível aqui.

35.2.4.4.1.2 Criação do GitRepo: manual #

Obtenha o recurso GitRepo:

curl -o os-upgrade-gitrepo.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/gitrepos/day2/os-upgrade-gitrepo.yaml

Edite a configuração do GitRepo:

Remova a seção spec.targets (necessário apenas para clusters downstream).

# Example using sed
sed -i.bak '/^  targets:/,$d' os-upgrade-gitrepo.yaml && rm -f os-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval 'del(.spec.targets)' -i os-upgrade-gitrepo.yaml

Aponte o namespace do GitRepo para o namespace fleet-local, feito para implantar o recurso no cluster de gerenciamento.

# Example using sed
sed -i.bak 's/namespace: fleet-default/namespace: fleet-local/' os-upgrade-gitrepo.yaml && rm -f os-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval '.metadata.namespace = "fleet-local"' -i os-upgrade-gitrepo.yaml

Aplique o recurso GitRepo ao cluster de gerenciamento:
```
kubectl apply -f os-upgrade-gitrepo.yaml
```

Visualize o recurso GitRepo criado no namespace fleet-local:

kubectl get gitrepo os-upgrade -n fleet-local

# Example output
NAME            REPO                                              COMMIT         BUNDLEDEPLOYMENTS-READY   STATUS
os-upgrade      https://github.com/suse-edge/fleet-examples.git   release-3.3.0  0/0

35.2.4.4.2 Implantação do plano do SUC – recurso Bundle #

O recurso Bundle, que envia os planos do SUC de sistema operacional necessários, pode ser implantado de uma das seguintes maneiras:

Pela IU do Rancher : Seção 35.2.4.4.2.1, “Criação do bundle – IU do Rancher” (quando o Rancher está disponível).
Por meio da implantação manual do recurso (Seção 35.2.4.4.2.2, “Criação do bundle – manual”) no cluster de gerenciamento.

Após a implantação, para monitorar o processo de upgrade do sistema operacional dos nós do cluster de destino, consulte a Seção 22.3, “Monitorando os planos do System Upgrade Controller”.

35.2.4.4.2.1 Criação do bundle – IU do Rancher #

A equipe do Edge mantém um bundle pronto para uso que pode ser usado nas etapas a seguir.

Importante

Sempre use esse bundle de uma tag de versão válida do Edge.

Para criar um bundle pela IU do Rancher:

No canto superior esquerdo, clique em ☰ → Continuous Delivery (Entrega contínua).
Vá para Advanced > Bundles (Avançado > Bundles).
Selecione Create from YAML (Criar do YAML).
Nesse local, você pode criar o bundle de uma das seguintes maneiras:
Nota
Há casos de uso em que você precisa incluir alterações personalizadas nos planos do SUC que o bundle envia (por exemplo, para adicionar tolerâncias personalizadas). Inclua essas alterações no bundle que será gerado pelas etapas a seguir.
1. Copie manualmente o conteúdo do bundle de suse-edge/fleet-examples para a página Create from YAML (Criar do YAML).
2. Clone o repositório suse-edge/fleet-examples da tag da versão desejada e selecione a opção Read from File (Ler arquivo) na página Create from YAML (Criar do YAML). Dessa página, navegue até o local do bundle (bundles/day2/system-upgrade-controller-plans/os-upgrade) e selecione o arquivo do bundle. Esse procedimento preencherá automaticamente a página Create from YAML (Criar do YAML) com o conteúdo do bundle.
Edite o bundle na IU do Rancher:
- Altere o namespace do Bundle para apontar para o namespace fleet-local.
```
# Example
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: os-upgrade
  namespace: fleet-local
...
```
- Altere os clusters de destino para que o Bundle aponte para o seu cluster local (gerenciamento):
```
spec:
  targets:
  - clusterName: local
```
  Nota
  Em alguns casos de uso, o cluster local pode ter um nome diferente.
  Para recuperar o nome do cluster local, execute o comando abaixo:
  kubectl get clusters.fleet.cattle.io -n fleet-local
Selecione Create (Criar).

35.2.4.4.2.2 Criação do bundle – manual #

Obtenha o recurso Bundle:

curl -o os-upgrade-bundle.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/bundles/day2/system-upgrade-controller-plans/os-upgrade/os-upgrade-bundle.yaml

Edite a configuração do Bundle:
- Altere os clusters de destino para que o Bundle aponte para o seu cluster local (gerenciamento):
```
spec:
  targets:
  - clusterName: local
```
  Nota
  Em alguns casos de uso, o cluster local pode ter um nome diferente.
  Para recuperar o nome do cluster local, execute o comando abaixo:
  kubectl get clusters.fleet.cattle.io -n fleet-local
- Altere o namespace do Bundle para apontar para o namespace fleet-local.
```
# Example
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: os-upgrade
  namespace: fleet-local
...
```
Aplique o recurso Bundle ao seu cluster de gerenciamento:
```
kubectl apply -f os-upgrade-bundle.yaml
```
Visualize o recurso Bundle criado no namespace fleet-local:
```
kubectl get bundles -n fleet-local
```

35.2.4.4.3 Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros #

Em alguns casos de uso, talvez você queira incorporar os planos do SUC de sistema operacional ao fluxo de trabalho do GitOps de terceiros (por exemplo, o Flux).

Para obter os recursos de upgrade de sistema operacional que você precisa, primeiro determine a tag da versão do Edge do repositório suse-edge/fleet-examples que deseja usar.

Depois disso, os recursos estarão disponíveis em fleets/day2/system-upgrade-controller-plans/os-upgrade, em que:

plan-control-plane.yaml é um recurso do plano do SUC para nós do plano de controle.
plan-worker.yaml é um recurso do plano do SUC para nós do worker.
secret.yaml é um segredo que contém o script upgrade.sh, responsável por criar o systemd.service (Seção 35.2.4.1.1, “systemd.service”).
config-map.yaml é um ConfigMap que armazena as configurações consumidas pelo script upgrade.sh.

Importante

Esses recursos do plano são interpretados pelo System Upgrade Controller e devem ser implantados em cada cluster downstream do qual você deseja fazer upgrade. Para obter informações sobre a implantação do SUC, consulte a Seção 22.2, “Instalando o System Upgrade Controller”.

Para entender melhor como usar o fluxo de trabalho do GitOps para implantar os planos do SUC para upgrade de sistema operacional, consulte a visão geral (Seção 35.2.4.2, “Visão geral”).

35.2.5 Upgrade da versão do Kubernetes #

Esta seção descreve como fazer um upgrade do Kubernetes usando o Capítulo 8, Fleet e o Capítulo 22, System Upgrade Controller.

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

Seção 35.2.5.1, “Componentes”: componentes adicionais usados pelo processo de upgrade.
Seção 35.2.5.2, “Visão geral”: visão geral do processo de upgrade.
Seção 35.2.5.3, “Requisitos”: requisitos do processo de upgrade.
Seção 35.2.5.4, “Upgrade do K8s: implantação do plano do SUC”: informações de como implantar os planos do SUC, responsáveis por acionar o processo de upgrade.

35.2.5.1 Componentes #

Esta seção aborda os componentes personalizados que o processo de upgrade do K8s usa com os componentes de "dia 2" padrão (Seção 35.2.1, “Componentes”).

35.2.5.1.1 rke2-upgrade #

Imagem do contêiner responsável por fazer upgrade da versão do RKE2 de um nó específico.

Incluída em um pod criado pelo SUC com base no plano do SUC. O plano deve estar localizado em cada cluster que precisa de upgrade do RKE2.

Para obter mais informações sobre como a imagem rke2-upgrade faz o upgrade, consulte a documentação upstream.

35.2.5.1.2 k3s-upgrade #

Imagem do contêiner responsável por fazer upgrade da versão do K3s de um nó específico.

Incluída em um pod criado pelo SUC com base no plano do SUC. O plano deve estar localizado em cada cluster que precisa de upgrade do K3s.

Para obter mais informações sobre como a imagem k3s-upgrade faz o upgrade, consulte a documentação upstream.

35.2.5.2 Visão geral #

O upgrade de distribuições Kubernetes para nós de cluster de gerenciamento é feito pelo Fleet e pelo System Upgrade Controller (SUC).

O Fleet é usado para implantar e gerenciar planos do SUC no cluster desejado.

Nota

Os planos do SUC são recursos personalizados que descrevem as etapas que o SUC precisa seguir para execução de uma tarefa específica em um conjunto de nós. Para ver um exemplo de como é um plano do SUC, consulte o repositório upstream.

Os planos do SUC do K8s são enviados a cada cluster por meio da implantação de um recurso GitRepo ou Bundle em um espaço de trabalho do Fleet específico. O Fleet recupera o GitRepo/Bundle implantado e implanta seu conteúdo (os planos do SUC do K8s) no(s) cluster(s) desejado(s).

Nota

Os planos do SUC do K8s descrevem o seguinte fluxo de trabalho:

Sempre use o comando cordon nos nós antes dos upgrades do K8s.
Sempre faça upgrade dos nós do plano de controle antes dos nós do worker.
Sempre faça upgrade dos nós do plano de controle um de cada vez, e dos nós do worker dois nós de cada vez.

Depois que os planos do SUC do K8s forem implantados, o fluxo de trabalho terá esta aparência:

O SUC reconcilia os planos do SUC do K8s implantados e cria um Kubernetes Job em cada nó.
Dependendo da distribuição Kubernetes, o job cria um pod que executa a imagem de contêiner do rke2-upgrade (Seção 35.2.5.1.1, “rke2-upgrade”) ou do k3s-upgrade (Seção 35.2.5.1.2, “k3s-upgrade”).
O pod criado vai percorrer o seguinte fluxo de trabalho:
1. Substitua o binário rke2/k3s existente no nó pelo da imagem rke2-upgrade/k3s-upgrade.
2. Cancele o processo do rke2/k3s em execução.
O cancelamento do processo do rke2/k3s aciona a reinicialização, o que inicia um novo processo que executa o binário atualizado, resultando em uma versão atualizada da distribuição Kubernetes.

Veja a seguir um diagrama da descrição acima:

35.2.5.3 Requisitos #

Faça backup da distribuição Kubernetes:
1. Para clusters RKE2, consulte a documentação sobre backup e restauração do RKE2.
2. Para clusters K3s, consulte a documentação sobre backup e restauração do K3s.
Garantir que as tolerâncias do plano do SUC correspondam às do nó: se os nós do cluster Kubernetes têm taints personalizados, adicione tolerâncias a esses taints nos planos do SUC. Por padrão, os planos do SUC têm tolerâncias apenas para nós do plano de controle. As tolerâncias padrão incluem:
- CriticalAddonsOnly=true:NoExecute
- node-role.kubernetes.io/control-plane:NoSchedule
- node-role.kubernetes.io/etcd:NoExecute
  Nota
  As tolerâncias adicionais devem ser incluídas na seção .spec.tolerations de cada plano. Os planos do SUC relacionados ao upgrade de versões do Kubernetes estão disponíveis no repositório suse-edge/fleet-examples em:
  Para o RKE2: fleets/day2/system-upgrade-controller-plans/rke2-upgrade
  Para o K3s: fleets/day2/system-upgrade-controller-plans/k3s-upgrade
  Use os planos de uma tag de versão válida do repositório.
  Um exemplo de definição de tolerâncias personalizadas para o plano do SUC de plano de controle do RKE2 tem esta aparência:
  apiVersion: upgrade.cattle.io/v1 kind: Plan metadata: name: rke2-upgrade-control-plane spec: ... tolerations: # default tolerations - key: "CriticalAddonsOnly" operator: "Equal" value: "true" effect: "NoExecute" - key: "node-role.kubernetes.io/control-plane" operator: "Equal" effect: "NoSchedule" - key: "node-role.kubernetes.io/etcd" operator: "Equal" effect: "NoExecute" # custom toleration - key: "foo" operator: "Equal" value: "bar" effect: "NoSchedule" ...

35.2.5.4 Upgrade do K8s: implantação do plano do SUC #

Importante

Em ambientes que já passaram por upgrade usando esse procedimento, os usuários devem garantir que uma das seguintes etapas seja concluída:

Remover os planos do SUC que já foram implantados relacionados a versões de lançamento mais antigas do Edge do cluster de gerenciamento: para fazer isso, remova o cluster desejado da configuração de destino do GitRepo/Bundle, ou remova o recurso GitRepo/Bundle completamente.
Reutilizar o recurso GitRepo/Bundle existente: para fazer isso, aponte a revisão do recurso para uma nova tag que inclua as instâncias do Fleet corretas para a versão desejada de suse-edge/fleet-examples.

Isso é feito para evitar conflitos entre os planos do SUC de versões de lançamento mais antigas do Edge.

Se os usuários tentarem fazer upgrade e já houver planos do SUC no cluster de gerenciamento, eles verão o seguinte erro no Fleet:

Not installed: Unable to continue with install: Plan <plan_name> in namespace <plan_namespace> exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error..

Conforme mencionado na Seção 35.2.5.2, “Visão geral”, os upgrades do Kubernetes são feitos enviando os planos do SUC para o cluster desejado de uma destas maneiras:

Recurso GitRepo do Fleet (Seção 35.2.5.4.1, “Implantação do plano do SUC: recurso GitRepo”)
Recurso Bundle do Fleet (Seção 35.2.5.4.2, “Implantação do plano do SUC – recurso Bundle”)

Para determinar o recurso que você deve usar, consulte a Seção 35.2.2, “Determinar seu caso de uso”.

Para casos de uso de implantação dos planos do SUC do K8s de uma ferramenta GitOps de terceiros, consulte a Seção 35.2.5.4.3, “Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros”.

35.2.5.4.1 Implantação do plano do SUC: recurso GitRepo #

Um recurso GitRepo, que distribui os planos do SUC do K8s necessários, pode ser implantado de uma das seguintes maneiras:

Pela IU do Rancher: Seção 35.2.5.4.1.1, “Criação do GitRepo: IU do Rancher” (quando o Rancher está disponível).
Pela implantação manual do recurso (Seção 35.2.5.4.1.2, “Criação do GitRepo: manual”) no cluster de gerenciamento.

Após a implantação, para monitorar o processo de upgrade do Kubernetes dos nós do cluster de destino, consulte a Seção 22.3, “Monitorando os planos do System Upgrade Controller”.

35.2.5.4.1.1 Criação do GitRepo: IU do Rancher #

Para criar um recurso GitRepo pela IU do Rancher, siga a documentação oficial dele.

A equipe do Edge mantém instâncias do Fleet prontas para uso para distribuições Kubernetes tanto do rke2 quanto do k3s. Dependendo do ambiente, a instância do Fleet pode ser usada diretamente ou como gabarito.

Importante

Sempre use as instâncias do Fleet de uma tag de versão válida do Edge.

Para casos de uso em que não há necessidade de incluir alterações personalizadas nos planos do SUC que as instâncias do Fleet envia, os usuários podem fazer referência a essas instâncias do Fleet diretamente do repositório suse-edge/fleet-examples.

Nos casos em que as alterações personalizadas são necessárias (por exemplo, para adicionar tolerâncias personalizadas), os usuários devem fazer referência às instâncias do Fleet de um repositório separado, para que possam adicionas as alterações aos planos do SUC conforme necessário.

Exemplos de configuração do recurso GitRepo usando as instâncias do Fleet do repositório suse-edge/fleet-examples:

35.2.5.4.1.2 Criação do GitRepo: manual #

Obtenha o recurso GitRepo:

Para clusters RKE2:

curl -o rke2-upgrade-gitrepo.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/gitrepos/day2/rke2-upgrade-gitrepo.yaml

Para clusters K3s:

curl -o k3s-upgrade-gitrepo.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/gitrepos/day2/k3s-upgrade-gitrepo.yaml

Edite a configuração do GitRepo:

Remova a seção spec.targets (necessário apenas para clusters downstream).

Para RKE2:

# Example using sed
sed -i.bak '/^  targets:/,$d' rke2-upgrade-gitrepo.yaml && rm -f rke2-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval 'del(.spec.targets)' -i rke2-upgrade-gitrepo.yaml

Para K3s:

# Example using sed
sed -i.bak '/^  targets:/,$d' k3s-upgrade-gitrepo.yaml && rm -f k3s-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval 'del(.spec.targets)' -i k3s-upgrade-gitrepo.yaml

Aponte o namespace do GitRepo para o namespace fleet-local, feito para implantar o recurso no cluster de gerenciamento.

Para RKE2:

# Example using sed
sed -i.bak 's/namespace: fleet-default/namespace: fleet-local/' rke2-upgrade-gitrepo.yaml && rm -f rke2-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval '.metadata.namespace = "fleet-local"' -i rke2-upgrade-gitrepo.yaml

Para K3s:

# Example using sed
sed -i.bak 's/namespace: fleet-default/namespace: fleet-local/' k3s-upgrade-gitrepo.yaml && rm -f k3s-upgrade-gitrepo.yaml.bak

# Example using yq (v4+)
yq eval '.metadata.namespace = "fleet-local"' -i k3s-upgrade-gitrepo.yaml

Aplique os recursos GitRepo ao cluster de gerenciamento:

# RKE2
kubectl apply -f rke2-upgrade-gitrepo.yaml

# K3s
kubectl apply -f k3s-upgrade-gitrepo.yaml

Visualize o recurso GitRepo criado no namespace fleet-local:

# RKE2
kubectl get gitrepo rke2-upgrade -n fleet-local

# K3s
kubectl get gitrepo k3s-upgrade -n fleet-local

# Example output
NAME           REPO                                              COMMIT          BUNDLEDEPLOYMENTS-READY   STATUS
k3s-upgrade    https://github.com/suse-edge/fleet-examples.git   fleet-local   0/0
rke2-upgrade   https://github.com/suse-edge/fleet-examples.git   fleet-local   0/0

35.2.5.4.2 Implantação do plano do SUC – recurso Bundle #

O recurso Bundle, que envia os planos do SUC de upgrade do Kubernetes necessários, pode ser implantado de uma das seguintes maneiras:

Pela IU do Rancher: Seção 35.2.5.4.2.1, “Criação do bundle – IU do Rancher” (quando o Rancher está disponível).
Pela implantação manual do recurso (Seção 35.2.5.4.2.2, “Criação do bundle – manual”) no cluster de gerenciamento.

Após a implantação, para monitorar o processo de upgrade do Kubernetes dos nós do cluster de destino, consulte a Seção 22.3, “Monitorando os planos do System Upgrade Controller”.

35.2.5.4.2.1 Criação do bundle – IU do Rancher #

A equipe do Edge mantém bundles prontos para uso para distribuições Kubernetes tanto do rke2 quanto do k3s. Dependendo do ambiente, esses bundles podem ser usados diretamente ou como gabaritos.

Importante

Sempre use esse bundle de uma tag de versão válida do Edge.

Para criar um bundle pela IU do Rancher:

No canto superior esquerdo, clique em ☰ → Continuous Delivery (Entrega contínua).
Vá para Advanced > Bundles (Avançado > Bundles).
Selecione Create from YAML (Criar do YAML).
Nesse local, você pode criar o bundle de uma das seguintes maneiras:
Nota
Há casos de uso em que você precisa incluir alterações personalizadas nos planos do SUC que o bundle envia (por exemplo, para adicionar tolerâncias personalizadas). Inclua essas alterações no bundle que será gerado pelas etapas a seguir.
1. Copie manualmente o conteúdo do bundle referente ao RKE2 ou ao K3s de suse-edge/fleet-examples para a página Create from YAML (Criar do YAML).
2. Clone o repositório suse-edge/fleet-examples da tag da versão desejada e selecione a opção Read from File (Ler arquivo) na página Create from YAML (Criar do YAML). Dessa página, navegue até o bundle necessário (bundles/day2/system-upgrade-controller-plans/rke2-upgrade/plan-bundle.yaml para RKE2 e bundles/day2/system-upgrade-controller-plans/k3s-upgrade/plan-bundle.yaml para K3s). Esse procedimento preencherá automaticamente a página Create from YAML (Criar do YAML) com o conteúdo do bundle.
Edite o bundle na IU do Rancher:
- Altere o namespace do Bundle para apontar para o namespace fleet-local.
```
# Example
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: rke2-upgrade
  namespace: fleet-local
...
```
- Altere os clusters de destino para que o Bundle aponte para o seu cluster local (gerenciamento):
```
spec:
  targets:
  - clusterName: local
```
  Nota
  Em alguns casos de uso, o cluster local pode ter um nome diferente.
  Para recuperar o nome do cluster local, execute o comando abaixo:
  kubectl get clusters.fleet.cattle.io -n fleet-local
Selecione Create (Criar).

35.2.5.4.2.2 Criação do bundle – manual #

Obtenha os recursos Bundle:

Para clusters RKE2:

curl -o rke2-plan-bundle.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/bundles/day2/system-upgrade-controller-plans/rke2-upgrade/plan-bundle.yaml

Para clusters K3s:

curl -o k3s-plan-bundle.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.3.0/bundles/day2/system-upgrade-controller-plans/k3s-upgrade/plan-bundle.yaml

Edite a configuração do Bundle:
- Altere os clusters de destino para que o Bundle aponte para o seu cluster local (gerenciamento):
```
spec:
  targets:
  - clusterName: local
```
  Nota
  Em alguns casos de uso, o cluster local pode ter um nome diferente.
  Para recuperar o nome do cluster local, execute o comando abaixo:
  kubectl get clusters.fleet.cattle.io -n fleet-local
- Altere o namespace do Bundle para apontar para o namespace fleet-local.
```
# Example
kind: Bundle
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: rke2-upgrade
  namespace: fleet-local
...
```

Aplique os recursos Bundle ao cluster de gerenciamento:

# For RKE2
kubectl apply -f rke2-plan-bundle.yaml

# For K3s
kubectl apply -f k3s-plan-bundle.yaml

Visualize o recurso Bundle criado no namespace fleet-local:

# For RKE2
kubectl get bundles rke2-upgrade -n fleet-local

# For K3s
kubectl get bundles k3s-upgrade -n fleet-local

# Example output
NAME           BUNDLEDEPLOYMENTS-READY   STATUS
k3s-upgrade    0/0
rke2-upgrade   0/0

35.2.5.4.3 Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros #

Em alguns casos de uso, talvez você queira incorporar os planos do SUC de upgrade do Kubernetes ao fluxo de trabalho do GitOps de terceiros (por exemplo, o Flux).

Para obter os recursos de upgrade do K8s upgrade que você precisa, primeiro determine a tag da versão do Edge do repositório suse-edge/fleet-examples que deseja usar.

Depois disso, os recursos estarão em:

Para ugrade do cluster RKE2:
- Para os nós do plano de controle: fleets/day2/system-upgrade-controller-plans/rke2-upgrade/plan-control-plane.yaml
- Para os nós de worker: fleets/day2/system-upgrade-controller-plans/rke2-upgrade/plan-worker.yaml
Para upgrade do cluster K3s:
- Para os nós do plano de controle: fleets/day2/system-upgrade-controller-plans/k3s-upgrade/plan-control-plane.yaml
- Para os nós de worker: fleets/day2/system-upgrade-controller-plans/k3s-upgrade/plan-worker.yaml

Importante

Para entender melhor como usar o fluxo de trabalho do GitOps para implantar os planos do SUC para upgrade de versão do Kubernetes, consulte a visão geral (Seção 35.2.5.2, “Visão geral”) do procedimento de atualização com o Fleet.

35.2.6 Upgrade do gráfico Helm #

Esta seção aborda as seguintes partes:

Seção 35.2.6.1, “Preparação para ambientes air-gapped”: armazena informações sobre como enviar gráficos e imagens OCI relacionados ao Edge para seu registro particular.
Seção 35.2.6.2, “Procedimento de upgrade”: armazena informações sobre diversos casos de uso de upgrade de gráficos Helm e o respectivo procedimento de upgrade.

35.2.6.1 Preparação para ambientes air-gapped #

35.2.6.1.1 Garantir que você tenha acesso ao Fleet por gráfico Helm #

Dependendo da compatibilidade do seu ambiente, você poderá seguir uma destas opções:

Hospede os recursos do Fleet do seu gráfico em um servidor Git local que possa ser acessado pelo cluster de gerenciamento.
Use a CLI do Fleet para converter um gráfico Helm em bundle, que você pode usar diretamente e não precisa ser hospedado em nenhum lugar. É possível recuperar a CLI do Fleet da página referente à respectiva versão. Para usuários do Mac, existe um Homebrew Formulae fleet-cli.

35.2.6.1.2 Encontrar os ativos necessários à sua versão de lançamento do Edge #

Vá para a página de versões do "dia 2" e localize a versão do Edge para a qual você quer fazer upgrade do gráfico e clique em Assets (Ativos).

Na seção "Assets" (Ativos), faça download dos seguintes arquivos:

Arquivo de versão	Descrição
edge-save-images.sh	Obtém as imagens especificadas no arquivo `edge-release-images.txt` e as compacta em um arquivo ".tar.gz".
edge-save-oci-artefacts.sh	Obtém as imagens de gráfico OCI relacionadas à versão especifica do Edge e as compacta em um arquivo ".tar.gz".
edge-load-images.sh	Carrega as imagens de um arquivo ".tar.gz", faz a remarcação e as envia a um registro particular.
edge-load-oci-artefacts.sh	Detecta o diretório que contém os pacotes ".tgz" de gráficos OCI do Edge e os carrega em um registro particular.
edge-release-helm-oci-artefacts.txt	Contém uma lista de imagens de gráfico OCI relacionadas a uma versão específica do Edge.
edge-release-images.txt	Contém uma lista de imagens relacionadas a uma versão específica do Edge.

35.2.6.1.3 Criar o arquivo de imagens da versão do Edge #

Em uma máquina com acesso à Internet:

Torne o edge-save-images.sh executável:
```
chmod +x edge-save-images.sh
```

Gere o arquivo de imagens:

./edge-save-images.sh --source-registry registry.suse.com

Esse procedimento cria um arquivo pronto para carregamento chamado edge-images.tar.gz.
Nota
Se a opção -i|--images foi especificada, o nome do arquivo pode ser diferente.

Copie esse arquivo para sua máquina air-gapped:

scp edge-images.tar.gz <user>@<machine_ip>:/path

35.2.6.1.4 Criar o arquivo de imagens de gráfico OCI do Edge #

Em uma máquina com acesso à Internet:

Torne o edge-save-oci-artefacts.sh executável:
```
chmod +x edge-save-oci-artefacts.sh
```

Gere o arquivo de imagens de gráfico OCI:

./edge-save-oci-artefacts.sh --source-registry registry.suse.com

Esse procedimento cria um arquivo chamado oci-artefacts.tar.gz.
Nota
Se a opção -a|--archive foi especificada, o nome do arquivo pode ser diferente.

Copie esse arquivo para sua máquina air-gapped:

scp oci-artefacts.tar.gz <user>@<machine_ip>:/path

35.2.6.1.5 Carregar as imagens da versão do Edge para sua máquina air-gapped #

Na máquina air-gapped:

Faça login no seu registro particular (se necessário):
```
podman login <REGISTRY.YOURDOMAIN.COM:PORT>
```
Torne o edge-load-images.sh executável:
```
chmod +x edge-load-images.sh
```
Execute o script, especificando o arquivo já copiado edge-images.tar.gz:
```
./edge-load-images.sh --source-registry registry.suse.com --registry <REGISTRY.YOURDOMAIN.COM:PORT> --images edge-images.tar.gz
```
Nota
Desse modo, todas as imagens do edge-images.tar.gz serão carregadas, remarcadas e enviadas ao registro especificado na opção --registry.

35.2.6.1.6 Carregar as imagens de gráfico OCI do Edge em sua máquina air-gapped #

Na máquina air-gapped:

Faça login no seu registro particular (se necessário):
```
podman login <REGISTRY.YOURDOMAIN.COM:PORT>
```
Torne o edge-load-oci-artefacts.sh executável:
```
chmod +x edge-load-oci-artefacts.sh
```
Descompacte o arquivo oci-artefacts.tar.gz copiado:
```
tar -xvf oci-artefacts.tar.gz
```
Isso cria um diretório com o gabarito de nomenclatura edge-release-oci-tgz-<data>.
Especifique esse diretório no script edge-load-oci-artefacts.sh para carregar as imagens de gráfico OCI do Edge em seu registro particular:
Nota
Esse script assume que a CLI helm foi pré-instalada em seu ambiente. Para obter instruções de instalação do Helm, consulte Installing Helm (Instalando o Helm).
```
./edge-load-oci-artefacts.sh --archive-directory edge-release-oci-tgz-<date> --registry <REGISTRY.YOURDOMAIN.COM:PORT> --source-registry registry.suse.com
```

35.2.6.1.7 Configurar o registro particular na distribuição Kubernetes #

Para RKE2, consulte Private Registry Configuration (Configuração de registro particular)

Para K3s, consulte Private Registry Configuration (Configuração de registro particular)

35.2.6.2 Procedimento de upgrade #

Esta seção tem como foco os seguintes casos de uso do procedimento de upgrade do Helm:

Importante

Não é possível fazer upgrade confiável de gráficos Helm implantados manualmente. Sugerimos reimplantá-los usando o método da Seção 35.2.6.2.1, “Eu tenho um novo cluster e desejo implantar e gerenciar um gráfico Helm do Edge”.

35.2.6.2.1 Eu tenho um novo cluster e desejo implantar e gerenciar um gráfico Helm do Edge #

Esta seção aborda o seguinte:

35.2.6.2.1.1 Preparar os recursos do Fleet para seu gráfico #

Adquira os recursos do Fleet do gráfico com base na tag da versão do Edge que deseja usar.
Navegue até a instância do Fleet do gráfico Helm (fleets/day2/chart-templates/<gráfico>).
Se você pretende usar um fluxo de trabalho do GitOps, copie o diretório do Fleet do gráfico para o repositório Git do qual você vai executar o GitOps.
Opcionalmente, se o gráfico Helm exigir configurações em seus valores, edite a configuração .helm.values no arquivo fleet.yaml do diretório copiado.
Opcionalmente, pode haver casos de uso em que você tenha que adicionar outros recursos à instância do Fleet do seu gráfico para que se adapte melhor ao seu ambiente. Para obter informações de como aprimorar o diretório do Fleet, consulte Git Repository Contents (Conteúdo do repositório Git).

Nota

Em alguns casos, o tempo limite padrão que o Fleet usa nas operações do Helm pode ser insuficiente e resultar no seguinte erro:

failed pre-install: context deadline exceeded

Nesses casos, adicione a propriedade timeoutSeconds à configuração helm do arquivo fleet.yaml.

Esta é a aparência de um exemplo de gráfico Helm do longhorn:

Estrutura de repositórios Git do usuário:

<user_repository_root>
├── longhorn
│   └── fleet.yaml
└── longhorn-crd
    └── fleet.yaml

Conteúdo do fleet.yaml preenchido com os dados do Longhorn do usuário:

defaultNamespace: longhorn-system

helm:
  # timeoutSeconds: 10
  releaseName: "longhorn"
  chart: "longhorn"
  repo: "https://charts.rancher.io/"
  version: "106.2.0+up1.8.1"
  takeOwnership: true
  # custom chart value overrides
  values:
    # Example for user provided custom values content
    defaultSettings:
      deletingConfirmationFlag: true

# https://fleet.rancher.io/bundle-diffs
diff:
  comparePatches:
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: engineimages.longhorn.io
    operations:
    - {"op":"remove", "path":"/status/conditions"}
    - {"op":"remove", "path":"/status/storedVersions"}
    - {"op":"remove", "path":"/status/acceptedNames"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: nodes.longhorn.io
    operations:
    - {"op":"remove", "path":"/status/conditions"}
    - {"op":"remove", "path":"/status/storedVersions"}
    - {"op":"remove", "path":"/status/acceptedNames"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: volumes.longhorn.io
    operations:
    - {"op":"remove", "path":"/status/conditions"}
    - {"op":"remove", "path":"/status/storedVersions"}
    - {"op":"remove", "path":"/status/acceptedNames"}

Nota

Estes são apenas valores de exemplo usados para ilustrar as configurações comuns no gráfico do longhorn. Eles NÃO devem ser considerados diretrizes de implantação para o gráfico do longhorn.

35.2.6.2.1.2 Implantar o Fleet para seu gráfico #

É possível implantar o Fleet para seu gráfico usando o GitRepo (Seção 35.2.6.2.1.2.1, “GitRepo”) ou o bundle (Seção 35.2.6.2.1.2.2, “Bundle”).

Nota

Durante a implantação do Fleet, se você receber a mensagem Modified (Modificado), adicione uma entrada comparePatches correspondente à seção diff do Fleet. Para obter mais informações, consulte Generating Diffs to Ignore Modified GitRepos (Gerando diffs para ignorar GitRepos modificados).

35.2.6.2.1.2.1 GitRepo #

O recurso GitRepo do Fleet armazena as informações sobre como acessar os recursos do Fleet do seu gráfico e a quais clusters ele precisa aplicar esses recursos.

É possível implantar o recurso GitRepo pela IU do Rancher ou manualmente pela implantação do recurso no cluster de gerenciamento.

Exemplo de recurso GitRepo do Longhorn para implantação manual:

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: longhorn-git-repo
  namespace: fleet-local
spec:
  # If using a tag
  # revision: user_repository_tag
  #
  # If using a branch
  # branch: user_repository_branch
  paths:
  # As seen in the 'Prepare your Fleet resources' example
  - longhorn
  - longhorn-crd
  repo: user_repository_url

35.2.6.2.1.2.2 Bundle #

Os recursos Bundle armazenam os recursos brutos do Kubernetes que o Fleet precisa implantar. Normalmente, a recomendação é usar a abordagem do GitRepo, mas para casos de uso em que o ambiente é air-gapped e não oferece suporte a um servidor Git local, os Bundles podem ajudar na propagação do Fleet do gráfico Helm aos clusters de destino.

É possível implantar um Bundle pela IU do Rancher (Continuous Delivery → Advanced → Bundles → Create from YAML (Entrega contínua → Avançado → Bundles → Criar do YAML)) ou pela implantação manual do recurso Bundle no namespace correto do Fleet. Para obter informações sobre os namespaces do Fleet, consulte a documentação upstream.

É possível criar Bundles para gráficos Helm do Edge usando a abordagem Converter um gráfico Helm em bundle do Fleet.

Veja a seguir um exemplo de como criar um recurso Bundle com base nos gabaritos de gráfico Helm longhorn e longhorn-crd do Fleet e implantar manualmente esse bundle no cluster de gerenciamento.

Nota

Para ilustrar o fluxo de trabalho, o exemplo a seguir usa a estrutura de diretório suse-edge/fleet-examples.

Navegue até o gabarito de gráfico longhorn do Fleet:
```
cd fleets/day2/chart-templates/longhorn/longhorn
```
Crie um arquivo targets.yaml para instruir o Fleet sobre os clusters em que ele deve implantar o gráfico Helm:
```
cat > targets.yaml <<EOF
targets:
# Match your local (management) cluster
- clusterName: local
EOF
```
Nota
Em alguns casos de uso, o nome do seu cluster local pode ser diferente.
Para recuperar o nome do seu cluster local, execute este comando:
```
kubectl get clusters.fleet.cattle.io -n fleet-local
```
Converta o gráfico Helm Longhorn do Fleet em um recurso bundle usando fleet-cli.
Nota
É possível recuperar a CLI do Fleet da página Assets (Ativos) da respectiva versão (fleet-linux-amd64).
Para usuários do Mac, existe um Homebrew Formulae fleet-cli.
```
fleet apply --compress --targets-file=targets.yaml -n fleet-local -o - longhorn-bundle > longhorn-bundle.yaml
```
Navegue até o gabarito de gráfico longhorn-crd do Fleet:
```
cd fleets/day2/chart-templates/longhorn/longhorn-crd
```
Crie um arquivo targets.yaml para instruir o Fleet sobre os clusters em que ele deve implantar o gráfico Helm:
```
cat > targets.yaml <<EOF
targets:
# Match your local (management) cluster
- clusterName: local
EOF
```

Converta o gráfico Helm Longhorn CRD do Fleet em um recurso bundle usando fleet-cli.

fleet apply --compress --targets-file=targets.yaml -n fleet-local -o - longhorn-crd-bundle > longhorn-crd-bundle.yaml

Implante os arquivos longhorn-bundle.yaml e longhorn-crd-bundle.yaml no cluster de gerenciamento:
```
kubectl apply -f longhorn-crd-bundle.yaml
kubectl apply -f longhorn-bundle.yaml
```

Siga estas etapas para garantir que o SUSE Storage seja implantado em todos os clusters de gerenciamento especificados.

35.2.6.2.1.3 Gerenciar o gráfico Helm implantado #

Após a implantação com o Fleet, para fazer upgrade dos gráficos Helm, consulte a Seção 35.2.6.2.2, “Quero fazer upgrade de um gráfico Helm gerenciado pelo Fleet”.

35.2.6.2.2 Quero fazer upgrade de um gráfico Helm gerenciado pelo Fleet #

Determine a versão para a qual você precisa fazer upgrade do seu gráfico para que ele fique compatível com o lançamento desejado do Edge. Você encontra a versão do gráfico Helm por lançamento do Edge nas Notas de lançamento (Seção 52.1, “Resumo”).
No repositório Git monitorado pelo Fleet, edite o arquivo fleet.yaml do gráfico Helm com a versão e o repositório corretos do gráfico conforme as Notas de lançamento (Seção 52.1, “Resumo”).
Depois de confirmar e enviar as alterações ao repositório, será acionado um upgrade do gráfico Helm desejado.

35.2.6.2.3 Quero fazer upgrade de um gráfico Helm implantado pelo EIB #

O Capítulo 11, Edge Image Builder implanta gráficos Helm criando um recurso HelmChart e usando o helm-controller introduzido pelo recurso de integração do Helm RKE2/K3s.

Para garantir que o upgrade do gráfico Helm implantado pelo EIB seja feito com sucesso, os usuários precisam fazer upgrade dos respectivos recursos HelmChart.

Veja a seguir informações sobre:

A visão geral (Seção 35.2.6.2.3.1, “Visão geral”) do processo de upgrade.
As etapas de upgrade necessárias (Seção 35.2.6.2.3.2, “Etapas de upgrade”).
Um exemplo (Seção 35.2.6.2.3.3, “Exemplo”) que demonstra o upgrade de um gráfico Longhorn usando o método explicado.
Como usar o processo de upgrade com uma ferramenta GitOps diferente (Seção 35.2.6.2.3.4, “Upgrade do gráfico Helm usando uma ferramenta GitOps de terceiros”).

35.2.6.2.3.1 Visão geral #

O upgrade dos gráficos Helm que são implantados pelo EIB é feito por uma instância do Fleet chamada eib-charts-upgrader.

Essa instância do Fleet processa os dados fornecidos pelo usuário para atualizar um conjunto específico de recursos HelmChart.

A atualização desses recursos aciona o helm-controller, que faz upgrade dos gráficos Helm associados aos recursos HelmChart modificados.

O usuário precisa apenas:

Obter localmente os arquivos para cada gráfico Helm que precisa de upgrade.
Especificar esses arquivos no script generate-chart-upgrade-data.sh generate-chart-upgrade-data.sh, que incluirá os dados dos arquivos na instância do Fleet eib-charts-upgrader.
Implantar a instância do Fleet eib-charts-upgrader no respectivo cluster de gerenciamento. Isso é feito por um recurso GitRepo ou Bundle.

Após a implantação, o eib-charts-upgrader, com ajuda do Fleet, enviará os recursos para o cluster de gerenciamento desejado.

Esses recursos incluem:

Um conjunto de segredos com os dados do gráfico Helm fornecidos pelo usuário.
Um Kubernetes Job para implantar o pod que vai montar os segredos já mencionados e, com base neles, aplicar o patch aos recursos HelmChart correspondentes.

Como já foi mencionado, isso acionará o helm-controller, que faz upgrade do gráfico Helm real.

Veja a seguir um diagrama da descrição acima:

upgrade eib helm gerenciamento dia2 fleet

35.2.6.2.3.2 Etapas de upgrade #

Clone o repositório suse-edge/fleet-examples da tag da versão correta.
Crie um diretório para armazenar um ou mais arquivos dos gráficos Helm enviados.
```
mkdir archives
```

Dentro do diretório do arquivo recém-criado, extraia os arquivos dos gráficos Helm dos quais você deseja fazer upgrade:

cd archives
helm pull [chart URL | repo/chartname]

# Alternatively if you want to pull a specific version:
# helm pull [chart URL | repo/chartname] --version 0.0.0

Em Assets (Ativos) da tag da versão desejada, faça download do script generate-chart-upgrade-data.sh.
Execute o script generate-chart-upgrade-data.sh:
```
chmod +x ./generate-chart-upgrade-data.sh

./generate-chart-upgrade-data.sh --archive-dir /foo/bar/archives/ --fleet-path /foo/bar/fleet-examples/fleets/day2/eib-charts-upgrader
```
Para cada arquivo de gráfico no diretório --archive-dir, o script gera um arquivo YAML de segredo do Kubernetes com os dados de upgrade do gráfico e o armazena no diretório base/secrets da instância do Fleet especificada por --fleet-path.
O script generate-chart-upgrade-data.sh também aplica modificações adicionais à instância do Fleet para garantir que os arquivos YAML de segredo do Kubernetes gerados sejam corretamente usados pela carga de trabalho implantada pelo Fleet.
Importante
Os usuários não devem fazer alterações no conteúdo que é gerado pelo script generate-chart-upgrade-data.sh.

As etapas abaixo dependem do ambiente que está em execução:

Para um ambiente com suporte a GitOps (por exemplo, não air-gapped ou air-gapped, mas com suporte a servidor Git local):
1. Copie a instância do Fleet fleets/day2/eib-charts-upgrader para o repositório que você vai usar com o GitOps.
  Nota
  Garanta que o Fleet inclua as alterações feitas pelo script generate-chart-upgrade-data.sh.
2. Configure o recurso GitRepo que será usado para enviar todos os recursos da instância do Fleet eib-charts-upgrader.
  1. Para configuração e implantação do GitRepo pela IU do Rancher, consulte Accessing Fleet in the Rancher UI (Acessando o Fleet na IU do Racher).
  2. Para configuração e implantação manuais do GitRepo, consulte Creating a Deployment (Criando uma implantação).
Para um ambiente sem suporte a GitOps (por exemplo, air-gapped que não permite o uso de servidor Git local):
1. Faça download do binário fleet-cli na página da versão do rancher/fleet (fleet-linux-amd64 para Linux). Para usuários do Mac, existe um Homebrew Formulae que pode ser usado: fleet-cli.
2. Navegue até a instância do Fleet eib-charts-upgrader:
```
cd /foo/bar/fleet-examples/fleets/day2/eib-charts-upgrader
```
3. Crie um arquivo targets.yaml para instruir o Fleet sobre onde implantar seus recursos:
```
cat > targets.yaml <<EOF
targets:
# To map the local(management) cluster
- clusterName: local
EOF
```
  Nota
  Em alguns casos de uso, o cluster local pode ter um nome diferente.
  Para recuperar o nome do cluster local, execute o comando abaixo:
  kubectl get clusters.fleet.cattle.io -n fleet-local
4. Use fleet-cli para converter o Fleet em um recurso Bundle:
```
fleet apply --compress --targets-file=targets.yaml -n fleet-local -o - eib-charts-upgrade > bundle.yaml
```
  Isso cria um bundle (bundle.yaml) para armazenar todos os recursos usados como gabaritos da instância do Fleet eib-charts-upgrader.
  Para obter mais informações sobre o comando fleet apply, consulte fleet apply.
  Para obter mais informações sobre como converter instâncias do Fleet em bundles, consulte Convert a Helm Chart into a Bundle (Converter um gráfico Helm em bundle).
5. Implante o Bundle. É possível fazer isso de uma destas maneiras:
  1. Pela IU do Rancher: navegue até Continuous Delivery → Advanced → Bundles → Create from YAML (Entrega contínua → Avançado → Bundles → Criar do YAML) e cole o conteúdo do bundle.yaml ou clique na opção Read from File (Ler arquivo) e especifique o arquivo.
  2. Manualmente: implante o arquivo bundle.yaml manualmente no cluster de gerenciamento.

A execução dessas etapas resulta na implantação bem-sucedida do recurso GitRepo/Bundle. O Fleet seleciona o recurso e seu conteúdo é implantado nos clusters de destino que o usuário especificou nas etapas anteriores. Para obter uma visão geral do processo, consulte a Seção 35.2.6.2.3.1, “Visão geral”.

Para obter informações sobre como acompanhar o processo de upgrade, consulte a Seção 35.2.6.2.3.3, “Exemplo”.

Importante

Após a verificação bem-sucedida da atualização do gráfico, remova o recurso Bundle/GitRepo.

Isso removerá os recursos de upgrade que não são mais necessários do cluster de gerenciamento, garantindo que não haja conflitos com versões futuras.

35.2.6.2.3.3 Exemplo #

Nota

No exemplo a seguir, demonstramos como fazer upgrade de um gráfico Helm implantado pelo EIB de uma versão para outra em um cluster de gerenciamento. Observe que as versões usadas neste exemplo não são recomendações. Para recomendações de versão específicas a um lançamento do Edge, consulte as Notas de lançamento (Seção 52.1, “Resumo”).

Caso de uso:

Um cluster de gerenciamento que executa uma versão mais antiga do Longhorn.

O cluster foi implantado pelo EIB usando o seguinte trecho de definição da imagem:

kubernetes:
  helm:
    charts:
    - name: longhorn-crd
      repositoryName: rancher-charts
      targetNamespace: longhorn-system
      createNamespace: true
      version: 104.2.0+up1.7.1
      installationNamespace: kube-system
    - name: longhorn
      repositoryName: rancher-charts
      targetNamespace: longhorn-system
      createNamespace: true
      version: 104.2.0+up1.7.1
      installationNamespace: kube-system
    repositories:
    - name: rancher-charts
      url: https://charts.rancher.io/
...

É preciso fazer upgrade do SUSE Storage para uma versão compatível com o Edge 3.3.1, ou seja, para a versão 106.2.0+up1.8.1.
Presume-se que o cluster de gerenciamento seja air-gapped, sem suporte a servidor Git local e com uma instalação ativa do Rancher.

Siga as etapas de upgrade (Seção 35.2.6.2.3.2, “Etapas de upgrade”):

Clone o repositório suse-edge/fleet-example da tag release-3.3.0.

git clone -b release-3.3.0 https://github.com/suse-edge/fleet-examples.git

Crie um diretório para armazenar o arquivo de upgrade do Longhorn.
```
mkdir archives
```

Extraia a versão desejada do arquivo de gráficos do Longhorn:

# First add the Rancher Helm chart repository
helm repo add rancher-charts https://charts.rancher.io/

# Pull the Longhorn 1.8.1 CRD archive
helm pull rancher-charts/longhorn-crd --version 106.2.0+up1.8.1

# Pull the Longhorn 1.8.1 chart archive
helm pull rancher-charts/longhorn --version 106.2.0+up1.8.1

Fora do diretório archives, faça download do script generate-chart-upgrade-data.sh da tag da versão do suse-edge/fleet-examples.

A configuração do diretório deve ter uma aparência como esta:

.
├── archives
|   ├── longhorn-106.2.0+up1.8.1.tgz
│   └── longhorn-crd-106.2.0+up1.8.1.tgz
├── fleet-examples
...
│   ├── fleets
│   │   ├── day2
|   |   |   ├── ...
│   │   │   ├── eib-charts-upgrader
│   │   │   │   ├── base
│   │   │   │   │   ├── job.yaml
│   │   │   │   │   ├── kustomization.yaml
│   │   │   │   │   ├── patches
│   │   │   │   │   │   └── job-patch.yaml
│   │   │   │   │   ├── rbac
│   │   │   │   │   │   ├── cluster-role-binding.yaml
│   │   │   │   │   │   ├── cluster-role.yaml
│   │   │   │   │   │   ├── kustomization.yaml
│   │   │   │   │   │   └── sa.yaml
│   │   │   │   │   └── secrets
│   │   │   │   │       ├── eib-charts-upgrader-script.yaml
│   │   │   │   │       └── kustomization.yaml
│   │   │   │   ├── fleet.yaml
│   │   │   │   └── kustomization.yaml
│   │   │   └── ...
│   └── ...
└── generate-chart-upgrade-data.sh

Execute o script generate-chart-upgrade-data.sh:

# First make the script executable
chmod +x ./generate-chart-upgrade-data.sh

# Then execute the script
./generate-chart-upgrade-data.sh --archive-dir ./archives --fleet-path ./fleet-examples/fleets/day2/eib-charts-upgrader

A estrutura de diretórios após a execução do script deve ser parecida com esta:

.
├── archives
|   ├── longhorn-106.2.0+up1.8.1.tgz
│   └── longhorn-crd-106.2.0+up1.8.1.tgz
├── fleet-examples
...
│   ├── fleets
│   │   ├── day2
│   │   │   ├── ...
│   │   │   ├── eib-charts-upgrader
│   │   │   │   ├── base
│   │   │   │   │   ├── job.yaml
│   │   │   │   │   ├── kustomization.yaml
│   │   │   │   │   ├── patches
│   │   │   │   │   │   └── job-patch.yaml
│   │   │   │   │   ├── rbac
│   │   │   │   │   │   ├── cluster-role-binding.yaml
│   │   │   │   │   │   ├── cluster-role.yaml
│   │   │   │   │   │   ├── kustomization.yaml
│   │   │   │   │   │   └── sa.yaml
│   │   │   │   │   └── secrets
│   │   │   │   │       ├── eib-charts-upgrader-script.yaml
│   │   │   │   │       ├── kustomization.yaml
│   │   │   │   │       ├── longhorn-VERSION.yaml - secret created by the generate-chart-upgrade-data.sh script
│   │   │   │   │       └── longhorn-crd-VERSION.yaml - secret created by the generate-chart-upgrade-data.sh script
│   │   │   │   ├── fleet.yaml
│   │   │   │   └── kustomization.yaml
│   │   │   └── ...
│   └── ...
└── generate-chart-upgrade-data.sh

Os arquivos alterados no Git devem ter aparência similar a esta:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   fleets/day2/eib-charts-upgrader/base/patches/job-patch.yaml
	modified:   fleets/day2/eib-charts-upgrader/base/secrets/kustomization.yaml

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	fleets/day2/eib-charts-upgrader/base/secrets/longhorn-VERSION.yaml
	fleets/day2/eib-charts-upgrader/base/secrets/longhorn-crd-VERSION.yaml

Crie um Bundle para a instância do Fleet eib-charts-upgrader:
1. Primeiro, navegue até o Fleet:
```
cd ./fleet-examples/fleets/day2/eib-charts-upgrader
```
2. Em seguida, crie um arquivo targets.yaml:
```
cat > targets.yaml <<EOF
targets:
- clusterName: local
EOF
```
3. Depois disso, use o binário fleet-cli para converter a instância do Fleet em um bundle:
```
fleet apply --compress --targets-file=targets.yaml -n fleet-local -o - eib-charts-upgrade > bundle.yaml
```
Implante o bundle usando a IU do Rancher:
Figura 35.1: Implantar o bundle usando a IU do Rancher #

Agora selecione Read from File (Ler arquivo) e encontre o arquivo bundle.yaml no sistema.
Isso preencherá automaticamente o Bundle na IU do Rancher.
Selecione Create (Criar).
Após a implantação bem-sucedida, o bundle terá uma aparência similar a esta:
Figura 35.2: Bundle implantado com sucesso #

Após a implantação bem-sucedida do Bundle, monitore o processo de upgrade da seguinte maneira:

Consulte os registros do pod de upgrade:
Agora consulte os registros do pod criado pelo helm-controller para o upgrade:
1. O nome do pod seguirá o seguinte gabarito: helm-install-longhorn-<sufixo-aleatório>
2. O pod estará no namespace em que o recurso HelmChart foi implantado. No nosso caso, o namespace é kube-system.
  Figura 35.3: Registros do gráfico do Longhorn atualizado com sucesso #
Verifique se a versão do HelmChart foi atualizada navegando até a seção HelmCharts do Rancher (More Resources → HelmCharts "Mais recursos → HelmCharts"). Selecione o namespace em que o gráfico foi implantado; que, neste exemplo, é kube-system.
Por fim, verifique se os pods do Longhorn estão em execução.

Depois de fazer as validações acima, é seguro pressupor que o upgrade do gráfico Helm do Longhorn foi feito para a versão 106.2.0+up1.8.1.

35.2.6.2.3.4 Upgrade do gráfico Helm usando uma ferramenta GitOps de terceiros #

Em alguns casos de uso, os usuários talvez queiram seguir esse procedimento de upgrade com um fluxo de trabalho do GitOps diferente do Fleet (por exemplo, Flux).

Para gerar os recursos necessários ao procedimento de upgrade, você pode usar o script generate-chart-upgrade-data.sh para preencher a instância do Fleet eib-charts-upgrader com os dados fornecidos pelo usuário. Para obter mais informações sobre como fazer isso, consulte a Seção 35.2.6.2.3.2, “Etapas de upgrade”.

Com a configuração completa, você pode usar o kustomize para gerar uma solução totalmente funcional para ser implantada no seu cluster:

cd /foo/bar/fleets/day2/eib-charts-upgrader

kustomize build .

Para incluir a solução no fluxo de trabalho do GitOps, remova o arquivo fleet.yaml e use o que sobrou como configuração válida do Kustomize. Lembre-se de executar primeiro o script generate-chart-upgrade-data.sh para que ele possa preencher a configuração do Kustomize com os dados dos gráficos Helm para o qual você quer fazer upgrade.

Para saber qual é a finalidade de uso desse fluxo de trabalho, consulte a Seção 35.2.6.2.3.1, “Visão geral” e a Seção 35.2.6.2.3.2, “Etapas de upgrade”.