23 Controller de upgrade #

Um controlador do Kubernetes que faz upgrades dos seguintes componentes da plataforma SUSE Edge:

Sistema operacional (SUSE Linux Micro)
Kubernetes (K3s e RKE2)
Componentes adicionais (Rancher, Elemental, SUSE Security etc.)

O Controller de upgrade otimiza o processo de upgrade dos componentes mencionados acima, pois encapsula suas complexidades em um único recurso voltado para o usuário que funciona como um acionador de upgrade. Os usuários precisam apenas configurar esse recurso, e o Controller de upgrade cuida do restante.

Nota

Atualmente, o Controller de upgrade oferece suporte a upgrades da plataforma SUSE Edge apenas para clusters de gerenciamento não air-gapped. Consulte a Seção 23.7, “Limitações conhecidas” para obter mais informações.

23.1 Como o SUSE Edge usa o Controller de upgrade? #

O Controller de upgrade é essencial para automação das operações de "dia 2" (que antes eram manuais) necessárias para fazer upgrade dos clusters de gerenciamento de uma versão de lançamento do SUSE Edge para a seguinte.

Para atingir essa automação, o Controller de upgrade usa ferramentas como o System Upgrade Controller (Capítulo 22, System Upgrade Controller) e o Helm Controller.

Para obter mais detalhes de como o Controller de upgrade funciona, consulte a Seção 23.4, “Como funciona o Controller de upgrade?”.

Para saber as limitações conhecidas do Controller de upgrade, consulte a Seção 23.7, “Limitações conhecidas”.

Para obter informações sobre a diferença entre o Controller de upgrade e o System Upgrade Controller, consulte a Seção 23.2, “Comparação entre Controller de upgrade e System Upgrade Controller”.

23.2 Comparação entre Controller de upgrade e System Upgrade Controller #

O System Upgrade Controller (SUC) (Capítulo 22, System Upgrade Controller) é uma ferramenta de uso geral que propaga as instruções de upgrade para os nós específicos do Kubernetes.

Apesar de oferecer suporte a algumas operações de "dia 2" para a plataforma SUSE Edge, ele não abrange todas elas. Mesmo para as operações com suporte, os usuários ainda precisam configurar, manter e implantar manualmente vários planos do SUC, um processo propenso a erros que pode provocar problemas inesperados.

Isso levou à necessidade de uma ferramenta para automatizar e abstrair a complexidade de gerenciar várias operações de "dia 2" na plataforma SUSE Edge. E, assim, o Controller de upgrade foi desenvolvido. Ele simplifica o processo de upgrade com a introdução de um único recurso voltado para o usuário que conduz o upgrade. Os usuários precisam gerenciar apenas esse recurso, e o Controller de upgrade cuida do restante.

23.3 Instalando o Controller de upgrade #

23.3.1 Pré-requisitos #

Helm
cert-manager
System Upgrade Controller (Seção 22.2, “Instalando o System Upgrade Controller”)
Um cluster Kubernetes; seja K3s ou RKE2

23.3.2 Etapas #

Instale o gráfico Helm do Controller de upgrade no cluster de gerenciamento:

helm install upgrade-controller oci://registry.suse.com/edge/charts/upgrade-controller --version 303.0.1+up0.1.1 --create-namespace --namespace upgrade-controller-system

Valide a implantação do Controller de upgrade:

kubectl get deployment -n upgrade-controller-system

Valide o pod do Controller de upgrade:

kubectl get pods -n upgrade-controller-system

Valide os registros do pod do Controller de upgrade:

kubectl logs <pod_name> -n upgrade-controller-system

23.4 Como funciona o Controller de upgrade? #

Para fazer upgrade de uma versão do Edge, o Controller de upgrade lança dois novos recursos personalizados do Kubernetes:

UpgradePlan (Seção 23.5.1, “UpgradePlan”): criado pelo usuário; armazena as configurações referentes ao upgrade de uma versão do Edge.
ReleaseManifest (Seção 23.5.2, “ReleaseManifest”): criado pelo Controller de upgrade; armazena as versões de componente específicas a uma determinada versão de lançamento do Edge. Os usuários não devem editar esse arquivo.

