Applies to SUSE Edge 3.6

33 Downstream clusters #

Esta seção aborda as possíveis maneiras de realizar operações de "Dia 2" para diferentes partes do seu downstream cluster.

33.1 Fleet #

Esta seção oferece informações sobre como realizar operações de "Dia 2" usando o componente Fleet (Chapter 6, Fleet).

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

Section 33.1.1, “Componentes” - componentes padrão usados para todas as operações de "Dia 2".
Section 33.1.2, “Determine seu caso de uso” - fornece uma visão geral dos recursos personalizados do Fleet que serão usados e sua adequação para diferentes casos de uso de operações de "Dia 2".
Section 33.1.3, “Fluxo de trabalho de Dia 2” - fornece um guia de fluxo de trabalho para a execução de operações de "Dia 2" com o Fleet.
Section 33.1.4, “Fazer upgrade do SO” - descreve como fazer upgrade do SO usando o Fleet.
Section 33.1.5, “Atualização da versão do Kubernetes” - descreve como fazer upgrade da versão do Kubernetes usando o Fleet.
Section 33.1.6, “Fazer upgrade do Helm chart” - descreve como fazer upgrade do Helm chart usando o Fleet.

33.1.1 Componentes #

Abaixo, você pode encontrar uma descrição dos componentes padrão que devem ser configurados em seu cluster downstream para que você possa realizar com sucesso as operações de "Dia 2" usando o Fleet.

33.1.1.1 System Upgrade Controller (SUC) #

Note

Deve ser implantado em cada cluster downstream.

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

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

Para obter mais informações sobre o componente SUC e como ele se encaixa na pilha Edge, consulte Chapter 18, Upgrade Controller do Sistema.

Para obter informações sobre como implantar o SUC, primeiro determine seu caso de uso (Section 33.1.2, “Determine seu caso de uso”) e, em seguida, consulte Instalação do System Upgrade Controller - GitRepo (Section 18.2.1.1, “Instalação do Upgrade Controller - GitRepo”) ou Instalação do System Upgrade Controller - Bundle (Section 18.2.1.2, “Instalação do Upgrade Controller - Bundle”).

33.1.2 Determine seu caso de uso #

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

Abaixo, você pode encontrar informações sobre o propósito desses recursos e os casos de uso para os quais eles são mais adequados no contexto de operações de "Dia 2".

33.1.2.1 GitRepo #

Um GitRepo é um recurso Fleet (Chapter 6, Fleet) que representa um repositório Git a partir do qual o Fleet pode criar Bundles. Cada Bundle é criado com base em caminhos de configuração definidos dentro do recurso GitRepo. Para obter mais informações, consulte a documentação do GitRepo.

No contexto de operações de "Dia 2", os recursos GitRepo são normalmente usados para implantar SUC ou SUC Plans em ambientes não air-gapped que utilizam uma abordagem de Fleet GitOps.

Alternativamente, os recursos GitRepo também podem ser usados para implantar SUC ou SUC Plans em ambientes air-gapped, desde que você espelhe a configuração do seu repositório por meio de um servidor git local.

33.1.2.2 Pacote #

Bundles contêm recursos raw do Kubernetes que serão implantados no cluster de destino. Geralmente, eles são criados a partir de um recurso GitRepo, mas existem casos de uso em que podem ser implantados manualmente. Para obter mais informações, consulte a documentação do Bundle.

No contexto de operações de "Dia 2", os recursos Bundle são normalmente usados para implantar SUC ou SUC Plans em ambientes air-gapped que não utilizam alguma forma de procedimento de GitOps local (por exemplo, um servidor git local).

Alternativamente, se o seu caso de uso não permitir um fluxo de trabalho GitOps (por exemplo, usando um repositório Git), os recursos Bundle também podem ser usados para implantar SUC ou SUC Plans em ambientes não air-gapped.

33.1.3 Fluxo de trabalho de Dia 2 #

O que se segue é um fluxo de trabalho de "Dia 2" que deve ser seguido ao fazer upgrade de um cluster downstream para uma versão específica do Edge.

Fazer upgrade do SO (Section 33.1.4, “Fazer upgrade do SO”)
Kubernetes version upgrade (Section 33.1.5, “Atualização da versão do Kubernetes”)
Fazer upgrade do Helm chart (Section 33.1.6, “Fazer upgrade do Helm chart”)

33.1.4 Fazer upgrade do SO #

Esta seção descreve como fazer upgrade do sistema operacional usando Chapter 6, Fleet e o Chapter 18, Upgrade Controller do Sistema.

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

Section 33.1.4.1, “Componentes” - componentes adicionais usados pelo processo de upgrade.
Section 33.1.4.2, “Visão geral” - visão geral do processo de upgrade.
Section 33.1.4.3, “Requisitos” - requisitos do processo de upgrade.
Section 33.1.4.4, “Upgrade do SO - implantação do plano SUC” - informações sobre como implantar o SUC plans, responsável por acionar o processo de upgrade.

33.1.4.1 Componentes #

Esta seção aborda os componentes personalizados que o processo de OS upgrade usa em relação aos componentes (Section 33.1.1, “Componentes”) padrão de "Day 2".

33.1.4.1.1 systemd.service #

O upgrade do SO em um nó específico é gerenciado por um systemd.service.

Um serviço diferente é criado dependendo do tipo de upgrade que o SO requer de uma versão do Edge para outra:

Para versões do Edge que requerem a mesma versão do SO (por exemplo, 6.1), o os-pkg-update.service será criado. Ele usa transactional-update para realizar um upgrade normal de pacotes.
Para versões do Edge que requerem uma migração de versão do SO (por exemplo, 6.1 → 6.2), o os-migration.service será criado. Ele usa transactional-update para realizar:
1. Um upgrade normal de pacotes que garante que todos os pacotes estejam atualizados para mitigar quaisquer falhas na migração relacionadas a versões antigas de pacotes.
2. Uma migração de SO utilizando o comando zypper migration.

Os serviços mencionados acima são fornecidos em cada nó por meio de um SUC plan que deve estar localizado no cluster downstream que precisa de upgrade do SO.

33.1.4.2 Visão geral #

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

Fleet é usado para implantar e gerenciar SUC plans no cluster desejado.

Note

SUC plans são recursos personalizados que descrevem as etapas que o SUC precisa seguir para que uma tarefa específica seja executada em um conjunto de nós. Para um exemplo de como um SUC plan se parece, consulte o repositório upstream.

Os OS SUC plans são enviados para cada cluster implantando um recurso GitRepo ou Bundle em um workspace específico do Fleet. O Fleet recupera os GitRepo/Bundle implantados e implanta seu conteúdo (o OS SUC plans) no(s) cluster(es) desejado(s).

