Skip to main content

Upgrade de Versão do Kubernetes

Esta seção descreve o passo a passo para realizar o upgrade de versão de Clusters Kubernetes na Magalu Cloud, garantindo segurança e previsibilidade.

Será utilizada a CLI da MGC para realizar o processo de upgrade. O mesmo pode ser realizado via Terraform, SDK ou API, seguindo os mesmos parâmetros.

Não há suporte para o processo de rollback de versões. Uma vez iniciado, o Cluster e Node Pools terão a nova versão de maneira definitiva.

Pré-requisitos​

Permissões​

Verifique se você possui permissões adequadas no Tenant para gerenciar Clusters Kubernetes. O produto de Kubernetes utiliza uma Service Account que precisa do papel Editor configurado no Turia IAM para realizar operações como upgrade de versão. Caso o Turia IAM esteja habilitado na sua conta, siga o tutorial Integre o Kubernetes com o Turia IAM para configurar as permissões necessárias.

Saúde do Cluster​

Antes de iniciar o upgrade, confirme que o Cluster está em estado saudável e que não haja operações em andamento (criação, deleção ou manutenção).

Verifique o estado do Cluster com o comando abaixo:

mgc kubernetes cluster get <cluster-id>

[...]
status:
    message: ready
    state: Running

Verifique o estado dos Node Pools:

mgc kubernetes nodepool list --cluster-id <cluster-id>

[...]
status:
    messages:
    - ready
    state: Running

Caso o Cluster ou algum Node Pool não esteja no estado Running, aguarde a conclusão de operações pendentes antes de prosseguir com o upgrade.

Compatibilidade​

Antes de atualizar, consulte as notas de versão do Kubernetes da versão de destino para entender mudanças de comportamento e novas funcionalidades.

APIs do Kubernetes deprecadas podem deixar de funcionar após o upgrade. Você pode utilizar a ferramenta Pluto para identificar recursos que utilizam APIs deprecadas ou removidas nos seus manifests:

pluto detect-files -d ./manifests/ --target-versions k8s=<nova-versão>

Você também pode verificar diretamente os recursos do Cluster em execução:

pluto detect-helm -o wide --target-versions k8s=<nova-versão>
pluto detect-api-resources --target-versions k8s=<nova-versão>

Atualize as versões de API do Kubernetes nos seus manifests YAML para versões suportadas pela versão de destino do Kubernetes. Consulte o guia de deprecação de APIs do Kubernetes para referência.

É obrigatório realizar o upgrade de versões minor sequencialmente (ex: v1.30 → v1.31 → v1.32). Não é possível pular versões minor.

Também é possível fazer upgrade entre versões patch (ex: v1.32.3 → v1.32.10).

Consulte aqui as versões disponíveis do Kubernetes na Magalu Cloud.

Backup​

Antes de iniciar o upgrade, garanta que você possui backups ou estratégias de rollback definidos para o seu Cluster. Algumas recomendações:

Você pode utilizar a ferramenta Velero para realizar o backup dos recursos e volumes do seu Cluster. O Velero permite backup e restauração de recursos Kubernetes e volumes persistentes.

Mantenha seus manifestos do Kubernetes versionados em um repositório de versionamento de código para facilitar o rollback em caso de problemas.

Boas Práticas Gerais​

Exercite o processo de upgrade previamente em Clusters de ambientes de desenvolvimento ou homologação para identificar possíveis problemas antes de aplicar em produção.

Durante o upgrade, Nodes são recriados e Pods serão reagendados em diferentes Nodes, o que pode causar breves interrupções. Prefira janelas de manutenção em horários de menor uso da sua aplicação.

Garanta que seus Node Pools possuam mais de um Node para que, durante o upgrade, seus workloads possam ser reagendados em Nodes disponíveis, evitando indisponibilidade.

Configure Liveness and Readiness Probes em suas aplicações. Eles garantem que o Kubernetes só envie tráfego para Pods prontos e reinicie Pods com falhas, aumentando a resiliência durante o upgrade. Consulte a documentação do Kubernetes sobre Probes aqui.

PodDisruptionBudgets (PDBs) permitem definir a quantidade mínima de Pods que devem permanecer disponíveis durante operações como o upgrade de Nodes. Consulte a documentação do Kubernetes sobre PodDisruptionBudgets para configurar a disponibilidade dos seus workloads.

Status Cluster e Node Pool​

Durante o upgrade de Clusters e Node Pools, o Status no Portal aparece como "Desconhecido". Esse é um bug identificado e já estamos trabalhando para resolvê-lo.

Node Pool Status Desconhecido

Realizar o Upgrade do Control Plane (CLI)​