O Controller de upgrade cria um recurso ReleaseManifest que armazena os dados do componente referentes à versão de lançamento do Edge especificada pelo usuário na propriedade releaseVersion do recurso UpgradePlan.

Usando os dados do componente do ReleaseManifest, o Controller de upgrade faz upgrade do componente da versão do Edge na seguinte ordem:

Sistema operacional (SO) (Seção 23.4.1, “Upgrade do sistema operacional”).
Kubernetes (Seção 23.4.2, “Upgrade do Kubernetes”).
Componentes adicionais (Seção 23.4.3, “Upgrades de componentes adicionais”).

Nota

Durante o processo de upgrade, o Controller de upgrade envia continuamente as informações de upgrade para o UpgradePlan criado. Para obter mais informações sobre como acompanhar o processo de upgrade, consulte Acompanhando o processo de upgrade (Seção 23.6, “Acompanhando o processo de upgrade”).

23.4.1 Upgrade do sistema operacional #

Para fazer upgrade do sistema operacional, o Controller de upgrade cria planos do SUC (Capítulo 22, System Upgrade Controller) com o seguinte gabarito de nomenclatura:

Para planos do SUC relacionados a upgrades de sistema operacional de nó do plano de controle: control-plane-<nome-do-so>-<versão-do-so>-<sufixo>.
Para planos do SUC relacionados a upgrades de sistema operacional de nó do worker: workers-<nome-do-so>-<versão-do-so>-<sufixo>.

Com base nesses planos, o SUC cria as cargas de trabalho em cada nó do cluster que faz o upgrade real do sistema operacional.

Dependendo do ReleaseManifest, o upgrade de sistema operacional pode incluir:

Atualizações somente de pacotes: para casos de uso em que a versão do sistema operacional não é alterada entre os lançamentos do Edge.
Migração completa do sistema operacional: para casos de uso em que a versão do sistema operacional é alterada entre os lançamentos do Edge.

O upgrade é feito um nó de cada vez, começando primeiro pelos nós do plano de controle. Apenas quando o upgrade do nó do plano de controle é concluído que o upgrade dos nós do worker é iniciado.

Nota

O Controller de upgrade configura os planos do SUC de sistema operacional para fazer uma drenagem dos nós do cluster, se o cluster tiver mais de um um nó do tipo especificado.

Para os clusters em que os nós do plano de controle são mais de um, e existe apenas um nó do worker, a drenagem será realizada somente para os nós do plano de controle e vice-versa.

Para obter informações sobre como desabilitar completamente as drenagens de nós, consulte a seção UpgradePlan (Seção 23.5.1, “UpgradePlan”).

23.4.2 Upgrade do Kubernetes #

Para fazer upgrade da distribuição Kubernetes de um cluster, o Controller de upgrade cria planos do SUC (Capítulo 22, System Upgrade Controller) com o seguinte gabarito de nomenclatura:

Para os planos do SUC relacionados a ugrades do Kubernetes em nós do plano de controle: control-plane-<versão-do-k8s>-<sufixo>.
Para os planos do SUC relacionados a upgrades do Kubernetes em nós do worker: workers-<versão-do-k8s>-<sufixo>.

Com base nesses planos, o SUC cria as cargas de trabalho em cada nó do cluster que faz o upgrade real do Kubernetes.

O upgrade do Kubernetes é feito um nó de cada vez, começando primeiro pelos nós do plano de controle. Apenas quando o upgrade do nó do plano de controle é concluído que o upgrade dos nós do worker é iniciado.

Nota

O Controller de upgrade configura os planos do SUC do Kubernetes para fazer uma drenagem dos nós do cluster, se o cluster tiver mais de um um nó do tipo especificado.

Para os clusters em que os nós do plano de controle são mais de um, e existe apenas um nó do worker, a drenagem será realizada somente para os nós do plano de controle e vice-versa.

Para obter informações sobre como desabilitar completamente as drenagens de nós, consulte a Seção 23.5.1, “UpgradePlan”.

23.4.3 Upgrades de componentes adicionais #