Note

Os recursos GitRepo/Bundle são sempre implantados no management cluster. Se usar um recurso GitRepo ou Bundle depende do seu caso de uso, verifique Section 33.1.2, “Determine seu caso de uso” para mais informações.

OS SUC plans descrevem o seguinte fluxo de trabalho:

Sempre cordon os nós antes de upgrades do SO.
Sempre faça upgrade dos nós control-plane antes dos nós worker.
Sempre faça upgrade do cluster, um nó por vez.

Uma vez que os OS SUC plans são implantados, o fluxo de trabalho é o seguinte:

O SUC reconcilia os OS SUC plans implantados e cria um Kubernetes Job em cada nó.
O Kubernetes Job cria um systemd.service (Section 33.1.4.1.1, “systemd.service”) para upgrade de pacote ou migração de SO.
O systemd.service criado aciona o processo de upgrade do SO no nó específico.
Important
Assim que o processo de upgrade do SO terminar, o nó correspondente será rebooted para aplicar as atualizações no sistema.

Abaixo você pode encontrar um diagrama da descrição acima:

33.1.4.3 Requisitos #

Geral:

Máquina registrada no SCC - Todos os downstream nós do cluster devem estar registrados no https://scc.suse.com/, o que é necessário para que o respectivo systemd.service possa se conectar com sucesso ao repositório RPM desejado.
Important
Para versões Edge que exigem uma migração de versão de SO (por exemplo, 6.1 → 6.2), certifique-se de que sua chave SCC suporte a migração para a nova versão.
Certifique-se de que as tolerâncias do Plano SUC correspondam às tolerâncias do nó - Se os nós do seu cluster Kubernetes tiverem taints personalizados, certifique-se de adicionar tolerâncias para esses taints nos Planos SUC. Por padrão, SUC Plans possuem tolerâncias apenas para nós control-plane. As tolerâncias padrão incluem:
- CriticalAddonsOnly=true:NoExecute
- node-role.kubernetes.io/control-plane:NoSchedule
- node-role.kubernetes.io/etcd:NoExecute
  Note
  Quaisquer tolerâncias adicionais devem ser adicionadas na seção .spec.tolerations de cada Plano. SUC Plans relacionados ao upgrade do SO podem ser encontrados no repositório suse-edge/fleet-examples em fleets/day2/system-upgrade-controller-plans/os-upgrade. Certifique-se de usar os Planos de uma tag de release de repositório válida.
  Um exemplo de definição de tolerâncias personalizadas para o plano SUC control-plane seria assim:
  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 da SUSE - Os repositórios RPM do SO devem ser espelhados localmente para que o systemd.service possa ter acesso a eles. Isso pode ser alcançado usando RMT ou SUMA.

33.1.4.4 Upgrade do SO - implantação do plano SUC #

Important

Para ambientes atualizados anteriormente usando este procedimento, os usuários devem garantir que uma das seguintes etapas seja concluída:

Remove any previously deployed SUC Plans related to older Edge release versions from the downstream cluster - pode ser feito removendo o cluster desejado da GitRepo/Bundle target configuration existente, ou removendo o recurso GitRepo/Bundle por completo.
Reuse the existing GitRepo/Bundle resource - pode ser feito apontando a revisão do recurso para uma nova tag que contenha as frotas corretas para o suse-edge/fleet-examples release desejado.

Isso é feito para evitar conflitos entre SUC Plans para versões de release do Edge mais antigas.

Se os usuários tentarem fazer upgrade enquanto houver SUC Plans existentes no cluster downstream, eles verão o seguinte erro do 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..

Como mencionado em Section 33.1.4.2, “Visão geral”, os upgrades do SO são feitos enviando SUC plans para o cluster desejado por meio de uma das seguintes maneiras:

Recurso GitRepo do Fleet - Section 33.1.4.4.1, “Implantação do plano SUC - recurso GitRepo”.
Recurso Bundle do Fleet - Section 33.1.4.4.2, “Implantação do plano SUC - Recurso de Bundle”.

Para determinar qual recurso você deve usar, consulte Section 33.1.2, “Determine seu caso de uso”.

Para casos de uso em que você deseja implantar o OS SUC plans a partir de uma ferramenta GitOps de terceiros, consulte Section 33.1.4.4.3, “Implantação do plano SUC - fluxo de trabalho GitOps de terceiros”

33.1.4.4.1 Implantação do plano SUC - recurso GitRepo #

Um recurso GitRepo, que implanta o OS SUC plans necessário, pode ser implantado de uma das seguintes maneiras:

Através do Rancher UI - Section 33.1.4.4.1.1, “Criação de GitRepo - UI do Rancher” (quando Rancher estiver disponível).
Ao implantar manualmente (Section 33.1.4.4.1.2, “Criação de GitRepo - manual”) o recurso no seu management cluster.

Uma vez implantado, para monitorar o processo de upgrade do SO dos nós do seu cluster alvo, consulte Section 18.3, “Monitoramento de Planos do Upgrade Controller do Sistema”.

33.1.4.4.1.1 Criação de GitRepo - UI do Rancher #

Para criar um recurso GitRepo através da UI do Rancher, siga a documentação oficial deles.

A equipe Edge mantém um fleet pronto para uso. Dependendo do seu ambiente, este fleet pode ser usado diretamente ou como um modelo.

Important

Sempre use este fleet a partir de uma tag de release válida do Edge.

Para casos de uso onde nenhuma alteração personalizada precisa ser incluída no SUC plans que o fleet entrega, os usuários podem referenciar diretamente o fleet os-upgrade do repositório suse-edge/fleet-examples.

Em casos onde alterações personalizadas são necessárias (por exemplo, para adicionar tolerâncias personalizadas), os usuários devem referenciar o fleet os-upgrade de um repositório separado, permitindo que adicionem as alterações aos planos SUC conforme necessário.

Um exemplo de como um GitRepo pode ser configurado para usar o fleet do repositório suse-edge/fleet-examples, pode ser visto aqui.

33.1.4.4.1.2 Criação de GitRepo - manual #

Puxe o recurso GitRepo:

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

Edite a configuração do GitRepo, em spec.targets especifique sua lista de destino desejada. Por padrão, os recursos GitRepo do suse-edge/fleet-examples NÃO são mapeados para nenhum cluster downstream.
- Para corresponder a todos os clusters, altere o GitRepo destino padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Alternativamente, se você quiser uma seleção de cluster mais granular, veja Mapeamento para Clusters Downstream
Aplique o recurso GitRepo ao seu management cluster:
```
kubectl apply -f os-upgrade-gitrepo.yaml
```

