Ir al contenido

Dirige una migración de cPanel

Añade un origen cPanel, planifica una migración por olas, inícialo, sigue cada cuenta y conmútala o revierte a través de la API.

Esta guía muestra cómo ejecutar con la API una migración de cPanel/WHM: conectar un origen, crear una migración, iniciarla, seguirla y conmutar cada cuenta. Cubre los mismos pasos que Migration Center en el panel. Las migraciones están disponibles para administradores y revendedores; un revendedor ve y migra solo sus propias cuentas.

  • Una clave de API con el scope migrations:read para leer y migrations:write para cambiar cualquier cosa (scopes).
  • El id del servidor de destino (GET /api/v1/servers), un servidor cuyo agente tenga el motor de migración.
  • Acceso al origen: un token de API de WHM, SSH como root (contraseña o clave) o un archivo cpmove. Las credenciales se guardan cifradas, la API nunca las devuelve y se destruyen cuando terminan las migraciones que usan el origen.
  • Un id de plan para las cuentas que crees (GET /api/v1/plans). Sin él se usa el plan por defecto de la organización.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SERVER_ID="3a3a3a3a-1111-4222-8333-444455556666"

POST /api/v1/migration-sources añade un origen. Para un origen WHM indica el host, el token de API y el servidor cuyo agente lo sondea (probe_server_id, normalmente el destino). kind es whm, ssh o archive; el puerto por defecto es 2087 para WHM y 22 para SSH, y el usuario por defecto es root.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "whm", "name": "old-cpanel", "host": "whm.old-host.example", "token": "'"$WHM_TOKEN"'", "probe_server_id": "'"$SERVER_ID"'"}'

El primer sondeo solo observa la identidad del origen, así que la respuesta trae "status": "awaiting_confirmation" y un fingerprint (de la clave de host SSH o del certificado de WHM). Guarda el id del origen como SOURCE_ID. Compara la huella con la real y confirma exactamente ese valor:

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-sources/$SOURCE_ID/confirm" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"fingerprint": "SHA256:…"}'

Empieza el sondeo completo. Consulta GET /api/v1/migration-sources/{id} hasta que status sea ready; entonces accounts lista las cuentas de cPanel (user, domain, disk_bytes, suspended). Un estado error trae un error_code; POST …/probe lo reintenta.

Para un origen de tipo archivo, indica archive_url (un enlace HTTPS) o sube primero el fichero: POST /api/v1/migration-sources/upload con {"filename": "…", "size": …} responde con una dirección temporal de subida (válida una hora); envía el fichero a ella con PUT, con las cabeceras de headers de la respuesta, y crea el origen con kind: "archive" y el object devuelto como archive_object.

POST /api/v1/migrations crea un borrador: un origen, un servidor de destino y las cuentas, en olas ordenadas.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Autumn move",
    "source_id": "'"$SOURCE_ID"'",
    "server_id": "'"$SERVER_ID"'",
    "waves": [
      {"name": "Pilot", "items": [{"source_username": "shopuser"}]},
      {"name": "The rest", "items": [{"source_username": "blog"}, {"source_username": "docs"}]}
    ],
    "settings": {"parallelism": 2, "rollback_days": 14, "dns_mode_default": "external"}
  }'
  • name, source_id, server_id y al menos una ola son obligatorios. Cada elemento necesita source_username; plan_id, owner_user_id y options (dns_modes por zona, mail_passwords, ftp) son opcionales.
  • settings también es opcional. Los más útiles: parallelism (1–10), auto_pause (parar en la primera cuenta fallida), auto_cutover, windows (cuándo pueden ejecutarse los pasos pesados), dns_mode_default (pluspanel_ns, external o source_dns), rollback_days (1–30, por defecto 14) y client_visible.
  • La respuesta es la migración con sus olas y elementos. Guarda el id de la migración como MIGRATION_ID y anota el id de cada elemento (ITEM_ID más abajo).