Após realizar o planejamento do upgrade de versão do Cluster, vamos iniciar o processo realizando o upgrade de versão do Control Plane.

O Control Plane pode estar somente uma versão minor à frente da versão dos Node Pools (N+1).

Durante o processo de upgrade de versão do Control Plane não será possível realizar alterações no Cluster e criar ou alterar Node Pools.

Com o comando abaixo, inicie o processo de upgrade do seu Cluster Kubernetes:

mgc kubernetes cluster update <cluster-id> --version <nova-versão>

version: <nova-versão>

Apenas uma instância do Control Plane é atualizada por vez, garantindo a disponibilidade do Cluster em todo o processo. Esta fase pode demorar até 60 minutos.

Com o comando abaixo, verifique que o processo de upgrade está sendo realizado:

mgc kubernetes cluster get <cluster-id> 

[...]
status:
    message: updating control plane
    state: Reconciling

Quando finalizado, o comando abaixo irá retornar a seguinte mensagem:

mgc kubernetes cluster get <cluster-id> 

[...]
status:
    message: ready
    state: Running

Você pode confirmar a nova versão do Control Plane com o comando abaixo:

mgc kubernetes cluster get <cluster-id> 

[...]
version: <nova-versão>

Caso o Cluster entre em algum estado de erro inesperado, entre em contato com o time de suporte da Magalu Cloud por aqui.

Realizar o Upgrade de Node Pools (CLI)​

Após realizar o upgrade do Control Plane, é necessário realizar o Upgrade de Node Pools.

Os Node Pools podem estar somente uma versão minor atrás da versão do Control Plane. Por exemplo, caso o Control Plane esteja na versão v1.34.0, os Node Pools poderão estar somente nas versões v1.33.x ou v1.34.0.

Não é possível alterar as informações do Node Pool durante o processo de upgrade.

É possível atualizar mais de um Node Pool ao mesmo tempo.

Caso o Node Pool esteja distribuído em mais de uma AZ (zona de disponibilidade), o processo irá atualizar todos os Nodes de uma AZ antes de iniciar a próxima. A ordem de escolha das AZs será feita de maneira aleatória.

Durante o upgrade, uma certa quantidade de Nodes extras serão adicionados ao Node Pool com a nova versão de Kubernetes e, quando estes estiverem operacionais, a mesma quantidade de Nodes com a antiga versão serão removidos. Esse processo se repete até que todos os Nodes do Node Pool estejam atualizados. A quantidade de Nodes extras adicionados, chamado do Max Surge, é de 10% da quantidade de Nodes do Node Pool, com o teto máximo de 20 Nodes.

Em média, cada Node demora cerca de 4 minutos para ser criado.

O processo de upgrade respeitará a política de PodDisruptionBudget configurada em seu workload. Porém, há um timeout máximo de 15 minutos para que todos os Pods sejam drenados corretamente do Node. Caso o timeout seja atingido, o Node será removido forçadamente. Esse processo pode impactar o Max Surge, atrasando o upgrade de Node Pools.

Com o comando abaixo, inicie o processo de upgrade do Node Pool:

mgc kubernetes nodepool update --cluster-id <cluster-id> --node-pool-id <nodepool-id> --version <nova-versão> 

[...]
version: <nova-versão>

Com o comando abaixo, verifique que o processo de upgrade está sendo realizado:

mgc kubernetes nodepool get --cluster-id <cluster-id> --node-pool-id <nodepool-id>

[...]
status:
  messages:
    - updating node pool
  state: Reconciling

Quando finalizado, o comando abaixo irá retornar a seguinte mensagem:

mgc kubernetes nodepool get --cluster-id <cluster-id> --node-pool-id <nodepool-id>

[...]
status:
  messages:
  - ready
  state: Running

Você pode confirmar a nova versão do Node Pool com o comando abaixo:

mgc kubernetes nodepool get --cluster-id <cluster-id> --node-pool-id <nodepool-id>

[...]
version: <nova-versão>

Caso o Node Pool entre em algum estado de erro inesperado, entre em contato com o time de suporte da Magalu Cloud por aqui.

Validar o Cluster​

Após a conclusão do upgrade, orientamos a realizar algumas validações para garantir que o Cluster está operando corretamente.

Verifique a versão atual do Cluster com o comando abaixo:

kubectl version | grep Server

Valide os workloads:

  • Pods em estado Running
  • Services respondendo corretamente
  • Jobs e CronJobs executando normalmente
  • PVCs em estado Bound

Confira logs, métricas e dashboards para identificar possíveis anomalias ou necessidades de atualização.

Documente o upgrade realizado (versão, data, impactos).