Visualize o recurso GitRepo criado no namespace fleet-default:

kubectl get gitrepo os-upgrade -n fleet-default

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

33.1.4.4.2 Implantação do plano SUC - Recurso de Bundle #

Um recurso Bundle, que inclui os OS SUC Plans necessários, pode ser implantado de uma das seguintes maneiras:

Através do Rancher UI - Section 33.1.4.4.2.1, “Criação de Bundle - Interface do Rancher” (quando Rancher estiver disponível).
Ao implantar manualmente (Section 33.1.4.4.2.2, “Criação de Bundle - manual”) o recurso no seu management cluster.

Uma vez implantado, para monitorar o processo de fazer upgrade do SO dos nós do seu cluster alvo, consulte Section 18.3, “Monitoramento de Planos do Upgrade Controller do Sistema”.

33.1.4.4.2.1 Criação de Bundle - Interface do Rancher #

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

Important

Sempre use este bundle a partir de uma tag de release Edge válida.

Para criar um bundle através da interface do Rancher:

No canto superior esquerdo, clique em ☰ → Continuous Delivery
Vá para Avançado > Bundles
Selecione Criar a partir de YAML
A partir daqui, você pode criar o Bundle de uma das seguintes maneiras:
Note
Pode haver casos de uso em que você precise incluir alterações personalizadas no SUC plans que o bundle inclui (por exemplo, para adicionar tolerâncias personalizadas). Certifique-se de incluir essas alterações no bundle que será gerado pelas etapas abaixo.
1. Copiando manualmente o conteúdo do bundle de suse-edge/fleet-examples para a página Criar a partir de YAML.
2. Clonando o repositório suse-edge/fleet-examples da release desejada e selecionando a opção Ler a partir de arquivo na página Criar a partir de YAML. A partir daí, navegue até o local do bundle (bundles/day2/system-upgrade-controller-plans/os-upgrade) e selecione o arquivo do bundle. Isso preencherá automaticamente a página Criar a partir de YAML com o conteúdo do bundle.
Altere os clusters target para o Bundle:
- Para corresponder a todos os clusters downstream, altere o Bundle .spec.targets padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Para mapeamentos de clusters downstream mais granulares, consulte Mapping to Downstream Clusters.
Selecione Criar

33.1.4.4.2.2 Criação de Bundle - manual #

Obtenha o recurso Bundle:

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

Edite as configurações de Bundle target, em spec.targets forneça sua lista de target desejada. Por padrão, os recursos Bundle do suse-edge/fleet-examples NÃO são mapeados para nenhum cluster downstream.
- Para corresponder a todos os clusters, altere o Bundle target padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Alternativamente, se você quiser uma seleção de clusters mais granular, veja Mapping to Downstream Clusters
Aplique o recurso Bundle ao seu management cluster:
```
kubectl apply -f os-upgrade-bundle.yaml
```
Visualize o recurso Bundle criado no namespace fleet-default:
```
kubectl get bundles -n fleet-default
```

33.1.4.4.3 Implantação do plano SUC - fluxo de trabalho GitOps de terceiros #

Pode haver casos de uso em que os usuários desejem incorporar o OS SUC plans ao seu próprio fluxo de trabalho GitOps de terceiros (por exemplo, Flux).

Para obter os recursos de fazer upgrade do SO de que você precisa, primeiro determine a tag de release do Edge do repositório suse-edge/fleet-examples que você deseja usar.

Depois disso, os recursos podem ser encontrados em fleets/day2/system-upgrade-controller-plans/os-upgrade, onde:

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

Important

Estes recursos Plan são interpretados pelo System Upgrade Controller e devem ser implantados em cada cluster downstream que você deseja fazer upgrade. Para informações sobre a implantação do SUC, consulte Section 18.2, “Instalando o Upgrade Controller do Sistema”.

Para entender melhor como seu fluxo de trabalho GitOps pode ser usado para implantar os SUC Plans para fazer upgrade do SO, pode ser útil dar uma olhada na visão geral (Section 33.1.4.2, “Visão geral”).

33.1.5 Atualização da versão do Kubernetes #

Important

Esta seção aborda atualizações do Kubernetes para clusters downstream que NÃO foram criados por meio de uma instância do Rancher (Chapter 4, Rancher). Para obter informações sobre como atualizar a versão do Kubernetes de clusters criados pelo Rancher, consulte Atualizando e revertendo o Kubernetes.

Esta seção descreve como realizar uma atualização do Kubernetes usando o Chapter 6, Fleet e o Chapter 18, Upgrade Controller do Sistema.

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

Section 33.1.5.1, “Componentes” - componentes adicionais usados pelo processo de atualização.
Section 33.1.5.2, “Visão geral” - visão geral do processo de atualização.
Section 33.1.5.3, “Requisitos” - requisitos do processo de atualização.
Section 33.1.5.4, “Atualização do K8s - implantação do plano SUC” - informações sobre como implantar o SUC plans, responsável por acionar o processo de atualização.

33.1.5.1 Componentes #

Esta seção aborda os componentes personalizados que o processo K8s upgrade usa em vez dos componentes (Section 33.1.1, “Componentes”) padrão de "Dia 2".

33.1.5.1.1 rke2-upgrade #

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

Distribuída por meio de um Pod criado pelo SUC com base em um Plano SUC. O Plano deve estar localizado em cada cluster que precise de uma atualização do RKE2.

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

33.1.5.1.2 k3s-upgrade #

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

Distribuída por meio de um Pod criado pelo SUC com base em um Plano SUC. O Plano deve estar localizado em cada cluster que precise de um upgrade do K3s.

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

33.1.5.2 Visão geral #

O upgrade da distribuição Kubernetes para nós de cluster downstream é feito utilizando Fleet e o System Upgrade Controller (SUC).

Fleet é usado para implantar e gerenciar SUC plans no cluster desejado.

Note

SUC plans são recursos personalizados que descrevem as etapas que o SUC precisa seguir para que uma tarefa específica seja executada em um conjunto de nós. Para um exemplo de como um SUC plan se parece, consulte o repositório upstream.

Os K8s SUC plans são enviados em cada cluster implantando um recurso GitRepo ou Bundle em um workspace específico do Fleet. O Fleet recupera o GitRepo/Bundle implantado e implanta seu conteúdo (o K8s SUC plans) no(s) cluster(es) desejado(s).

Note

Recursos GitRepo/Bundle são sempre implantados no management cluster. Se usar um recurso GitRepo ou Bundle depende do seu caso de uso, verifique Section 33.1.2, “Determine seu caso de uso” para mais informações.