Atualmente, todos os componentes adicionais são instalados por gráficos Helm. Para ver a lista completa dos componentes de uma versão específica, consulte as Notas de lançamento (Seção 52.1, “Resumo”).

Para gráficos Helm implantados pelo EIB (Capítulo 11, Edge Image Builder), o Controller de upgrade atualiza o HelmChart CR existente de cada componente.

Para gráficos Helm implantados fora do EIB, o Controller de upgrade cria um recurso HelmChart para cada componente.

Após a criação/atualização do recurso HelmChart, o Controller de upgrade se baseia no helm-controller para detectar essa alteração e prosseguir com o upgrade real do componente.

O upgrade dos gráficos será feito em sequência de acordo com a ordem apresentada no ReleaseManifest. É possível também especificar mais valores no UpgradePlan. Se uma versão de gráfico permanecer inalterada no novo lançamento do SUSE Edge, o upgrade dele não será feito. Para obter mais informações sobre isso, consulte a Seção 23.5.1, “UpgradePlan”.

23.5 Extensões de API Kubernetes #

Extensões para a API Kubernetes lançadas pelo Controller de upgrade.

23.5.1 UpgradePlan #

O Controller de upgrade lança um novo recurso personalizado do Kubernetes chamado UpgradePlan.

O UpgradePlan atua como um mecanismo de instrução para o Controller de upgrade e oferece suporte às seguintes configurações:

releaseVersion: a versão de lançamento do Edge para a qual o upgrade do cluster deve ser feito. Ela deve seguir o controle de versão semântico e ser recuperada das Notas de lançamento (Seção 52.1, “Resumo”).
disableDrain (opcional): indica se o Controller de upgrade deve ou não desabilitar as drenagens de nós. Útil quando você tem cargas de trabalho com orçamentos de interrupção.
- Exemplo de desabilitação de drenagem de nó do plano de controle:
```
spec:
  disableDrain:
    controlPlane: true
```
- Exemplo de desabilitação de drenagem de nó do plano de controle e do worker:
```
spec:
  disableDrain:
    controlPlane: true
    worker: true
```
helm (opcional): especifica valores adicionais para componentes instalados pelo Helm.
Atenção
Somente é aconselhável usar esse campo para valores que sejam críticos aos upgrades. As atualizações nos valores de gráficos padrão deverão ser feitas depois que o upgrade dos respectivos gráficos for feito para a versão seguinte.
- Exemplo:
```
spec:
  helm:
  - chart: foo
    values:
      bar: baz
```

23.5.2 ReleaseManifest #

O Controller de upgrade lança um novo recurso personalizado do Kubernetes chamado ReleaseManifest.

O recurso ReleaseManifest é criado pelo Controller de upgrade e armazena os dados de componente referentes a uma versão de lançamento específica do Edge. Isso significa que o upgrade de cada versão de lançamento do Edge será representado por um recurso ReleaseManifest diferente.

Atenção

O Controller de upgrade sempre deve criar o ReleaseManifest.

Não é aconselhável criar manualmente ou editar os recursos ReleaseManifest . O usuários que decidirem por esse método devem fazê-lo por sua conta e risco.

O ReleaseManifest inclui os seguintes dados de componente, mas sem limitação:

Dados de sistema operacional: versão, arquiteturas suportadas, dados adicionais de upgrade etc.
Dados de distribuição Kubernetes: versões suportadas do RKE2/K3s
Dados de componentes adicionais: dados de gráficos Helm do SUSE (local, versão, nome etc.)

Para ver um exemplo da aparência de um ReleaseManifest, consulte a documentação upstream. Tenha em mente que se trata apenas de um exemplo, sem a intenção de criar um recurso ReleaseManifest válido.

23.6 Acompanhando o processo de upgrade #

Esta seção apresenta como acompanhar e depurar o processo de upgrade que o Controller de upgrade inicia após a criação do recurso UpgradePlan.

23.6.1 Geral #

Acesse as informações gerais sobre o estado do processo de upgrade em Condições de status do UpgradePlan.

Veja o status do recurso UpgradePlan da seguinte maneira:

kubectl get upgradeplan <upgradeplan_name> -n upgrade-controller-system -o yaml

Exemplo de execução do UpgradePlan:

