documentation.suse.com / Documentação do SUSE Edge / Operações de dia 2 / Clusters downstream

36 Clusters downstream

 
Importante
Importante

As etapas a seguir não são válidas para clusters downstream gerenciados pelo SUSE Edge for Telco (Capítulo 37, SUSE Edge for Telco). Para obter orientação sobre o upgrade desses clusters, consulte a Seção 43.2, “Upgrades de cluster downstream”.

Esta seção apresenta as maneiras possíveis de executar operações de "dia 2" em diferentes partes do cluster downstream.

36.1 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:

  1. Seção 36.1.1, “Componentes”: componentes padrão usados para todas as operações de "dia 2".

  2. Seção 36.1.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".

  3. Seção 36.1.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.

  4. Seção 36.1.4, “Upgrade de sistema operacional”: descreve como fazer upgrades de sistema operacional com o Fleet.

  5. Seção 36.1.5, “Upgrade da versão do Kubernetes”: descreve como fazer upgrades de versão do Kubernetes com o Fleet.

  6. Seção 36.1.6, “Upgrade do gráfico Helm”: descreve como fazer upgrades de gráficos Helm com o Fleet.

36.1.1 Componentes

 

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

36.1.1.1 System Upgrade Controller (SUC)

 
Nota
Nota

Deve ser implantado em cada cluster downstream.

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.

Para obter informações sobre como implantar o SUC, determine primeiro o seu caso de uso (Seção 36.1.2, “Determinar seu caso de uso”) e depois consulte Instalação do System Upgrade Controller – GitRepo (Seção 22.2.1.1, “Instalação do System Upgrade Controller – GitRepo”) ou Instalação do System Upgrade Controller – Bundle (Seção 22.2.1.2, “Instalação do System Upgrade Controller – Bundle”).

36.1.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".

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

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

36.1.3 Fluxo de trabalho de dia 2

 

Veja abaixo o fluxo de trabalho de "dia 2" que deve ser seguido para fazer upgrading de um cluster downstream para uma versão específica do Edge.

  1. Upgrade de sistema operacional (Seção 36.1.4, “Upgrade de sistema operacional”)

  2. Upgrade de versão do Kubernetes (Seção 36.1.5, “Upgrade da versão do Kubernetes”)

  3. Upgrade de gráfico Helm (Seção 36.1.6, “Upgrade do gráfico Helm”)

36.1.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:

  1. Seção 36.1.4.1, “Componentes”: componentes adicionais usados pelo processo de upgrade.

  2. Seção 36.1.4.2, “Visão geral”: visão geral do processo de upgrade.

  3. Seção 36.1.4.3, “Requisitos”: requisitos do processo de upgrade.

  4. Seção 36.1.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.

36.1.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 36.1.1, “Componentes”).

36.1.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 do plano do SUC, que deve estar localizado no cluster downstream que precisa do upgrade de sistema operacional.

36.1.4.2 Visão geral

 

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

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

Nota
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
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 36.1.2, “Determinar seu caso de uso” para obter mais informações.

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

  1. Sempre use o comando cordon nos nós antes dos upgrades de sistema operacional.

  2. Sempre faça upgrade dos nós do plano de controle antes dos nós do worker.

  3. 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:

  1. O SUC reconcilia os planos do SUC de sistema operacional implantados e cria um Kubernetes Job em cada nó.

  2. O Kubernetes Job cria um systemd.service (Seção 36.1.4.1.1, “systemd.service”) para upgrade de pacote ou migração de sistema operacional.

  3. O systemd.service criado aciona o processo de upgrade de sistema operacional no nó específico.

    Importante
    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:

upgrade so downstream dia2 fleet

36.1.4.3 Requisitos

 

Geral:

  1. Máquina registrada no SCC: todos os nós do cluster downstream 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
    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.

  2. 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
      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:

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

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

 
Importante
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 downstream: para fazer isso, remova o cluster desejado da configuração de destino do GitRepo/Bundle existente 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 downstream, 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 36.1.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:

Para determinar o recurso que você deve usar, consulte a Seção 36.1.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 36.1.4.4.3, “Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros”.