K8s SUC plans descrevem o seguinte fluxo de trabalho:

Sempre cordon os nós antes de fazer upgrade do K8s.
Sempre atualize os nós control-plane antes dos nós worker.
Sempre atualize os nós control-plane um nó por vez e os nós worker dois nós por vez.

Uma vez que os K8s SUC plans são implantados, o fluxo de trabalho parece com isto:

O SUC reconcilia os K8s SUC plans implantados e cria um Kubernetes Job em cada nó.
Dependendo da distribuição do Kubernetes, o Job criará um Pod que executa a imagem de contêiner rke2-upgrade (Section 33.1.5.1.1, “rke2-upgrade”) ou k3s-upgrade (Section 33.1.5.1.2, “k3s-upgrade”).
O Pod criado passará pelo seguinte fluxo de trabalho:
1. Substitua o binário rke2/k3s existente no nó pelo da imagem rke2-upgrade/k3s-upgrade.
2. Encerre o processo rke2/k3s em execução.
Encerrar o processo rke2/k3s aciona uma reinicialização, iniciando um novo processo que executa o binário atualizado, resultando em uma versão de distribuição do Kubernetes atualizada.

Abaixo você pode encontrar um diagrama da descrição acima:

33.1.5.3 Requisitos #

Faça backup da sua distribuição Kubernetes:
1. Para clusters RKE2, consulte a documentação de Backup e Restauração do RKE2.
2. Para clusters K3s, consulte a documentação de Backup e Restauração do K3s.
Certifique-se de que as tolerâncias do Plano SUC correspondam às tolerâncias do nó - Se os nós do seu cluster Kubernetes tiverem taints personalizados, certifique-se de adicionar tolerâncias para esses taints nos Planos SUC. Por padrão, os Planos SUC possuem tolerâncias apenas para nós de 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
  Note
  Quaisquer tolerâncias adicionais devem ser adicionadas na seção .spec.tolerations de cada Plano. Os Planos SUC relacionados à atualização da versão do Kubernetes podem ser encontrados no repositório suse-edge/fleet-examples em:
  Para RKE2 - fleets/day2/system-upgrade-controller-plans/rke2-upgrade
  Para K3s - fleets/day2/system-upgrade-controller-plans/k3s-upgrade
  Certifique-se de usar os Planos de uma tag de lançamento de repositório válida.
  Um exemplo de definição de tolerâncias personalizadas para o Plano SUC do plano de controle do RKE2 seria assim:
  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" ...

33.1.5.4 Atualização do K8s - implantação do plano SUC #

Important

Para ambientes previamente atualizados usando este procedimento, os usuários devem garantir que um das seguintes etapas seja concluído:

Remove any previously deployed SUC Plans related to older Edge release versions from the downstream cluster - pode ser feito removendo o cluster desejado da GitRepo/Bundle configuração de destino existente, ou removendo o recurso GitRepo/Bundle por completo.
Reuse the existing GitRepo/Bundle resource - pode ser feito apontando a revisão do recurso para uma nova tag que contenha os Fleet corretos para o suse-edge/fleet-examples lançamento desejado.

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

Se os usuários tentarem fazer upgrade enquanto houver SUC Plans existentes no cluster downstream, eles verão o seguinte erro do 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..

Como mencionado em Section 33.1.5.2, “Visão geral”, as atualizações do Kubernetes são feitas enviando SUC plans para o cluster desejado através de uma das seguintes maneiras:

Recurso GitRepo do Fleet (Section 33.1.5.4.1, “Implantação de plano SUC - recurso GitRepo”)
Recurso Bundle do Fleet (Section 33.1.5.4.2, “Implantação do plano SUC - Recurso Bundle”)

Para determinar qual recurso você deve usar, consulte Section 33.1.2, “Determine seu caso de uso”.

Para casos de uso onde você deseja implantar o K8s SUC plans a partir de uma ferramenta GitOps de terceiros, consulte Section 33.1.5.4.3, “Implantação do plano SUC - fluxo de trabalho GitOps de terceiros”

33.1.5.4.1 Implantação de plano SUC - recurso GitRepo #

Um recurso GitRepo, que envia o K8s SUC plans necessário, pode ser implantado de uma das seguintes maneiras:

Através do Rancher UI - Section 33.1.5.4.1.1, “Criação de GitRepo - IU do Rancher” (quando Rancher estiver disponível).
Por implantação manual (Section 33.1.5.4.1.2, “Criação de GitRepo - manual”) do recurso no seu management cluster.

Uma vez implantado, para monitorar o processo de fazer upgrade do Kubernetes dos nós do seu cluster de destino, consulte Section 18.3, “Monitoramento de Planos do Upgrade Controller do Sistema”.

33.1.5.4.1.1 Criação de GitRepo - IU do Rancher #

Para criar um recurso GitRepo através da IU do Rancher, siga a documentação oficial deles.

A equipe Edge mantém fleets prontos para uso para as distribuições Kubernetes rke2 e k3s. Dependendo do seu ambiente, este fleet pode ser usado diretamente ou como um modelo.

Important

Sempre use esses fleets a partir de uma tag de release válida do Edge.

Para casos de uso onde não é necessário incluir alterações personalizadas no SUC plans que esses fleets enviam, os usuários podem referenciar diretamente os fleets do repositório suse-edge/fleet-examples.

Em casos onde alterações personalizadas são necessárias (por exemplo, para adicionar tolerations personalizadas), os usuários devem referenciar os fleets de um repositório separado, permitindo-lhes adicionar as alterações aos planos SUC conforme necessário.

Exemplos de configuração para um recurso GitRepo usando os fleets do repositório suse-edge/fleet-examples:

33.1.5.4.1.2 Criação de GitRepo - manual #

Puxe o recurso GitRepo:

Para clusters RKE2:

curl -o rke2-upgrade-gitrepo.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.6.1/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.6.1/gitrepos/day2/k3s-upgrade-gitrepo.yaml

Edite a configuração do GitRepo, em spec.targets especifique sua lista de destino desejada. Por padrão, os recursos GitRepo do suse-edge/fleet-examples NÃO são mapeados para nenhum cluster downstream.
- Para corresponder a todos os clusters, altere o GitRepo target padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Alternativamente, se você quiser uma seleção de cluster mais granular, veja Mapeamento para Clusters Downstream

Aplique os recursos GitRepo ao seu management cluster:

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

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

Visualize o recurso GitRepo criado no namespace fleet-default:

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

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

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

33.1.5.4.2 Implantação do plano SUC - Recurso Bundle #