apiVersion: lifecycle.suse.com/v1alpha1
kind: UpgradePlan
metadata:
  name: upgrade-plan-mgmt
  namespace: upgrade-controller-system
spec:
  releaseVersion: 3.3.1
status:
  conditions:
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Control plane nodes are being upgraded
    reason: InProgress
    status: "False"
    type: OSUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Kubernetes upgrade is not yet started
    reason: Pending
    status: Unknown
    type: KubernetesUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Rancher upgrade is not yet started
    reason: Pending
    status: Unknown
    type: RancherUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Longhorn upgrade is not yet started
    reason: Pending
    status: Unknown
    type: LonghornUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: MetalLB upgrade is not yet started
    reason: Pending
    status: Unknown
    type: MetalLBUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: CDI upgrade is not yet started
    reason: Pending
    status: Unknown
    type: CDIUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: KubeVirt upgrade is not yet started
    reason: Pending
    status: Unknown
    type: KubeVirtUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: NeuVector upgrade is not yet started
    reason: Pending
    status: Unknown
    type: NeuVectorUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: EndpointCopierOperator upgrade is not yet started
    reason: Pending
    status: Unknown
    type: EndpointCopierOperatorUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Elemental upgrade is not yet started
    reason: Pending
    status: Unknown
    type: ElementalUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: SRIOV upgrade is not yet started
    reason: Pending
    status: Unknown
    type: SRIOVUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Akri upgrade is not yet started
    reason: Pending
    status: Unknown
    type: AkriUpgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: Metal3 upgrade is not yet started
    reason: Pending
    status: Unknown
    type: Metal3Upgraded
  - lastTransitionTime: "2024-10-01T06:26:27Z"
    message: RancherTurtles upgrade is not yet started
    reason: Pending
    status: Unknown
    type: RancherTurtlesUpgraded
  observedGeneration: 1
  sucNameSuffix: 90315a2b6d

Aqui você vê todos os componentes para os quais o Controller de upgrade tentará programar um upgrade. Cada condição segue o gabarito abaixo:

lastTransitionTime: a hora em que a condição do componente mudou de um status para outro pela última vez.
message: mensagem que indica o estado atual do upgrade da condição do componente específico.
reason: o estado atual do upgrade da condição do componente específico. Os possíveis motivos incluem:
- Succeeded: o upgrade do componente específico foi bem-sucedido.
- Failed: falha no upgrade do componente específico.
- InProgress: o upgrade do componente específico está em andamento.
- Pending: o upgrade do componente específico ainda não foi programado.
- Skipped: o componente específico não foi encontrado no cluster, portanto, o upgrade dele será ignorado.
- Error: o componente específico encontrou um erro temporário.
status: o status do type (tipo) da condição atual, que pode ser True (Verdadeiro), False (Falso) ou Unknown (Desconhecido).
type: indicador do componente que está passando por upgrade.

O Controller de upgrade cria planos do SUC para as condições de componente do tipo OSUpgraded e KubernetesUpgraded. Para acompanhar em mais detalhes os planos do SUC criados para esses componentes, consulte a Seção 22.3, “Monitorando os planos do System Upgrade Controller”.

É possível acompanhar em mais detalhes todos os outros tipos de condição de componente visualizando os recursos criados para eles pelo helm-controller. Para obter mais informações, consulte a Seção 23.6.2, “Helm Controller”.

É possível marcar um UpgradePlan programado pelo Controller de upgrade como successful (bem-sucedido) se:

Não há condições de componente Pending ou InProgress.
A propriedade lastSuccessfulReleaseVersion aponta para a releaseVersion, que é especificada na configuração do UpgradePlan. O Controller de upgrade adiciona essa propriedade ao status do UpgradePlan após o processo de upgrade bem-sucedido.

Exemplo de UpgradePlan bem-sucedido:

apiVersion: lifecycle.suse.com/v1alpha1
kind: UpgradePlan
metadata:
  name: upgrade-plan-mgmt
  namespace: upgrade-controller-system
spec:
  releaseVersion: 3.3.1