PATCH /api/v1/migrations/{id} cambia los ajustes y las olas, también mientras la migración está en marcha (solo se pueden mover los elementos que no han empezado); una migración completada o cancelada lo rechaza. Un borrador también se puede eliminar. Para ver qué se trasladaría antes de copiar nada, analiza un elemento con POST /api/v1/migration-items/{id}/analyze y lee GET /api/v1/migration-items/{id}/preflight (format es md, pdf o json).

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID/start" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"

PlusPanel analiza, aprovisiona, copia y verifica entonces las cuentas ola por ola. Síguela con GET /api/v1/migrations/{id}:

curl -fsS "$PLUSPANEL_URL/api/v1/migrations/$MIGRATION_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  | jq '{status, current_wave, pause_reason, items: [.waves[].items[] | {id, source_username, state, step, gate}]}'
  • status de la migración: draft, running, paused, completed o cancelled. pause_reason dice por qué se pausó una migración (por ejemplo tras una cuenta fallida).
  • El state de un elemento va de pending por analyzing, analyzed, provisioning, presync, verifying y ready a cutover, post_verify, completed y finalized; los demás son failed, paused, skipped, cancelled y rolled_back. step y progress muestran el paso actual.
  • gate indica qué puede hacer un elemento ahora: can_cutover (con cutover_blocker cuando no puede), can_rollback, running y ambers_acked.

GET /api/v1/migration-items/{id} añade el plan de verificación previa, lo que creó el aprovisionamiento, el estado del DNS por dominio y los nombres de host de vista previa; …/checks lista las comprobaciones y …/steps la cronología. pause, resume y cancel en /api/v1/migrations/{id} controlan toda la migración. GET /api/v1/migrations/{id}/report da el informe agregado (format es md, pdf o json).

Cuando un elemento está ready y su gate.can_cutover es true, conmútalo:

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/migration-items/$ITEM_ID/cutover" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"

La conmutación hace una última sincronización, cambia el DNS de cada dominio según el modo DNS del elemento y verifica el resultado. Una comprobación en rojo bloquea la conmutación. Las comprobaciones en ámbar necesitan antes POST …/ack-ambers (un reason opcional queda en el registro de auditoría). Lee GET …/dns para ver las instrucciones que debes aplicar tú en modo external y usa POST …/dns/check para comprobar la propagación ahora.

Dentro de la ventana de reversión, POST /api/v1/migration-items/{id}/rollback devuelve el DNS al origen; la cuenta de destino se queda. Otras acciones sobre un elemento: presync (una nueva sincronización incremental), verify, retry (tras un fallo) y skip.

Estado Código Qué significa
401 invalid_api_key La clave falta, ha caducado o se ha revocado.
403 La clave no tiene scope migrations, o el usuario no puede migrar esto.
404 El origen, la migración o el elemento no existe o no es visible para ti.
409 migration_unsupported_agent El agente del servidor no tiene motor de migración.
409 migration_source_not_ready El origen aún no está ready.
409 migration_state La acción no encaja con el estado actual (por ejemplo, iniciar dos veces).
409 migration_running Un elemento o una migración en curso bloquea el cambio o la eliminación.
409 migration_red_checks, migration_ambers_unacknowledged La conmutación está bloqueada por comprobaciones en rojo o por comprobaciones en ámbar sin reconocer.
409 migration_verify_stale La verificación está obsoleta; verifica de nuevo antes de conmutar.
409 migration_rollback_expired La ventana de reversión del elemento ha terminado.
422 migration_invalid_source, migration_fingerprint_mismatch El host o las credenciales del origen no se aceptan, o la huella difiere de la observada.
503 migration_vault_unavailable, migration_uploads_unavailable Las credenciales o la subida de archivos no están disponibles en esta instalación.

Los errores son problem details: decide según code.

No se envía ningún evento de webhook por el progreso de la migración: consulta la migración como en el paso 3. La lista de eventos muestra lo que sí se envía.