36.1.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:

  1. Pela IU do Rancher: Seção 36.1.4.4.1.1, “Criação do GitRepo: IU do Rancher” (quando o Rancher está disponível).

  2. Pela implantação manual do recurso (Seção 36.1.4.4.1.2, “Criação do GitRepo: 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”.

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

36.1.4.4.1.2 Criação do GitRepo: manual
 

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

  2. Edite a configuração do GitRepo e especifique a lista de destinos desejados em spec.targets. Por padrão, os recursos GitRepo de suse-edge/fleet-examples NÃO são mapeados para clusters downstream.

    • Para corresponder todos os clusters, altere o destino do GitRepo padrão para:

      spec:
  targets:
  - clusterSelector: {}

    • Se preferir uma seleção mais granular de clusters, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

  3. Aplique o recurso GitRepo ao cluster de gerenciamento:

    kubectl apply -f os-upgrade-gitrepo.yaml

  4. 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.3.0  0/0
36.1.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:

  1. Pela IU do Rancher: Seção 36.1.4.4.2.1, “Criação do bundle – IU do Rancher” (quando o Rancher está disponível).

  2. Pela implantação manual do recurso (Seção 36.1.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”.

36.1.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
Importante

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

Para criar um bundle pela IU do Rancher:

  1. No canto superior esquerdo, clique em ☰ → Continuous Delivery (Entrega contínua).

  2. Vá para Advanced > Bundles (Avançado > Bundles).

  3. Selecione Create from YAML (Criar do YAML).

  4. Nesse local, você pode criar o bundle de uma das seguintes maneiras:

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

  5. Altere os clusters de destino para o Bundle:

    • Para corresponder todos os clusters downstream, altere o bundle padrão .spec.targets para:

      spec:
  targets:
  - clusterSelector: {}

    • Para mapeamentos mais granulares de clusters downstream, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

  6. Selecione Create (Criar).

36.1.4.4.2.2 Criação do bundle – manual
 

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

  2. Edite as configurações de destino do Bundle. Em spec.targets, insira a lista de destinos desejada. Por padrão, os recursos Bundle de suse-edge/fleet-examples NÃO são mapeados para clusters downstream.

    • Para corresponder todos os clusters, altere o destino do Bundle padrão para:

      spec:
  targets:
  - clusterSelector: {}

    • Se preferir uma seleção mais granular de clusters, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

  3. Aplique o recurso Bundle ao seu cluster de gerenciamento:

    kubectl apply -f os-upgrade-bundle.yaml

  4. Visualize o recurso Bundle criado no namespace fleet-default:

    kubectl get bundles -n fleet-default
36.1.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 36.1.4.1.1, “systemd.service”).

  • config-map.yaml é um ConfigMap que armazena as configurações consumidas pelo script upgrade.sh.

Importante
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 36.1.4.2, “Visão geral”).

36.1.5 Upgrade da versão do Kubernetes

 
Importante
Importante

Esta seção aborda os upgrades do Kubernetes para clusters downstream que NÃO foram criados por uma instância do Rancher (Capítulo 5, Rancher). Para obter informações sobre como fazer upgrade da versão do Kubernetes dos clusters criados pelo Rancher, consulte Upgrading and Rolling Back Kubernetes (Fazendo upgrade e rollback 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:

  1. Seção 36.1.5.1, “Componentes”: componentes adicionais usados pelo processo de upgrade.

  2. Seção 36.1.5.2, “Visão geral”: visão geral do processo de upgrade.

  3. Seção 36.1.5.3, “Requisitos”: requisitos do processo de upgrade.

  4. Seção 36.1.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.

36.1.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 36.1.1, “Componentes”).

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

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

36.1.5.2 Visão geral

 

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

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

Nota
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
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 36.1.2, “Determinar seu caso de uso” para obter mais informações.

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

  1. Sempre use o comando cordon nos nós antes dos upgrades do K8s.

  2. Sempre faça upgrade dos nós do plano de controle antes dos nós do worker.

  3. 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:

  1. O SUC reconcilia os planos do SUC do K8s implantados e cria um Kubernetes Job em cada nó.

  2. Dependendo da distribuição Kubernetes, o job cria um pod que executa a imagem de contêiner do rke2-upgrade (Seção 36.1.5.1.1, “rke2-upgrade”) ou do k3s-upgrade (Seção 36.1.5.1.2, “k3s-upgrade”).

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

  4. 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:

upgrade k8s downstream dia2 fleet

36.1.5.3 Requisitos

 

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

  2. 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
      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"
...

36.1.5.4 Upgrade do K8s: implantação do plano do SUC

 
Importante
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 downstream: para fazer isso, remova o cluster desejado da configuração de destino do GitRepo/Bundle existente 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 downstream, 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 36.1.5.2, “Visão geral”, os upgrades do Kubernetes são feitos enviando os planos do SUC ao cluster desejado de uma destas maneiras:

Para determinar o recurso que você deve usar, consulte a Seção 36.1.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 36.1.5.4.3, “Implantação do plano do SUC: fluxo de trabalho do GitOps de terceiros”.