status:
  conditions:
  - lastTransitionTime: "2024-10-01T06:26:48Z"
    message: All cluster nodes are upgraded
    reason: Succeeded
    status: "True"
    type: OSUpgraded
  - lastTransitionTime: "2024-10-01T06:26:59Z"
    message: All cluster nodes are upgraded
    reason: Succeeded
    status: "True"
    type: KubernetesUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Chart rancher upgrade succeeded
    reason: Succeeded
    status: "True"
    type: RancherUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Chart longhorn is not installed
    reason: Skipped
    status: "False"
    type: LonghornUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Specified version of chart metallb is already installed
    reason: Skipped
    status: "False"
    type: MetalLBUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Chart cdi is not installed
    reason: Skipped
    status: "False"
    type: CDIUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Chart kubevirt is not installed
    reason: Skipped
    status: "False"
    type: KubeVirtUpgraded
  - lastTransitionTime: "2024-10-01T06:27:13Z"
    message: Chart neuvector-crd is not installed
    reason: Skipped
    status: "False"
    type: NeuVectorUpgraded
  - lastTransitionTime: "2024-10-01T06:27:14Z"
    message: Specified version of chart endpoint-copier-operator is already installed
    reason: Skipped
    status: "False"
    type: EndpointCopierOperatorUpgraded
  - lastTransitionTime: "2024-10-01T06:27:14Z"
    message: Chart elemental-operator upgrade succeeded
    reason: Succeeded
    status: "True"
    type: ElementalUpgraded
  - lastTransitionTime: "2024-10-01T06:27:15Z"
    message: Chart sriov-crd is not installed
    reason: Skipped
    status: "False"
    type: SRIOVUpgraded
  - lastTransitionTime: "2024-10-01T06:27:16Z"
    message: Chart akri is not installed
    reason: Skipped
    status: "False"
    type: AkriUpgraded
  - lastTransitionTime: "2024-10-01T06:27:19Z"
    message: Chart metal3 is not installed
    reason: Skipped
    status: "False"
    type: Metal3Upgraded
  - lastTransitionTime: "2024-10-01T06:27:27Z"
    message: Chart rancher-turtles is not installed
    reason: Skipped
    status: "False"
    type: RancherTurtlesUpgraded
  lastSuccessfulReleaseVersion: 3.3.1
  observedGeneration: 1
  sucNameSuffix: 90315a2b6d

23.6.2 Helm Controller #

Esta seção explica como acompanhar os recursos criados pelo helm-controller.

Nota

As etapas a seguir consideram que o kubectl foi configurado para conectar-se ao cluster no qual o Controller de upgrade foi implantado.

Localize o recurso HelmChart para o componente específico:
```
kubectl get helmcharts -n kube-system
```

Usando o nome do recurso HelmChart, localize o pod de upgrade que foi criado pelo helm-controller:

kubectl get pods -l helmcharts.helm.cattle.io/chart=<helmchart_name> -n kube-system

# Example for Rancher
kubectl get pods -l helmcharts.helm.cattle.io/chart=rancher -n kube-system
NAME                         READY   STATUS      RESTARTS   AGE
helm-install-rancher-tv9wn   0/1     Completed   0          16m

Exiba os registros do pod específico do componente:
```
kubectl logs <pod_name> -n kube-system
```

23.7 Limitações conhecidas #

Os upgrades de clusters downstream ainda não são gerenciados pelo Controller de upgrade. Para obter mais informações sobre como fazer upgrade de clusters downstream, consulte o Capítulo 36, Clusters downstream.
O Controller de upgrade espera que os gráficos Helm adicionais do SUSE Edge implantados pelo EIB (Capítulo 11, Edge Image Builder) tenham o HelmChart CR implantado no namespace kube-system. Para isso, configure a propriedade installationNamespace no arquivo de definição do EIB. Para obter mais informações, consulte a documentação upstream.
Atualmente, o Controller de upgrade não tem como determinar a versão de lançamento do Edge que está em execução no cluster de gerenciamento. Insira uma versão de lançamento do Edge superior àquela que está em execução no cluster.
Atualmente, o Controller de upgrade oferece suporte apenas a upgrades de ambientes não air-gapped. Os upgrades air-gapped ainda não são possíveis.