Migrar Cluster Kubernetes
O produto de Kubernetes da Magalu Cloud ainda não possui a funcionalidade de upgrade de versões do Kubernetes, sendo necessário criar um novo Cluster e migrar manualmente os recursos do Cluster antigo, processo que será abordado neste tutorial.
O procedimento descrito aqui também é recomendado para migrar o Cluster Kubernetes da versão v1 para a versão v3 da plataforma de Kubernetes da Magalu Cloud.
A região utilizada nesse tutorial é br-se1.
Clique aqui para mais informações sobre as versões de plataforma do produto de Kubernetes.
Durante a migração da versão v1 para a versão v3, não há possibilidade de migrar IPs de Load Balancers ou Volumes Persistentes, sendo necessário criar esses recursos novamente no Cluster de destino.
Este tutorial é um guia geral de como realizar o backup e restauração entre dois Clusters diferentes. O processo será único para cada caso, dependendo da carga produtiva do seu Cluster. Caso haja alguma dúvida, entre em contato com time da Magalu Cloud.
Este tutorial não aborda a migração de dados que não utilizem PVCs da versão v2 ou v3, como volumes NFS, volumes de Nodes montados diretamente em Pods ou PVCs criados em um Cluster versão v1.
Nesse tutorial, iremos utilizar dois Clusters Kubernetes:
cluster01: Cluster de origem, no qual será feito o backup. Utiliza o Kubernetes versãov1.31.7.cluster02: Cluster de destino, no qual será feito a restauração do backup. Utiliza o Kubernetes versãov1.32.3.
A ferramenta Velero será utilizada para backup e restauração.
Plano de Migração
Para mais informações sobre o planejamento de migrações, consulte o tutorial Planejamento Para Migração de Clusters Kubernetes.
Armazenando o Backup no Object Storage
Utilizaremos o serviço de Object Storage para armazenar os dados durante o processo de backup e restauração.
Com a CLI da MGC, crie uma API Key para gerenciarmos o bucket:
mgc object-storage api-key create --name k8s-backup
Utilizando o ID da chave retornado, configure-a para ser utilizada nas próximas operações:
mgc object-storage api-key set <api-key-id>
Anote as informações da chave para integração com a solução de backup (key_pair_id e key_pair_secret):
mgc object-storage api-key get <api-key-id>
description: created from CLI
key_pair_id: [redacted]
key_pair_secret: [redacted]
name: k8s-backup
start_validity: "2025-12-01T00:00:00Z"
tenant_name: [redacted]
uuid: [redacted]
Com as informações acima, crie um arquivo chamado credenciais-velero com a seguinte estrutura:
[default]
aws_access_key_id = <key-par-id>
aws_secret_access_key = <key-pair-secret>
Por fim, crie o bucket que será utilizado para o backup e restore. Utilize um nome único, de acordo com as regras de nomenclatura.
mgc object-storage buckets create --bucket k8s-backup
bucket: k8s-backup
bucket_is_prefix: false
enable_versioning: true
Instalando o Velero
Siga o passo a passo da instalação da CLI do Velero.
Com o comando abaixo, instale o Velero em ambos os Clusters (cluster01 e cluster02). Utilize o nome do bucket criado anteriormente no parâmetro --bucket.
velero install \
--provider aws \
--plugins velero/velero-plugin-for-aws:v1.2.1 \
--bucket k8s-backup \
--secret-file ./credenciais-velero \
--use-volume-snapshots=false \
--backup-location-config region=br-se1,s3Url=https://br-se1.magaluobjects.com
[...]
Velero is installed! ⛵ Use 'kubectl logs deployment/velero -n velero' to view the status.
Utilize os parâmetros s3Url=https://br-ne1.magaluobjects.com e region=br-ne1 caso esteja utilizando a região br-ne1.
Load Balancers de Serviço
Caso esteja migrando da versão v1 para a versão v3 da plataforma Kubernetes da Magalu Cloud, não é possível manter o mesmo IP público do Load Balancer de Serviço. Um novo Load Balancer será criado.
As Annotations utilizadas em Load Balancers de Serviço da versão v1 serão ignoradas.
Caso queira manter o mesmo IP público de um Load Balancer de Serviço durante a migração, siga as instruções abaixo.
No Cluster de origem (cluster01), adicione a Annotation magalu.cloud/public-ip-reclaim-policy=retain no Service do tipo LoadBalancer. Neste exemplo, o nome do Service é nginx:
kubectl annotate service nginx magalu.cloud/public-ip-reclaim-policy=retain
Encontre o IP público do Service do tipo LoadBalancer com o comando abaixo:
kubectl get service nginx
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx LoadBalancer 10.96.137.0 201.23.76.194 80:31872/TCP 15h
Com a CLI da MGC, anote o ID do IP público utilizando o valor do campo EXTERNAL-IP do comando acima:
mgc network public-ips list | grep '201.23.76.194' -C10
[...]
- created_at: 2025-12-01T20:03:47.037527
description: Public IP for Load Balancer.
error: null
external_id: null
# este campo
id: cd6fed96-49cc-4a9a-b0b9-56f37ad40175
port_id: null
project_type: default
public_ip: 201.23.76.194
status: in_use
tenant_id: [redacted]
updated: 2025-12-01T20:03:47.037528
vpc_id: 00000000-0000-0000-0000-000000000000
[...]
No Cluster de destino (cluster02), crie um ConfigMap no Namespace velero para modificar o recurso Service durante o processo de restauração para incluir a Annotation magalu.cloud/load-balancer-public-ip-id=<ip-id>. Crie uma entrada para cada Service, especificando corretamente o Name, Namespace e ID do IP:
Primeiramente, crie um arquivo chamado resource-modifier.yaml:
version: v1
resourceModifierRules:
- conditions:
groupResource: services
# nome do Service
resourceNameRegex: "^nginx$"
# Namespace do Service
namespaces:
- default
patches:
- operation: add
path: "/metadata/annotations/magalu.cloud~1load-balancer-public-ip-id"
# ID do IP
value: "cd6fed96-49cc-4a9a-b0b9-56f37ad40175"
E crie um ConfigMap à partir do arquivo:
kubectl -n velero create configmap resource-modifier --from-file resource-modifier.yaml
Realizando o Backup No Cluster de Origem
Alterações no Cluster após a realização do backup não serão refletidas no processo de restauração. Após o backup, garanta que os recursos do Cluster de origem não sejam alterados.
No Cluster de origem (cluster01), rode o comando abaixo para criar o backup:
velero backup create backup-cluster01 \
--exclude-namespaces mgk-monitoring,kube-node-lease,kube-public,kube-system,velero
Caso esteja migrando da versão v1 para a versão v3 da plataforma Kubernetes da Magalu Cloud, não é possível reutilizar o mesmo volume no Cluster de destino. Por esse motivo, indicamos não migrar os PVCs e PVs. Caso esteja realizando o backup em um Cluster na versão v1, utilize o comando abaixo para criar o backup:
velero backup create backup-cluster01 \
--exclude-namespaces mgk-monitoring,kube-node-lease,kube-public,kube-system,velero \
--exclude-resources persistentvolumeclaims,persistentvolumes
Verifique que o backup está completo com o comando abaixo. Essa operação pode demorar alguns minutos.
velero backup desrcibe backup-cluster01
[...]
Phase: Completed
Restaurando o Backup no Cluster de Destino
No Cluster de destino (cluster02), verifique que o backup está disponível:
velero backup get backup-cluster01
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
backup-cluster01 Completed 0 0 2025-12-02 09:46:29 -0300 -03 29d default <none>
E realize a restauração do backup. Omita o argumento --resource-modifier-configmap caso não precise realizar a manutenção do IP público de Load Balancers de Serviço.
velero restore create --from-backup backup-cluster01 --resource-modifier-configmap resource-modifier
Restore request "backup-cluster01-20251202101513" submitted successfully.
Run `velero restore describe backup-cluster01-20251202101513` or `velero restore logs backup-cluster01-20251202101513` for more details.
Execute o primeiro comando indicado pelo Velero (velero restore describe backup-...) para verificar o status da restauração.
Alguns Warnings são esperados para recursos que já existem no Cluster de destino.
Load Balancers de Serviço
Caso você configurou um Load Balancer de Serviço para reutilizar o IP público no Cluster de destino, agora é necessário remover o recurso Service no Cluster de origem (cluster01) para que seja liberado o IP:
Execute o comando abaixo no Cluster de origem (cluster01):
kubectl delete service <service-name>
No Cluster de destino (cluster02), verifique que o Load Balancer reutilizou o IP correto:
kubectl get service nginx -w
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx LoadBalancer 10.101.113.233 <pending> 80:32640/TCP 108s
nginx LoadBalancer 10.101.113.233 201.23.76.194 80:32640/TCP 119s
Volumes Persistentes
Após a restauração do backup, os Pods no Cluster de destino (cluster02) que utilizarem PersistentVolumeClaims (PVCs) ficarão com o erro abaixo, indicando que o volume gerenciado serviço de Block Storage está em uso:
Warning FailedAttachVolume 2m27s (x8 over 37m) attachdetach-controller AttachVolume.Attach failed for volume "pvc-c21d43f4-d2d8-4e8e-a577-f62b4953022f" : rpc error: code = Internal desc = failed to attach volume 85e81c2c-b085-4b5c-8dc3-96bf0e59f4f1 with error {"message":"Volume must be available to attach","details":{"state":"in-use","allowed":["available"]},"slug":"volume_not_available"}
Para corrigir o erro, você deverá remover os Pods e os PVCs no Cluster de origem (cluster01), para que o volume seja liberado e anexado no Pod no Cluster de destino (cluster02). Após a remoção do PVC, o Pod irá funcionar normalmente.
O Pod no Cluster de destino (cluster02) que utilize o PVC deve estar na mesma zona de disponibilidade do volume.
Limpando os Recursos
Após o backup e restauração, caso deseje, realize a limpeza do seu ambiente.
Em ambos os Clusters, remova o Velero:
velero uninstall
Remova o bucket do Object Storage utilizado para o backup:
mgc object-storage buckets delete k8s-backup
Revogue a API Key utilizada para acessar o bucket do Object Storage:
mgc object-storage api-key revoke <api-key-id>