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.
Qué necesitas
Sección titulada «Qué necesitas»- Una clave de API con el scope
migrations:readpara leer ymigrations:writepara 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"
1. Añade y confirma el origen
Sección titulada «1. Añade y confirma el origen»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.
2. Crea la migración
Sección titulada «2. Crea la migración»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_idy al menos una ola son obligatorios. Cada elemento necesitasource_username;plan_id,owner_user_idyoptions(dns_modespor zona,mail_passwords,ftp) son opcionales.settingstambié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,externalosource_dns),rollback_days(1–30, por defecto 14) yclient_visible.- La respuesta es la migración con sus olas y elementos. Guarda el
idde la migración comoMIGRATION_IDy anota elidde cada elemento (ITEM_IDmá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).
3. Inicia y sigue
Sección titulada «3. Inicia y sigue»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}]}'
statusde la migración:draft,running,paused,completedocancelled.pause_reasondice por qué se pausó una migración (por ejemplo tras una cuenta fallida).- El
statede un elemento va dependingporanalyzing,analyzed,provisioning,presync,verifyingyreadyacutover,post_verify,completedyfinalized; los demás sonfailed,paused,skipped,cancelledyrolled_back.stepyprogressmuestran el paso actual. gateindica qué puede hacer un elemento ahora:can_cutover(concutover_blockercuando no puede),can_rollback,runningyambers_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).
4. Conmuta una cuenta o revierte
Sección titulada «4. Conmuta una cuenta o revierte»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.
Errores
Sección titulada «Errores»| 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.
Eventos
Sección titulada «Eventos»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.
Relacionado
Sección titulada «Relacionado»- Migrar desde cPanel/WHM: las reglas, los modos de acceso y cómo se traslada una cuenta.
- Referencia de la API: cada operación
migration, con sus campos. - Convenciones de la API: errores, idempotencia y ETags.
- Autenticación y claves de API: scopes y manejo de las claves.