Um recurso Bundle, que fornece os Kubernetes upgrade SUC Plans necessários, pode ser implantado de uma das seguintes maneiras:

Através do Rancher UI - Section 33.1.5.4.2.1, “Criação de Bundle - Interface do Rancher” (quando Rancher estiver disponível).
Implantando manualmente (Section 33.1.5.4.2.2, “Criação de Bundle - manual”) o recurso no seu management cluster.

Uma vez implantado, para monitorar o processo de atualização do Kubernetes dos nós do seu cluster de destino, consulte Section 18.3, “Monitoramento de Planos do Upgrade Controller do Sistema”.

33.1.5.4.2.1 Criação de Bundle - Interface do Rancher #

A equipe Edge mantém bundles prontos para uso para as distribuições Kubernetes rke2 e k3s. Dependendo do seu ambiente, esses bundles podem ser usados diretamente ou como um modelo.

Important

Sempre use este bundle a partir de uma tag de release Edge válida.

Para criar um Bundle através da interface do Rancher:

No canto superior esquerdo, clique em ☰ → Entrega contínua
Vá para Avançado > Bundle
Selecione Criar a partir de YAML
A partir daqui, você pode criar o Bundle de uma das seguintes maneiras:
Note
Pode haver casos de uso em que você precise incluir alterações personalizadas no SUC plans que o Bundle fornece (por exemplo, para adicionar tolerâncias personalizadas). Certifique-se de incluir essas alterações no Bundle que será gerado pelas etapas abaixo.
1. Copiando manualmente o conteúdo do Bundle para RKE2 ou K3s de suse-edge/fleet-examples para a página Criar a partir de YAML.
2. Clonando o repositório suse-edge/fleet-examples da tag de release desejada e selecionando a opção Ler de Arquivo na página Criar a partir de YAML. A partir daí, navegue até o Bundle que você precisa (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). Isso preencherá automaticamente a página Criar a partir de YAML com o conteúdo do Bundle.
Altere os clusters de destino para o Bundle:
- Para corresponder a todos os clusters downstream, altere o .spec.targets do Bundle padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Para mapeamentos de cluster downstream mais granulares, consulte Mapeamento para Clusters Downstream.
Selecione Criar

33.1.5.4.2.2 Criação de Bundle - manual #

Puxe os recursos do Bundle:

Para clusters RKE2:

curl -o rke2-plan-bundle.yaml https://raw.githubusercontent.com/suse-edge/fleet-examples/refs/tags/release-3.6.1/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.6.1/bundles/day2/system-upgrade-controller-plans/k3s-upgrade/plan-bundle.yaml

Edite as configurações de Bundle destino, em spec.targets forneça a lista de destino desejada. Por padrão, os recursos Bundle do suse-edge/fleet-examples NÃO são mapeados para nenhum cluster downstream.
- Para corresponder a todos os clusters, altere o Bundle target padrão para:
```
spec:
  targets:
  - clusterSelector: {}
```
- Alternativamente, se você quiser uma seleção de cluster mais granular, veja Mapeamento para Clusters Downstream

Aplique os recursos do Bundle ao seu management cluster:

# 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-default:

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

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

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

33.1.5.4.3 Implantação do plano SUC - fluxo de trabalho GitOps de terceiros #

Pode haver casos de uso em que os usuários gostariam de incorporar o Kubernetes upgrade SUC plans ao seu próprio fluxo de trabalho GitOps de terceiros (por exemplo, Flux).

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

Depois disso, os recursos podem ser encontrados em:

Para uma atualização de cluster RKE2:
- Para nós control-plane - fleets/day2/system-upgrade-controller-plans/rke2-upgrade/plan-control-plane.yaml
- Para nós worker - fleets/day2/system-upgrade-controller-plans/rke2-upgrade/plan-worker.yaml
Para uma atualização de cluster K3s:
- Para nós control-plane - fleets/day2/system-upgrade-controller-plans/k3s-upgrade/plan-control-plane.yaml
- Para nós worker - fleets/day2/system-upgrade-controller-plans/k3s-upgrade/plan-worker.yaml

Important

Esses recursos Plan são interpretados pelo System Upgrade Controller e devem ser implantados em cada cluster downstream que você deseja atualizar. Para informações sobre a implantação do SUC, consulte Section 18.2, “Instalando o Upgrade Controller do Sistema”.

Para entender melhor como seu fluxo de trabalho GitOps pode ser usado para implantar os SUC Plans para fazer upgrade da versão do Kubernetes, pode ser benéfico dar uma olhada na visão geral (Section 33.1.5.2, “Visão geral”) do procedimento de atualização usando Fleet.

33.1.6 Fazer upgrade do Helm chart #

Esta seção abrange as seguintes partes:

Section 33.1.6.1, “Preparação para ambientes air-gapped” - contém informações sobre como enviar charts e imagens OCI relacionados ao Edge para o seu registro privado.
Section 33.1.6.2, “Procedimento de upgrade” - contém informações sobre diferentes casos de uso de upgrade do Helm chart e seu procedimento de upgrade.

33.1.6.1 Preparação para ambientes air-gapped #

33.1.6.1.1 Certifique-se de ter acesso ao Fleet do seu Helm chart #

Dependendo do que seu ambiente suporta, você pode escolher uma das seguintes opções:

Hospede os recursos do Fleet do seu chart em um servidor Git local que seja acessível pelo seu management cluster.
Use a CLI do Fleet para converter um Helm chart em um Bundle que você pode usar diretamente e que não precisará ser hospedado em algum lugar. A CLI do Fleet pode ser obtida na página de release, para usuários de Mac existe uma fleet-cli Homebrew Formulae.

33.1.6.1.2 Encontre os ativos necessários para a sua versão de release do Edge #

Vá para a página de release do "Day 2", encontre a release do Edge para a qual você deseja atualizar seu chart e clique em Assets.

Na seção "Assets", baixe os seguintes arquivos:

Release File	Descrição
edge-save-images.sh	Extrai as imagens especificadas no arquivo `edge-release-images.txt` e as empacota dentro de um arquivo '.tar.gz'.
edge-save-oci-artefacts.sh	Extrai as imagens de chart OCI relacionadas à release específica do Edge e as empacota dentro de um arquivo '.tar.gz'.
edge-load-images.sh	Carrega imagens de um arquivo '.tar.gz', renomeia as tags e as envia para um registro privado.
edge-load-oci-artefacts.sh	Recebe um diretório contendo pacotes de chart OCI '.tgz' do Edge e os carrega em um registro privado.
edge-release-helm-oci-artefacts.txt	Contém uma lista de imagens de chart OCI relacionadas a uma release específica do Edge.
edge-release-images.txt	Contém uma lista de imagens relacionadas a uma release específica do Edge.

