claude-plugins/infraestrutura/skills/vm-migration/SKILL.md

name, description, author, version, quality_score, user_invocable, desk_task, allowed-tools, dependencies

name	description	author	version	quality_score	user_invocable	desk_task	allowed-tools	dependencies
vm-migration	Migração zero-downtime de workloads CWP/EasyPanel para Proxmox VMs seguindo Migration-Plan-OptionA. Use when user mentions "migrate to proxmox", "cwp migration", "easypanel migration", "workload migration".	Descomplicar® Crescimento Digital	1.0.0	75	true	1712	Task, Read, Bash	ssh-unified notebooklm proxmox-setup pbs-config

VM Migration

Migração zero-downtime de workloads CWP e EasyPanel para Proxmox VMs seguindo Migration-Plan-OptionA com safety nets e rollback procedures.

Quando Usar

• Migrar servidores CWP para VMs Proxmox
• Migrar containers EasyPanel para VMs Proxmox
• Executar Migration-Plan-OptionA (3 fases)
• Migração phased com validation periods
• Zero-downtime para clientes production

Sintaxe

/vm-migration <source-type> <source-host> [--phase 1|2|3] [--batch-size 5] [--validate-days 7]

Exemplos

# Fase 1: EasyPanel migration (batch 5 containers)
/vm-migration easypanel easy.descomplicar.pt --phase 1 --batch-size 5

# Fase 2: CWP migration com 7 dias validation
/vm-migration cwp server.descomplicar.pt --phase 2 --validate-days 7

# Fase 3: Apenas confirmar (sem migração)
/vm-migration finalize --phase 3

Knowledge Sources (Consultar SEMPRE)

NotebookLM Proxmox Research

mcp__notebooklm__notebook_query \
  notebook_id:"276ccdde-6b95-42a3-ad96-4e64d64c8d52" \
  query:"proxmox migration cwp easypanel docker lxc zero downtime"

Hub Docs

• Hub/05-Projectos/Cluster Descomplicar/Planning/Migration-Plan-OptionA.md
• Fase 1: EasyPanel (Week 1-2)
• Fase 2: CWP (Week 3-6, 7 dias validation)
• Fase 3: Cluster + cleanup (Week 7-8)

Migration-Plan-OptionA Overview

Timeline: 8 semanas Strategy: Phased migration com safety nets Rollback: Disponível em cada fase

Week 1-2: FASE 1 - EasyPanel Migration
├── Backup EasyPanel → PBS
├── Create Docker VM Proxmox
├── Migrate containers (batch 5-10)
├── DNS cutover gradual
└── Validation + Rollback window

Week 3-6: FASE 2 - CWP Migration
├── 7 dias safety net (server intacto)
├── Create AlmaLinux 8 VM
├── Migrate CWP accounts (batch)
├── Validate sites + email
├── DNS cutover (TTL 300s)
└── Rollback até Day 7

Week 7-8: FASE 3 - Cluster Formation
├── Prepare server.descomplicar.pt as Node A
├── Form cluster (pvecm)
├── Configure HA groups
├── Live migration tests
└── Cleanup legacy servers

Workflow Completo

PRE-MIGRATION (Todas Fases)

1. Backup Strategy Validation

# Verificar PBS configurado
pvesm status | grep pbs

# Criar backup point actual
vzdump --storage pbs-main --all 1 --mode snapshot

# Verificar 3-2-1 compliance:
# - Original: source server
# - Backup 1: PBS Node B
# - Backup 2: PBS Node A remote sync (ou VPS backup)

2. Documentar Estado Actual

# CWP: Listar contas
/scripts/list_accounts > /tmp/cwp-accounts.txt

# EasyPanel: Listar services
curl -s http://localhost:3000/api/trpc/projects.list | jq > /tmp/easypanel-services.json

# DNS TTLs (baixar para 300s ANTES de migration)
# Verificar em: dns.descomplicar.pt ou Cloudflare

3. Comunicar Clientes (se downtime esperado)

• Email 48h antes
• Status page update
• Janela de manutenção agendada

---

FASE 1: EasyPanel Migration (Week 1-2)

Target: Migrar 108 containers Docker para VM Proxmox

1.1 Criar VM Docker Host

# Via Proxmox CLI
qm create 200 \
  --name easypanel-docker \
  --memory 32768 \
  --cores 8 \
  --net0 virtio,bridge=vmbr0 \
  --scsi0 rpool/vm-disks:200 \
  --ostype l26 \
  --boot order=scsi0

# Install Ubuntu 24.04 LTS
# Via Cloud-Init ou ISO manual

1.2 Instalar Docker + EasyPanel

# SSH to VM
ssh root@10.10.10.200

# Docker
curl -fsSL https://get.docker.com | sh

# EasyPanel
curl -sSL https://get.easypanel.io | sh

1.3 Backup Containers Actuais

# Em easy.descomplicar.pt
# Backup docker volumes
tar -czf /tmp/easypanel-volumes.tar.gz /var/lib/easypanel/projects

# Transfer para PBS ou storage temporário
scp /tmp/easypanel-volumes.tar.gz root@cluster.descomplicar.pt:/mnt/migration/

