Migrar Cluster Kubernetes Para a Versão v3
A versão v1 de plataforma do produto de Kubernetes está obsoleta, não sendo possível sua criação desde o dia 05/12/2025. Confira mais informações sobre esse processo aqui.
Esse tutorial descreve o processo de migração de um Cluster na versão v1 para a versão v3.
É necessário a criação de um segundo Cluster na versão v3 para realizar a migração. Não é possível realizar o procedimento no mesmo Cluster.
A região utilizada nesse tutorial é br-se1.
Clique aqui para mais informações sobre as versões de plataforma do produto de Kubernetes.
Este tutorial é um guia geral de como realizar a migração. 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.
Nesse tutorial, iremos utilizar dois Clusters Kubernetes:
cluster-v1: Cluster de origem, utilizando a versão de plataformav1e versãov1.32.3do Kubernetes.cluster-v3: Cluster de destino, utilizando a versão da plataformav3e versãov1.32.10do Kubernetes.
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.
O Que Será Migrado
Os recursos a serem migrados do Cluster de origem (cluster-v1) para o Cluster de destino (cluster-v3) serão:
- Deployment:
default/nginx. - Load Balancer de Serviço com IP público:
default/nginx. - PVC:
default/nginx, montado no Deploymentdefault/nginx.
kubectl get deploy,service,pvc
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/nginx 1/1 1 1 104d
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/nginx LoadBalancer 10.103.53.93 201.23.71.247 80:30197/TCP 104d
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
persistentvolumeclaim/nginx Bound pvc-3b6e4065-e8cb-4177-91e9-b4f187e2446c 20Gi RWO cinder-storageclass <unset> 133m
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-migracao
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-migracao
start_validity: "2026-03-05T00: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-migracao
bucket: k8s-migracao
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 (cluster-v1 e cluster-v3). 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-migracao \
--secret-file ./credenciais-velero \
--use-volume-snapshots=false \
--use-node-agent \
--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
Não é possível manter o mesmo IP público de Load Balancers de Serviço. Um novo Load Balancer será criado com um novo endereço de IP. É responsabilidade do usuário final alterar qualquer outro serviço (DNS, por exemplo) que dependa do endereço de IP do Load Balancer.
As Annotations utilizadas em Load Balancers de Serviço da versão v1 serão ignoradas. As Annotations para configurar um Load Balancer de Serviço na versão v3 estão documentadas aqui.
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.
O processo de backup descrito aqui irá realizar o backup de todos os PVCs presentes no Cluster. Para mais informações de como controlar quais PVCs serão incluídos no backup, confira a documentação oficial do Velero.
No Cluster de origem (cluster-v1), rode o comando abaixo para criar o backup:
velero backup create backup-cluster-v1 \
--exclude-namespaces mgk-monitoring,kube-node-lease,kube-public,kube-system,velero
Verifique que o backup está completo com o comando abaixo. Essa operação pode demorar alguns minutos.
velero backup describe backup-cluster-v1
[...]
Phase: Completed
Restaurando o Backup no Cluster de Destino
No Cluster de destino (cluster-v3), verifique que o backup está disponível:
velero backup get backup-cluster-v1
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
backup-cluster-v1 Completed 0 0 2026-03-05 11:36:07 -0300 -03 29d default <none>
Caso seu backup inclua PVCs, é necessário configurar um ConfigMap para traduzir o nome do StorageClass presente na versão v1 para a versão v3.
Para isso, execute o comando abaixo para criar o ConfigMap. Ajuste conforme necessário caso possua um StorageClass com nome diferente.
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: change-storage-class-config
namespace: velero
labels:
velero.io/plugin-config: ""
velero.io/change-storage-class: RestoreItemAction
data:
# nome-storage-class-v1: nome-storage-class-v3
cinder-storageclass: mgc-csi-magalu-sc
EOF
Por último, realize a restauração do backup:
velero restore create --from-backup backup-cluster-v1
Restore request "backup-cluster-v1-20260305125202" submitted successfully.
Run `velero restore describe backup-cluster-v1-20260305125202` or `velero restore logs backup-cluster-v1-20260305125202` 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.
Verificando os Recursos
Após a conclusão do processo de restore, verifique se os recursos foram criados corretamente utilizando o comando abaixo (cluster-v3):
kubectl get deploy,service,pvc
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/nginx 1/1 1 1 26m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/nginx LoadBalancer 10.110.71.45 201.23.67.3 80:32223/TCP 26m
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
persistentvolumeclaim/nginx Bound pvc-68a24cfc-d468-48ec-a961-c13710ffdbc7 20Gi RWO mgc-csi-magalu-sc <unset> 26m
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-migracao
Revogue a API Key utilizada para acessar o bucket do Object Storage:
mgc object-storage api-key revoke <api-key-id>
Caso a migração seja concluída com sucesso, você pode deletar o Cluster de origem (cluster-v1) utilizando essa documentação.