Skip to Content
DocsCloud OSServer ModeFleet — App Migration

App Migration (Fleet)

App Migration lets you relocate a running containerised app from source node A to target node B with a deterministic, orchestrated flow. Free on every plan — this is the compute-moving primitive under every other fleet feature.

When to use it

  • You added a beefier node and want to shift database workloads onto it.
  • The source node is going in for maintenance.
  • You are re-balancing storage after adding drives.
  • You want to hand an app over to a different geo region.

The state machine

Every migration progresses through six states:

pending → snapshotting → transferring → restoring → cutover → done
                   \           \            \           \
                    +-----------+------------+-----------+--> failed
  • pending — the CP has recorded the request, nothing has happened on disk yet.
  • snapshotting — the source node exports the container image + its named volumes into a tarball under /var/lib/quazzar/migrations/<migration-id>.tar. On CoW pools (btrfs/zfs) the snapshot is taken atomically from the Phase 3 storage backend; otherwise Quazzar falls back to docker export + tar.
  • transferring — the orchestrator moves the archive from source to target (rsync / scp / shared NFS depending on your fleet topology).
  • restoring — the target node loads the archive and creates a stopped container so the cutover can flip traffic in one step.
  • cutover — source stops the old container, target starts the new container, and the Phase 1 reverse-proxy route repoints the domain at the new upstream atomically.
  • done — terminal success. The old volumes are kept on the source node as a safety net until you delete them manually.
  • failed — any non-terminal state can land here if a node reports a problem. The reason shows up in the migration list.

Starting a migration

  1. Open Control Panel → Fleet → Migrations.
  2. Type the App id (the container name or compose stack root).
  3. Pick Source node and Target node.
  4. Click Start migration. The row appears with a six-step progress bar that updates every 5 s.
  5. If anything goes wrong, the Abort button marks the migration failed and leaves both nodes untouched.

Rollback

done is not undoable through the UI — to revert, start a new migration in the opposite direction. The source-side archive is kept for seven days so you can replay from it.

  • POST /api/migrations — create.
  • GET /api/migrations — list.
  • POST /api/migrations/{id}/advance — state-machine tick.
  • POST /api/migrations/{id}/fail — abort.
  • POST /api/agent/v1/migration/snapshot — node-side (CP-driven).
  • POST /api/agent/v1/migration/restore — node-side (CP-driven).
  • POST /api/agent/v1/migration/cutover — node-side (CP-driven).
Public TunnelFleet — Multi-Node Dashboard