1.4 Migrar Containers (Batch 5-10)

Batch 1 (não-críticos para teste):

# Containers teste: dev environments, staging
# IDs: 1-5

# Por cada container:
1. Exportar env vars do EasyPanel
2. Exportar docker-compose.yml
3. Copiar volumes
4. Recriar em novo EasyPanel
5. Testar health endpoint
6. DNS cutover se OK

Workflow Batch:

# Script semi-automatizado
for container_id in 1 2 3 4 5; do
  # Export config
  curl -s http://easy.descomplicar.pt:3000/api/trpc/services.get \
    -d "serviceId=$container_id" > config_$container_id.json

  # Copiar volumes
  rsync -avz /var/lib/easypanel/projects/$container_id/ \
    root@10.10.10.200:/var/lib/easypanel/projects/$container_id/

  # Recriar service (via EasyPanel API ou UI)

  # Test
  curl -I http://10.10.10.200:PORT/health

  # DNS cutover (se health OK)
  # Actualizar DNS para apontar para 10.10.10.200 (via NAT port forward)
done

1.5 Validation (24-48h por batch)

# Monitoring:
- Uptime checks (UptimeRobot ou similar)
- Error rates (logs)
- Performance (response time <500ms)
- Cliente feedback

# Rollback triggers:
- >2 containers falham consecutivamente
- Cliente reporta down
- Health checks fail >10min

1.6 DNS Cutover

# Baixar TTL para 300s (5min) 24h ANTES
# Ex: Cloudflare ou dns.descomplicar.pt

# Cutover:
A record: old-ip → NAT port forward para 10.10.10.200:PORT

# Monitorizar por 1h
# Reverter se problemas

1.7 Rollback Procedure (se necessário)

# Reverter DNS (TTL 300s = 5min propagação)
# Reactivar container antigo
# Investigar causa falha
# Re-tentar após fix

Batch 2-N: Repetir até 108 containers migrados.

---

FASE 2: CWP Migration (Week 3-6)

Target: Migrar 39 vhosts CWP para VM AlmaLinux 8

CRITICAL: 7 dias safety net - server.descomplicar.pt intacto

2.1 Criar VM AlmaLinux 8 + CWP

qm create 300 \
  --name cwp-legacy \
  --memory 16384 \
  --cores 6 \
  --net0 virtio,bridge=vmbr0 \
  --scsi0 rpool/vm-disks:150 \
  --ostype l26

# Instalar AlmaLinux 8
# Instalar CWP7
wget http://centos-webpanel.com/cwp-el8-latest
sh cwp-el8-latest

2.2 Backup CWP Accounts

# Em server.descomplicar.pt
for account in $(cat /tmp/cwp-accounts.txt); do
  /scripts/pkgacct $account
done

# Transfer backups
rsync -avz /home/backup-*/cpmove-*.tar.gz \
  root@cluster.descomplicar.pt:/mnt/migration/cwp/

2.3 Migrar Contas (Batch 3-5 contas)

Workflow por conta:

# 1. Restore backup em VM CWP
scp /mnt/migration/cwp/cpmove-ACCOUNT.tar.gz root@10.10.10.300:/home/

# 2. Restore via CWP
/scripts/restorepkg ACCOUNT

# 3. Validar:
- Site carrega (HTTP 200)
- Database conecta
- Email funciona (send test)
- SSL certificado válido

# 4. DNS cutover (TTL 300s)
A record: site.com → 10.10.10.300 (via NAT port forward)

# 5. Monitorizar 24h

2.4 Validation Period (7 dias)

# Days 1-7 após migration:
- Server antigo (server.descomplicar.pt) INTACTO
- Rollback instantâneo se problema critical
- Cliente pode reverter DNS manualmente se necessário

# Day 7: Confirmar com Emanuel
# Se tudo OK → proceder cleanup
# Se problemas → extend validation ou rollback completo

2.5 Email Migration

# Por cada conta CWP:

# 1. Backup mailboxes
tar -czf /tmp/mail-ACCOUNT.tar.gz /home/ACCOUNT/mail/

# 2. Transfer
scp /tmp/mail-ACCOUNT.tar.gz root@10.10.10.300:/tmp/

# 3. Restore
cd /home/ACCOUNT/
tar -xzf /tmp/mail-ACCOUNT.tar.gz

# 4. Fix permissions
chown -R ACCOUNT:ACCOUNT /home/ACCOUNT/mail/

# 5. Testar IMAP/SMTP
telnet localhost 143  # IMAP
telnet localhost 25   # SMTP

2.6 Rollback Procedure (Fase 2)

# Disponível até Day 7

# 1. Reverter DNS (todos sites)
A records → IP antigo (server.descomplicar.pt)

# 2. Verificar server antigo online
ping server.descomplicar.pt

# 3. Comunicar clientes

# 4. Analisar causa falha

# 5. Ajustar plan e re-tentar

---

FASE 3: Cluster Formation (Week 7-8)

Target: Formar cluster 2-node, HA, cleanup

3.1 Preparar server.descomplicar.pt como Node A

