Migrate between devices

Edgible can move an application between devices you own with the application’s persistent storage intact and the public hostname unchanged. The flow is single-command from your side; the platform coordinates a multi-phase migration (preflight, quiesce, snapshot, ship, restore, cutover).

This guide shows what the application has to declare to be eligible for migration, and what edgible application migrate actually does.

What needs to be true

For an application to be migratable:

1. Storage is declared as mobility: movable. Volumes default to immovable — set movable explicitly if you want them to follow the application.
2. The placement allows migration. Set placement.migrationPolicy: allowed (or automatic).
3. Both source and target devices are online and registered in the same organization.
4. The target device can run the workload — compatible runtime (Docker present for compose/docker, etc.), enough capacity.

A migratable application

Save as app.yml:

app.yml

apiVersion: v3
kind: Application
metadata:
  name: migration-app
  organization: <your-org-id>
spec:
  placement:
    strategy: serving-device
    deviceSelector:
      deviceName: device-a
    migrationPolicy: allowed
  storage:
    - name: data
      type: persistent
      size: 1Gi
      mobility: movable
  workloads:
    - name: web
      type: compose
      composeFile: ./docker-compose.yml
      ports:
        - { name: http, containerPort: 8080, protocol: tcp }
      storage:
        - name: data
          mountPath: /mnt/edgible/data
  access:
    - name: public
      type: https
      target: { workload: web, port: http }
      hostname: { generated: true }
      tls: { managedBy: edgible }
      policies: { auth: { mode: none } }

Deploy:

edgible stack deploy -f app.yml

Wait for ready, then write some state to verify migration preserves it:

curl -X POST https://<hostname>/store -d "marker=before-migration"

(Use whatever endpoint your workload exposes for writing to its mounted volume.)

Running the migration

edgible application migrate migration-app --to device-b

The CLI submits a migration request; the platform runs the multi-phase flow:

1. Preflight — checks both devices are reachable, the workload is compatible with the target, and there’s enough space.
2. Quiesce — drains in-flight work, stops the workload on the source.
3. Snapshot — captures the state of the persistent volume.
4. Ship — transfers the snapshot from source to target over an authenticated channel.
5. Restore — rehydrates the volume on the target.
6. Start — brings the workload up on the target.
7. Validate — runs health checks and verifies the access route works.
8. Cutover — updates the gateway to forward traffic to the new device. The public hostname is unchanged.
9. Finalize — marks the source placement inactive and releases its volume.

The migration only commits on a successful health-and-route check at step 7. If anything fails before then, the workload stays where it was.

Watch progress:

edgible application status migration-app --watch

When status returns to ready on the new device, the migration is done. Verify:

curl https://<hostname>/store      # should show "marker=before-migration"

The marker survives because the volume came with the application.

Migration policies

migrationPolicy	Behavior
manual (default)	The application is locked to its current device. Migration requests are rejected.
allowed	Migration is permitted when explicitly requested with application migrate.
automatic	The platform may migrate the application on its own — for example, to balance load or in response to an unhealthy device.

Use manual for stateful workloads where you want full control. Use allowed when you want migration to be on-demand. Use automatic only for workloads that genuinely don’t care which physical device they’re on.

Migration into cloud

A mobility: movable volume can also be migrated into cloud (and out again). Run the same command pointing at a cloud region:

edgible application migrate migration-app --to-cloud --region us-east-1

The platform promotes the workload’s runtime to a tenant microVM, copies the volume into cloud-managed storage, and cuts traffic over. See Cloud hosting for the cloud side of the model.

Limits

• VM workloads need a storage-mounted disk. Inline diskImage paths can’t migrate; declare the disk via spec.storage[] and reference it in the workload’s storage[].
• Compose bind-mounts (host-bind storage) migrate best-effort. UID, symlink, and sparse-file caveats apply; for high-fidelity moves, promote the bind-mount to platform storage first.
• Source and target must be online. Offline migrations aren’t supported today.