36.1.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:

  1. Pela IU do Rancher: Seção 36.1.5.4.1.1, “Criação do GitRepo: IU do Rancher” (quando o Rancher está disponível).

  2. Pela implantação manual do recurso (Seção 36.1.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”.

36.1.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
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:

36.1.5.4.1.2 Criação do GitRepo: manual
 

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

  2. Edite a configuração do GitRepo e especifique a lista de destinos desejados em spec.targets. Por padrão, os recursos GitRepo de suse-edge/fleet-examples NÃO são mapeados para clusters downstream.

    • Para corresponder todos os clusters, altere o destino do GitRepo padrão para:

      spec:
  targets:
  - clusterSelector: {}

    • Se preferir uma seleção mais granular de clusters, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

  3. Aplique os recursos GitRepo ao cluster de gerenciamento:

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

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

  4. 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
36.1.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:

  1. Pela IU do Rancher: Seção 36.1.5.4.2.1, “Criação do bundle – IU do Rancher” (quando o Rancher está disponível).

  2. Pela implantação manual do recurso (Seção 36.1.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”.

36.1.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
Importante

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

Para criar um bundle pela IU do Rancher:

  1. No canto superior esquerdo, clique em ☰ → Continuous Delivery (Entrega contínua).

  2. Vá para Advanced > Bundles (Avançado > Bundles).

  3. Selecione Create from YAML (Criar do YAML).

  4. Nesse local, você pode criar o bundle de uma das seguintes maneiras:

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

  5. Altere os clusters de destino para o Bundle:

    • Para corresponder todos os clusters downstream, altere o bundle padrão .spec.targets para:

      spec:
  targets:
  - clusterSelector: {}

    • Para mapeamentos mais granulares de clusters downstream, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

  6. Selecione Create (Criar).

36.1.5.4.2.2 Criação do bundle – manual
 

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

  2. Edite as configurações de destino do Bundle. Em spec.targets, insira a lista de destinos desejada. Por padrão, os recursos Bundle de suse-edge/fleet-examples NÃO são mapeados para clusters downstream.

    • Para corresponder todos os clusters, altere o destino do Bundle padrão para:

      spec:
  targets:
  - clusterSelector: {}

    • Se preferir uma seleção mais granular de clusters, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

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

  4. 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
36.1.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
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 versão do Kubernetes, consulte a visão geral (Seção 36.1.5.2, “Visão geral”) do procedimento de atualização com o Fleet.

36.1.6 Upgrade do gráfico Helm

 

Esta seção aborda as seguintes partes:

  1. Seção 36.1.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.

  2. Seção 36.1.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.

36.1.6.1 Preparação para ambientes air-gapped

 
36.1.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:

  1. Hospede os recursos do Fleet do seu gráfico em um servidor Git local que possa ser acessado pelo cluster de gerenciamento.

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

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

  1. 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).

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

36.1.6.1.3 Criar o arquivo de imagens da versão do Edge
 

Em uma máquina com acesso à Internet:

  1. Torne o edge-save-images.sh executável:

    chmod +x edge-save-images.sh

  2. Gere o arquivo de imagens:

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

  3. Esse procedimento cria um arquivo pronto para carregamento chamado edge-images.tar.gz.

    Nota
    Nota

    Se a opção -i|--images foi especificada, o nome do arquivo pode ser diferente.

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

    scp edge-images.tar.gz <user>@<machine_ip>:/path
36.1.6.1.4 Criar o arquivo de imagens de gráfico OCI do Edge
 

Em uma máquina com acesso à Internet:

  1. Torne o edge-save-oci-artefacts.sh executável:

    chmod +x edge-save-oci-artefacts.sh

  2. Gere o arquivo de imagens de gráfico OCI:

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

  3. Esse procedimento cria um arquivo chamado oci-artefacts.tar.gz.

    Nota
    Nota

    Se a opção -a|--archive foi especificada, o nome do arquivo pode ser diferente.

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

    scp oci-artefacts.tar.gz <user>@<machine_ip>:/path
36.1.6.1.5 Carregar as imagens da versão do Edge para sua máquina air-gapped
 

Na máquina air-gapped:

  1. Faça login no seu registro particular (se necessário):

    podman login <REGISTRY.YOURDOMAIN.COM:PORT>

  2. Torne o edge-load-images.sh executável:

    chmod +x edge-load-images.sh

  3. 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
    Nota

    Desse modo, todas as imagens do edge-images.tar.gz serão carregadas, remarcadas e enviadas ao registro especificado na opção --registry.

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

Na máquina air-gapped:

  1. Faça login no seu registro particular (se necessário):

    podman login <REGISTRY.YOURDOMAIN.COM:PORT>

  2. Torne o edge-load-oci-artefacts.sh executável:

    chmod +x edge-load-oci-artefacts.sh

  3. Descompacte o arquivo oci-artefacts.tar.gz copiado:

    tar -xvf oci-artefacts.tar.gz

  4. Isso cria um diretório com o gabarito de nomenclatura edge-release-oci-tgz-<data>.

  5. 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
    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
36.1.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)