33.1.6.1.3 Crie o arquivo de imagens de release 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 imagem:

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

Isso criará um arquivo pronto para carregamento chamado edge-images.tar.gz.
Note
Se a opção -i|--images for especificada, o nome do arquivo pode ser diferente.

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

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

33.1.6.1.4 Crie o arquivo de imagens de chart 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 imagem de chart OCI:

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

Isso criará um arquivo chamado oci-artefacts.tar.gz.
Note
Se a opção -a|--archive for especificada, o nome do arquivo pode ser diferente.

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

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

33.1.6.1.5 Carregue as imagens de release do Edge em sua máquina air-gapped #

Em sua máquina air-gapped:

Faça login no seu registro privado (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, passando o arquivo copiado edge-images.tar.gz anteriormente:
```
./edge-load-images.sh --source-registry registry.suse.com --registry <REGISTRY.YOURDOMAIN.COM:PORT> --images edge-images.tar.gz
```
Note
Isso carregará todas as imagens do edge-images.tar.gz, renomeará as tags e as enviará para o registro especificado na opção --registry.

33.1.6.1.6 Carregue as imagens de chart OCI do Edge para sua máquina air-gapped. #

Em sua máquina air-gapped:

Faça login no seu registro privado (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 copiado oci-artefacts.tar.gz:
```
tar -xvf oci-artefacts.tar.gz
```
Isso produzirá um diretório com o modelo de nomenclatura edge-release-oci-tgz-<date>
Passe este diretório para o script edge-load-oci-artefacts.sh para carregar as imagens do chart Edge OCI para seu registro privado:
Note
Este script pressupõe que a CLI helm tenha sido pré-instalada em seu ambiente. Para instruções de instalação do Helm, consulte 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
```

33.1.6.1.7 Configure seu registro privado em sua distribuição Kubernetes #

Para RKE2, consulte Configuração de Registro Privado

Para K3s, consulte Configuração de Registro Privado

33.1.6.2 Procedimento de upgrade #

Esta seção foca nos seguintes casos de uso do procedimento de upgrade do Helm:

Important

Charts do Helm implantados manualmente não podem ser atualizados de forma confiável. Sugerimos reimplantar o chart do Helm usando o método Section 33.1.6.2.1, “Tenho um novo cluster e gostaria de implantar e gerenciar um chart Helm do Edge.”.

33.1.6.2.1 Tenho um novo cluster e gostaria de implantar e gerenciar um chart Helm do Edge. #

Esta seção aborda como:

33.1.6.2.1.1 Prepare os recursos do Fleet para o seu chart. #

Adquira os recursos do Fleet do chart a partir da tag de release do Edge que você deseja usar.
Navegue até o Fleet do chart do Helm (fleets/day2/chart-templates/<chart>).
Se você pretende usar um fluxo de trabalho GitOps, copie o diretório do Fleet do chart para o repositório Git de onde você fará o GitOps.
Opcionalmente, se o chart do Helm exigir configurações em seus values, edite a configuração .helm.values dentro do arquivo fleet.yaml do diretório copiado.
Opcionalmente, podem existir casos de uso em que você precise adicionar recursos adicionais ao Fleet do seu chart para que ele possa se ajustar melhor ao seu ambiente. Para obter informações sobre como aprimorar seu diretório Fleet, consulte Conteúdo do Repositório Git.

Note

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

failed pre-install: context deadline exceeded

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

Um exemplo para o Helm chart longhorn seria assim:

Estrutura do repositório Git do usuário:

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

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

defaultNamespace: longhorn-system

helm:
  # timeoutSeconds: 10
  releaseName: "longhorn"
  chart: "longhorn"
  repo: "https://charts.rancher.io/"
  version: "1.11.2"
  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"}

Note

Estes são apenas valores de exemplo que são usados para ilustrar configurações personalizadas no chart longhorn. Eles NÃO devem ser tratados como diretrizes de implantação para o chart longhorn.

33.1.6.2.1.2 Implante o Fleet para o seu chart #

Você pode implantar o Fleet para o seu chart usando um GitRepo (Section 33.1.6.2.1.2.1, “GitRepo”) ou um Bundle (Section 33.1.6.2.1.2.2, “Pacote”).

Note

Ao implantar o Fleet, se você receber uma mensagem Modified, certifique-se de adicionar uma entrada comparePatches correspondente à seção diff do Fleet. Para mais informações, consulte Gerando Diffs para Ignorar GitRepos Modificados.

33.1.6.2.1.2.1 GitRepo #

O recurso GitRepo do Fleet contém informações sobre como acessar os recursos do Fleet do seu chart e a quais clusters ele precisa aplicar esses recursos.

O recurso GitRepo pode ser implantado através da Rancher UI, ou manualmente, implantando o recurso no management cluster.

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

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: longhorn-git-repo
  namespace: fleet-default
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
  targets:
  # Match all clusters
  - clusterSelector: {}

33.1.6.2.1.2.2 Pacote #

Os recursos Bundle contêm os recursos brutos do Kubernetes que precisam ser implantados pelo Fleet. Normalmente, recomenda-se usar a abordagem GitRepo, mas para casos de uso em que o ambiente é air-gapped e não pode suportar um servidor Git local, o Bundles pode ajudá-lo a propagar o Fleet do seu chart Helm para seus clusters de destino.

Um Bundle pode ser implantado através da Rancher UI (Continuous Delivery → Advanced → Bundles → Create from YAML) ou implantando manualmente o recurso Bundle no namespace correto do Fleet. Para obter informações sobre os namespaces do Fleet, consulte a documentação upstream.

Bundles para charts Helm do Edge podem ser criados utilizando a abordagem Converter um chart Helm em um Bundle do Fleet.

Abaixo você pode encontrar um exemplo de como criar um recurso Bundle a partir dos modelos de Fleet de charts Helm longhorn e longhorn-crd e implantar manualmente este bundle no seu management cluster.

Note

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

Navegue até o modelo de Fleet do chart longhorn:

cd fleets/day2/chart-templates/longhorn/longhorn

Crie um arquivo targets.yaml que instruirá o Fleet para quais clusters ele deve implantar o chart Helm:
```
cat > targets.yaml <<EOF
targets:
# Matches all downstream clusters
- clusterSelector: {}
EOF
```
Para uma seleção de cluster downstream mais granular, consulte Mapeamento para Clusters downstream.
Converta o Fleet do chart Helm Longhorn em um recurso Bundle usando o fleet-cli.
Note
A CLI do Fleet pode ser obtida na página de release Assets (fleet-linux-amd64).
Para usuários de Mac, existe uma fórmula Homebrew chamada fleet-cli.
```
fleet apply --compress --targets-file=targets.yaml -n fleet-default -o - longhorn-bundle > longhorn-bundle.yaml
```

Navegue até o template do chart Fleet longhorn-crd:

cd fleets/day2/chart-templates/longhorn/longhorn-crd

Crie um arquivo targets.yaml que instruirá o Fleet sobre a quais clusters ele deve implantar o gráfico Helm:
```
cat > targets.yaml <<EOF
targets:
# Matches all downstream clusters
- clusterSelector: {}
EOF
```

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

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

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

Seguir estes passos garantirá que o SUSE Storage seja implantado em todos os clusters downstream especificados.

33.1.6.2.1.3 Gerenciar o gráfico Helm implantado #

Uma vez implantado com o Fleet, para fazer upgrade de gráficos Helm, consulte Section 33.1.6.2.2, “Eu gostaria de fazer upgrade de um gráfico Helm gerenciado pelo Fleet”.

33.1.6.2.2 Eu gostaria de 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 seja compatível com a versão do Edge desejada. A versão do gráfico Helm por versão do Edge pode ser visualizada nas notas de lançamento (Chapter 41, Notas de versão).
No seu repositório Git monitorado pelo Fleet, edite o arquivo fleet.yaml do gráfico Helm com a versão e o repositório corretos das notas de lançamento (Chapter 41, Notas de versão).
Após confirmar e enviar as alterações para o seu repositório, isso acionará o fazer upgrade do Helm chart desejado.

33.1.6.2.3 Eu gostaria de fazer upgrade de um Helm chart implantado via EIB. #

Chapter 8, Edge Image Builder implanta Helm charts criando um recurso HelmChart e utilizando o helm-controller introduzido pelo recurso de integração Helm RKE2/K3s.

Para garantir que um Helm chart implantado via EIB seja feito upgrade com sucesso, os usuários precisam fazer upgrade dos respectivos recursos HelmChart.

Abaixo você pode encontrar informações sobre:

A visão geral (Section 33.1.6.2.3.1, “Visão geral”) do processo de upgrade.
As etapas de upgrade (Section 33.1.6.2.3.2, “Etapas de upgrade”) necessárias.
Um exemplo (Section 33.1.6.2.3.3, “Exemplo”) que demonstra o upgrade do chart Longhorn usando o método explicado.
Como usar o processo de upgrade com uma ferramenta GitOps diferente (Section 33.1.6.2.3.4, “Fazer upgrade do Helm chart usando uma ferramenta GitOps de terceiros”).

33.1.6.2.3.1 Visão geral #

Os Helm charts implantados via EIB são feitos upgrade por meio de um fleet chamado eib-charts-upgrader.

Este fleet processa 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 Helm charts associados aos recursos HelmChart modificados.

Espera-se que o usuário apenas:

Baixe localmente os arquivos para cada Helm chart que precisa ser feito upgrade.
Passe esses arquivos para o generate-chart-upgrade-data.sh generate-chart-upgrade-data.sh script, que incluirá os dados desses arquivos na frota eib-charts-upgrader.
Implante a frota eib-charts-upgrader em seu management cluster. Isso é feito por meio de um recurso GitRepo ou Bundle.

Uma vez implantado, o eib-charts-upgrader, com a ajuda do Fleet, enviará seus recursos para o cluster downstream desejado.

Esses recursos incluem:

Um conjunto de Secrets contendo os dados do Helm chart fornecidos pelo usuário.
Um Kubernetes Job que implantará um Pod que montará o Secrets mencionado anteriormente e, com base neles, patch os recursos HelmChart correspondentes.

Como mencionado anteriormente, isso acionará o helm-controller que realizará a atualização real do chart Helm.

Abaixo você pode encontrar um diagrama da descrição acima:

33.1.6.2.3.2 Etapas de upgrade #

Clone o repositório suse-edge/fleet-examples da tag de lançamento correta tag.
Crie um diretório no qual você armazenará o(s) arquivo(s) do chart Helm baixado(s).
```
mkdir archives
```

Dentro do diretório recém-criado para os arquivos, pull os arquivos dos charts Helm que 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

De Assets da release tag desejada, baixe o 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 chart no diretório --archive-dir, o script gera um arquivo Kubernetes Secret YAML contendo os dados de upgrade do chart e o armazena no diretório base/secrets da frota especificada por --fleet-path.
O script generate-chart-upgrade-data.sh também aplica modificações adicionais à frota para garantir que os arquivos Kubernetes Secret YAML gerados sejam utilizados corretamente pela carga de trabalho implantada pela frota.
Important
Os usuários não devem fazer alterações além do que o script generate-chart-upgrade-data.sh gera.

As etapas abaixo dependem do ambiente em que você está executando:

Para um ambiente que suporta GitOps (por exemplo, não é air-gapped, ou é air-gapped, mas permite o suporte a um servidor Git local):
1. Copie a fleets/day2/eib-charts-upgrader Fleet para o repositório que você usará para GitOps.
  Note
  Certifique-se de que a Fleet inclua as alterações que foram feitas pelo script generate-chart-upgrade-data.sh.
2. Configure um recurso GitRepo que será usado para enviar todos os recursos da eib-charts-upgrader Fleet.
  1. Para configuração e implantação do GitRepo por meio da interface do Rancher, consulte Accessing Fleet in the Rancher UI.
  2. Para configuração e implantação manual do GitRepo, consulte Creating a Deployment.
Para um ambiente que não suporta GitOps (por exemplo, é isolado da rede e não permite o uso de servidor Git local):
1. Baixe o binário fleet-cli da página de rancher/fleet release (fleet-linux-amd64 para Linux). Para usuários de Mac, existe uma Homebrew Formulae que pode ser usada - fleet-cli.
2. Navegue até a eib-charts-upgrader Fleet:
```
cd /foo/bar/fleet-examples/fleets/day2/eib-charts-upgrader
```
3. Crie um arquivo targets.yaml que instruirá o Fleet sobre onde implantar seus recursos:
```
cat > targets.yaml <<EOF
targets:
# To match all downstream clusters
- clusterSelector: {}
EOF
```
  Para obter informações sobre como mapear clusters de destino, consulte a documentation upstream.
4. Use o fleet-cli para converter o Fleet em um recurso Bundle:
```
fleet apply --compress --targets-file=targets.yaml -n fleet-default -o - eib-charts-upgrade > bundle.yaml
```
  Isso criará um Bundle (bundle.yaml) que conterá todos os recursos modelados do Fleet eib-charts-upgrader.
  Para mais informações sobre o comando fleet apply, consulte fleet apply.
  Para mais informações sobre a conversão de Fleets em Bundles, consulte Convert a Helm Chart into a Bundle.
5. Implante o Bundle. Isso pode ser feito de duas maneiras:
  1. Através da interface do Rancher - Navegue até Continuous Delivery → Advanced → Bundles → Create from YAML e cole o conteúdo do bundle.yaml ou clique na opção Read from File e envie o próprio arquivo.
  2. Manualmente - Implante o arquivo bundle.yaml manualmente dentro do seu management cluster.

A execução dessas etapas resultará em um recurso GitRepo/Bundle implantado com sucesso. O recurso será captado pelo Fleet e seu conteúdo será implantado nos clusters de destino que o usuário especificou nas etapas anteriores. Para uma visão geral do processo, consulte Section 33.1.6.2.3.1, “Visão geral”.

Para obter informações sobre como acompanhar o processo de fazer upgrade, você pode consultar Section 33.1.6.2.3.3, “Exemplo”.

Important

Assim que o upgrade do chart for verificado com sucesso, remova o recurso Bundle/GitRepo.

Isso removerá os recursos de upgrade que não são mais necessários do seu cluster downstream, garantindo que nenhum conflito de versão futuro ocorra.

33.1.6.2.3.3 Exemplo #

Note

O exemplo abaixo demonstra como fazer upgrade de um Helm chart implantado via EIB de uma versão para outra em um cluster downstream. Observe que as versões usadas neste exemplo não são recomendações. Para recomendações de versão específicas para uma versão Edge, consulte as notas de versão (Chapter 41, Notas de versão).

Caso de uso:

Um cluster chamado doc-example está executando uma versão mais antiga do Longhorn.

O cluster foi implantado por meio do EIB, usando a seguinte definição de imagem snippet:

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

O SUSE Storage precisa ser feito upgrade para uma versão compatível com a release 3.6 do Edge. Ou seja, ele precisa ser feito upgrade para 1.11.2.
Assume-se que o management cluster responsável pelo gerenciamento do doc-example está air-gapped, sem suporte para um servidor Git local e possui uma configuração do Rancher funcional.

Siga as etapas para fazer upgrade (Section 33.1.6.2.3.2, “Etapas de upgrade”):

Clone o repositório suse-edge/fleet-example a partir da tag release-3.6.1.

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

Crie um diretório onde o arquivo de fazer upgrade do Longhorn será armazenado.
```
mkdir archives
```

Faça o pull da versão desejada do arquivo do chart Longhorn:

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

# Pull the Longhorn 1.11.2 chart archive
helm pull oci://dp.apps.rancher.io/charts/suse-storage --version 1.11.2

Fora do diretório archives, baixe o script generate-chart-upgrade-data.sh do release suse-edge/fleet-examples tag.

A configuração do diretório deve ser semelhante a:

.
├── archives
│   └── longhorn-1.11.2.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 do diretório após a execução do script deve ser semelhante a:

.
├── archives
│   └── longhorn-1.11.2.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 ser semelhantes a isto:

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 o Fleet eib-charts-upgrader:
1. Primeiro, navegue até o próprio Fleet:
```
cd ./fleet-examples/fleets/day2/eib-charts-upgrader
```
2. Em seguida, crie um arquivo targets.yaml:
```
cat > targets.yaml <<EOF
targets:
- clusterName: doc-example
EOF
```
3. Em seguida, use o binário fleet-cli para converter o Fleet em um Bundle:
```
fleet apply --compress --targets-file=targets.yaml -n fleet-default -o - eib-charts-upgrade > bundle.yaml
```
4. Agora, transfira o bundle.yaml para sua máquina management cluster.
Implante o Bundle através da interface do Rancher:
Figure 33.1: Implantar Bundle através da interface do Rancher #

A partir daqui, selecione Ler de Arquivo e encontre o arquivo bundle.yaml no seu sistema.
Isso preencherá automaticamente o Bundle dentro da interface do Rancher.
Selecione Criar.
Após uma implantação bem-sucedida, seu Bundle deverá ser semelhante a:
Figure 33.2: Bundle implantado com sucesso #

Após a implantação bem-sucedida do Bundle, para monitorar o processo de fazer upgrade:

Verifique os logs do Upgrade Pod:
Agora, verifique os logs do Pod criado para fazer upgrade pelo helm-controller:
1. O nome do Pod seguirá o seguinte modelo - helm-install-longhorn-<random-suffix>
2. O Pod estará no namespace onde o recurso HelmChart foi implantado. No nosso caso, este é kube-system.
  Figure 33.3: Logs para o gráfico Longhorn que foi submetido a fazer upgrade com sucesso #
Verifique se a versão do HelmChart foi atualizada navegando até a seção HelmCharts do Rancher (More Resources → HelmCharts). Selecione o namespace onde o chart foi implantado; para este exemplo, seria kube-system.
Por fim, verifique se os Pods do Longhorn estão em execução.

Após realizar as validações acima, é seguro presumir que o Helm chart do Longhorn foi submetido a fazer upgrade para a versão 1.11.2.

33.1.6.2.3.4 Fazer upgrade do Helm chart usando uma ferramenta GitOps de terceiros #

Pode haver casos de uso em que os usuários desejem usar este procedimento de fazer upgrade com um fluxo de trabalho GitOps diferente do Fleet (por exemplo, Flux).

Para produzir os recursos necessários para o procedimento de fazer upgrade, você pode usar o script generate-chart-upgrade-data.sh para preencher o Fleet eib-charts-upgrader com os dados fornecidos pelo usuário. Para obter mais informações sobre como fazer isso, consulte Section 33.1.6.2.3.2, “Etapas de upgrade”.

Depois de ter a configuração completa, você pode usar kustomize para gerar uma solução funcional completa que você pode implantar em seu cluster:

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

kustomize build .

Se você quiser incluir a solução em seu fluxo de trabalho GitOps, você pode remover o arquivo fleet.yaml e usar o que restou como uma configuração Kustomize válida. Apenas não se esqueça de executar primeiro o script generate-chart-upgrade-data.sh, para que ele possa preencher a configuração Kustomize com os dados dos Helm charts que você deseja fazer upgrade.

Para entender como este fluxo de trabalho deve ser usado, pode ser útil consultar Section 33.1.6.2.3.1, “Visão geral” e Section 33.1.6.2.3.2, “Etapas de upgrade”.