# APENAS após Fase 2 100% validada

# Backup final completo
tar -czf /tmp/final-backup-server.tar.gz /etc /home /var/www

# Reformatar com Proxmox (/proxmox-setup)
# Tornar Node A do cluster

3.2 Cluster Formation

# Usar skill /proxmox-cluster (criada a seguir)
/proxmox-cluster create --node-a server.descomplicar.pt --node-b cluster.descomplicar.pt

3.3 HA Configuration

# Usar skill /proxmox-ha (criada a seguir)
/proxmox-ha configure --critical-vms 200,300

3.4 Cleanup

# Cancelar easy.descomplicar.pt VPS (após validação)
# Backup final de tudo
# Documentar nova arquitectura

---

Backup Strategy Durante Migration

Fase 1 (EasyPanel)

3 locais:

1. Containers em easy.descomplicar.pt (original)
2. PBS Node B backup
3. easy.descomplicar.pt VPS backup (mantido durante Fase 1)

Fase 2 (CWP)

Safety net 7 dias:

1. Server antigo intacto (rollback rápido)
2. VM CWP → PBS backups automáticos
3. Backups manuais /mnt/migration/

RPO: 1h (PBS backups hourly se critical) RTO: 2-4h (restore + DNS propagation)

Fase 3 (Cluster)

Redundância completa:

1. VMs em Node A + Node B
2. PBS primary (Node B 16TB)
3. PBS secondary remote sync (Node A 12TB)

Output Summary (Por Fase)

Fase 1 Complete:

✅ EasyPanel migrado: 108 containers

📦 Containers:
   - Migrados: 108/108
   - Falhas: 0
   - Rollbacks: 0
   - Downtime médio: <2min por container

🎯 Validation:
   - Health checks: 100% OK
   - Cliente feedback: 0 issues
   - Performance: <500ms avg response

🔄 DNS Cutover:
   - TTL: 300s (5min)
   - Domains migrados: ALL
   - Rollback window: 7 dias

📋 Next: Fase 2 (CWP migration)

Fase 2 Complete:

✅ CWP migrado: 39 vhosts

🌐 Sites:
   - Migrados: 39/39
   - HTTP 200: 100%
   - SSL válido: 100%
   - Email funcional: 100%

⏱️ Timeline:
   - Week 3-6: Migration
   - Day 1-7: Validation period
   - Day 8: Cleanup (se OK)

🔒 Safety Net:
   - Server antigo: ONLINE (Day 1-7)
   - Rollback: Disponível (DNS reverter)
   - Backups: 3 locais

📋 Next: Fase 3 (Cluster formation)

Fase 3 Complete:

✅ Cluster Proxmox formado: 2 nodes

🖥️ Nodes:
   - Node A: server.descomplicar.pt (reformatado)
   - Node B: cluster.descomplicar.pt
   - Quorum: 2 votes

🔄 HA:
   - Critical VMs: 200, 300
   - Failover: Automatic
   - Live migration: Enabled

💾 PBS Redundancy:
   - Primary: Node B (16TB)
   - Secondary: Node A (12TB) remote sync
   - RPO: 1h | RTO: 2-4h

🎉 Migration Complete:
   - Total time: 8 weeks
   - Downtime: <5min total
   - Issues: 0 critical
   - Cliente satisfaction: HIGH

📋 Post-Migration:
   - Monitor por 30 dias
   - Documentar em PROC-VM-Migration.md
   - Cancelar VPS legacy
   - Treino equipa Proxmox

Troubleshooting

Container migration fails

# Verificar logs
docker logs CONTAINER_ID

# Verificar volumes
ls -lah /var/lib/easypanel/projects/PROJECT/

# Testar manual
docker-compose up -d

# Rollback e investigar

CWP site não carrega após migration

# Verificar Apache
systemctl status httpd

# Verificar vhost
cat /usr/local/apache/conf.d/vhosts/DOMAIN.conf

# Verificar database
mysql -u USER -p DATABASE

# Verificar DNS propagation
dig +short DOMAIN @8.8.8.8

Email não funciona

# Verificar Postfix
systemctl status postfix

# Testar SMTP
telnet localhost 25

# Verificar DNS MX
dig +short MX DOMAIN

# Verificar logs
tail -f /var/log/maillog

References

• Migration Plan: Hub/05-Projectos/Cluster Descomplicar/Planning/Migration-Plan-OptionA.md
• NotebookLM: 276ccdde-6b95-42a3-ad96-4e64d64c8d52
• Guia Hub: Guia-Definitivo-Proxmox-Hetzner.md (Módulo 4: Workloads)

---

Versão: 1.0.0 | Autor: Descomplicar® | Data: 2026-02-14

Metadata (Desk CRM Task #1712)

Projeto: Cluster Proxmox Descomplicar (#65)
Tarefa: Migração Infraestrutura (#1712)
Tags: migration, cwp, easypanel, zero-downtime, phased
Status: Implementation

---

/ @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/

---

Quando NÃO Usar

• Para migrações non-CWP/EasyPanel (criar plan específico)
• Para teste/dev environments (menos rigor)
• Para single-server setups (não cluster)