36.1.6.2 Procedimento de upgrade

 

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

  1. Seção 36.1.6.2.1, “Eu tenho um novo cluster e desejo implantar e gerenciar um gráfico Helm do Edge”

  2. Seção 36.1.6.2.2, “Quero fazer upgrade de um gráfico Helm gerenciado pelo Fleet”

  3. Seção 36.1.6.2.3, “Quero fazer upgrade de um gráfico Helm implantado pelo EIB”

Importante
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 36.1.6.2.1, “Eu tenho um novo cluster e desejo implantar e gerenciar um gráfico Helm do Edge”.

36.1.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:

  1. Seção 36.1.6.2.1.1, “Preparar os recursos do Fleet para seu gráfico”.

  2. Seção 36.1.6.2.1.2, “Implantar o Fleet para seu gráfico”.

  3. Seção 36.1.6.2.1.3, “Gerenciar o gráfico Helm implantado”.

36.1.6.2.1.1 Preparar os recursos do Fleet para seu gráfico
 

  1. Adquira os recursos do Fleet do gráfico com base na tag da versão do Edge que deseja usar.

  2. Navegue até a instância do Fleet do gráfico Helm (fleets/day2/chart-templates/<gráfico>).

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

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

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

36.1.6.2.1.2 Implantar o Fleet para seu gráfico
 

Você pode implantar a instância do Fleet para seu gráfico usando o GitRepo (Seção 36.1.6.2.1.2.1, “GitRepo”) ou o bundle (Seção 36.1.6.2.1.2.2, “Bundle”).

Nota
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).

36.1.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-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: {}
36.1.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
Nota

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

  1. Navegue até o gabarito de gráfico longhorn do Fleet:

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

  2. 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:
# Matches all downstream clusters
- clusterSelector: {}
EOF

    Para uma seleção mais granular de clusters downstream, consulte Mapping to Downstream Clusters (Mapeando para clusters downstream).

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

    Nota
    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-default -o - longhorn-bundle > longhorn-bundle.yaml

  4. Navegue até o gabarito de gráfico longhorn-crd do Fleet:

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

  5. 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:
# Matches all downstream clusters
- clusterSelector: {}
EOF

  6. 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-default -o - longhorn-crd-bundle > longhorn-crd-bundle.yaml

  7. 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 downstream especificados.

36.1.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 36.1.6.2.2, “Quero fazer upgrade de um gráfico Helm gerenciado pelo Fleet”.

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

  1. 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”).

  2. 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”).

  3. Depois de confirmar e enviar as alterações ao repositório, será acionado um upgrade do gráfico Helm desejado.

36.1.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:

36.1.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:

  1. Obter localmente os arquivos para cada gráfico Helm que precisa de upgrade.

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

  3. 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 downstream desejado.

Esses recursos incluem:

  1. Um conjunto de segredos com os dados do gráfico Helm fornecidos pelo usuário.

  2. 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 downstream dia2 fleet
36.1.6.2.3.2 Etapas de upgrade
 

  1. Clone o repositório suse-edge/fleet-examples da tag da versão correta.

  2. Crie um diretório para armazenar um ou mais arquivos dos gráficos Helm enviados.

    mkdir archives

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

  4. Em Assets (Ativos) da tag da versão desejada, faça download do script generate-chart-upgrade-data.sh.

  5. 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
    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:

  1. 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
      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).

  2. 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 match all downstream clusters
- clusterSelector: {}
EOF

      Para obter informações sobre como mapear clusters de destino, consulte a documentação upstream.

    4. Use 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 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 36.1.6.2.3.1, “Visão geral”.

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

Importante
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 downstream, garantindo que não haja conflitos com versões futuras.

36.1.6.2.3.3 Exemplo
 
Nota
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 downstream. 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 chamado doc-example 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 responsável pelo gerenciamento do doc-example seja air-gapped, sem suporte a servidor Git local e com uma instalação ativa do Rancher.

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

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

  2. Crie um diretório para armazenar o arquivo de upgrade do Longhorn.

    mkdir archives

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

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

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

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

  7. 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: doc-example
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-default -o - eib-charts-upgrade > bundle.yaml

    4. Agora transfira o bundle.yaml para a máquina do cluster de gerenciamento.

  8. Implante o bundle usando a IU do Rancher:

    exemplo 1 upgrade gráfico helm dia2
    Figura 36.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).

  9. Após a implantação bem-sucedida, o bundle terá uma aparência similar a esta:

    exemplo 2 upgrade gráfico helm dia2
    Figura 36.2: Bundle implantado com sucesso
     

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

  1. Consulte os registros do pod de upgrade:

    downstream exemplo 3 upgrade gráfico helm dia2

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

      downstream exemplo 4 upgrade gráfico helm dia2
      Figura 36.3: Registros do gráfico do Longhorn atualizado com sucesso
       

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

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

36.1.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 36.1.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 36.1.6.2.3.1, “Visão geral” e a Seção 36.1.6.2.3.2, “Etapas de upgrade”.

Documentation survey