Problema

En entornos con Proxmox, la mayoría de los administradores confía en los jobs de backup para proteger sus máquinas virtuales (VM) y contenedores (CT). Cuando el nodo físico (VE) falla, la necesidad inmediata es volver a poner en marcha todos los recursos respaldados, no solo una VM aislada. La herramienta de restauración de Proxmox permite seleccionar una VM y recuperarla, pero no ofrece una opción directa para “restaurar todo el backup” en una sola operación. El resultado es un proceso manual, propenso a errores y que consume tiempo crítico durante una recuperación de desastre.

Causa

  1. Diseño orientado a objetos individuales
    Proxmox Backup Server (PBS) almacena cada VM/CT como una entidad separada dentro del repositorio. Los metadatos de los jobs (horarios, políticas) se guardan en el nodo origen, no en el servidor de backup. Por eso la UI muestra la restauración por VM.

  2. Falta de vínculo entre job y conjunto de backups
    Un job de backup agrupa varios objetos, pero el repositorio no mantiene una “instantánea del job”. Cada backup se registra con su propio ID, lo que impide que PBS reconozca automáticamente que forman parte de un mismo conjunto.

  3. Dependencias de infraestructura
    Restaurar varios objetos simultáneamente requiere que el nodo destino tenga la misma configuración de storage, redes y IDs de VM. Si esas coincidencias no existen, la restauración masiva puede colisionar o crear duplicados.

Solución

El enfoque práctico consiste en automatizar la restauración de todos los backups que pertenecen a un mismo job o a un rango de fechas. La solución se divide en tres pasos:

  1. Obtener la lista de backups
    Utiliza proxmox-backup-client catalog o la API de PBS para filtrar por job-id o por rango de tiempo. El comando devuelve pares vmid:backup-id.

  2. Iterar y restaurar
    Un pequeño script Bash recorre la lista y ejecuta proxmox-backup-client restore para cada VM/CT, especificando el destino (nuevo VE) y, si es necesario, un nuevo vmid. El script también recrea discos en el storage correcto y asigna las interfaces de red definidas en la plantilla del VM.

  3. Sincronizar metadatos
    Después de la restauración, importa la configuración del VM (qm importdisk o pct restore) y actualiza la tabla de recursos del nuevo nodo con qm set / pct set. Opcionalmente, restaura los snapshots del job mediante pveam si se guardaron.

Script de ejemplo

#!/usr/bin/env bash
# Variables de entorno
PBS_REPO="pbs:backup-repo"
TARGET_NODE="new-ve"
STORAGE="local-lvm"
JOB_ID="my-backup-job"
START_DATE="2024-01-01"
END_DATE="2024-01-31"

# 1. Listado de backups del job en el rango de fechas
backups=$(proxmox-backup-client catalog \
  --repo $PBS_REPO \
  --filter "job-id=$JOB_ID" \
  --filter "date>=$START_DATE" \
  --filter "date<=$END_DATE" \
  --output json | jq -r '.[] | "\(.vmid) \(.backup-id)"')

# 2. Restaurar cada VM/CT
while read -r vmid backup_id; do
  echo "Restaurando VMID $vmid (backup $backup_id)..."
  # Generar nuevo VMID si el original ya existe en el target
  if qm status $vmid &>/dev/null; then
    new_vmid=$(qm nextid)
    echo "VMID $vmid ya existe, asignando $new_vmid"
  else
    new_vmid=$vmid
  fi

  # Restaurar discos
  proxmox-backup-client restore \
    $backup_id \
    $TARGET_NODE:$new_vmid \
    --repo $PBS_REPO \
    --storage $STORAGE \
    --force

  # Opcional: restaurar configuración de red y opciones
  # (asumimos que la metadata está incluida en el backup)
done <<< "$backups"

echo "Restauración completa."

Detalles clave del script

  • Filtrado por job-id permite agrupar los backups que pertenecen al mismo job, replicando la intención de “restaurar todo el job”.
  • Rango de fechas ayuda a limitar la restauración a la última ejecución antes del fallo.
  • Gestión de colisiones de VMID evita que la restauración falle por IDs ya ocupados.
  • --force sobrescribe discos existentes en el storage destino, útil en pruebas controladas.

Cuándo aplicar esta solución

  • Fallo total del nodo origen: cuando el hardware o el hypervisor se vuelve inaccesible y necesitas reconstruir el entorno completo.
  • Migración de versión: al mover un cluster a una versión mayor, pero deseas mantener los mismos backups como punto de partida.
  • Pruebas de recuperación: para validar que los jobs de backup cubren todos los objetos críticos y que el proceso de restauración masiva funciona.

No aplica cuando:

  • Solo se necesita restaurar una VM puntual; el script añade complejidad innecesaria.
  • Los backups están distribuidos en varios repositorios sin una convención de job-id común.
  • El nuevo VE tiene una topología de red o storage radicalmente distinta; en ese caso, una restauración manual permite ajustar cada VM individualmente.

Código

#!/usr/bin/env bash
# Variables de entorno
PBS_REPO="pbs:backup-repo"
TARGET_NODE="new-ve"
STORAGE="local-lvm"
JOB_ID="my-backup-job"
START_DATE="2024-01-01"
END_DATE="2024-01-31"

backups=$(proxmox-backup-client catalog \
  --repo $PBS_REPO \
  --filter "job-id=$JOB_ID" \
  --filter "date>=$START_DATE" \
  --filter "date<=$END_DATE" \
  --output json | jq -r '.[] | "\(.vmid) \(.backup-id)"')

while read -r vmid backup_id; do
  echo "Restaurando VMID $vmid (backup $backup_id)..."
  if qm status $vmid &>/dev/null; then
    new_vmid=$(qm nextid)
    echo "VMID $vmid ya existe, asignando $new_vmid"
  else
    new_vmid=$vmid
  fi

  proxmox-backup-client restore \
    $backup_id \
    $TARGET_NODE:$new_vmid \
    --repo $PBS_REPO \
    --storage $STORAGE \
    --force
done <<< "$backups"

echo "Restauración completa."

Verificación

  1. Lista de VMs en el nuevo nodo

    qm list
pct list

    Confirma que todos los vmid esperados aparecen.

  2. Estado de los discos

    ls -l /var/lib/vz/images/<vmid>

    Verifica que los discos tengan el tamaño correcto y que el storage asignado sea el esperado.

  3. Arranque de prueba

    qm start <vmid>
# o para contenedores
pct start <ctid>

    Asegúrate de que el sistema operativo arranca sin errores y que la red está operativa.

  4. Comparación de checksums (opcional)
    Si guardaste hashes de los discos originales, compáralos con los restaurados usando sha256sum.

Notas adicionales

  • Consistencia de IDs: si el nuevo cluster usa una política de asignación de VMID diferente, considera crear un mapeo antes de la restauración para evitar conflictos con recursos existentes.
  • Snapshots: los snapshots de PBS no se restauran automáticamente con el script. Usa proxmox-backup-client snapshot-list y snapshot-restore si necesitas esa capa.
  • Redes VLAN: la restauración no replica la configuración de VLANs; revisa los archivos de configuración (/etc/network/interfaces dentro del VM) y ajusta las interfaces en el nuevo nodo.
  • Automatización CI/CD: incorpora este script en tu pipeline de pruebas de DR (Disaster Recovery) para validar periódicamente la capacidad de recuperación completa.
  • Seguridad: ejecuta el script con una cuenta de servicio limitada a los repositorios y al nodo destino. Evita usar root directamente en producción.