Migrations and container archives

Migration moves an eligible workload between Docker nodes while preserving its Opfield identity and eligible resource grants. A GWCA archive packages an eligible workload for controlled export and import. Both workflows are operational changes, not backups: stateful volume data requires its own backup and restore plan.

Choose the correct outcome

Use migration when the same managed workload must move to another Docker Node while retaining its Opfield ownership and relationships. Use an Opfield Container Archive (GWCA) when a workload configuration must be exported for controlled transfer or later import. Use an application backup when the goal is to protect or restore data. These outcomes overlap operationally but are not interchangeable.

The workload owner decides the maintenance window and validates application behavior. The platform owner confirms target capacity, runtime compatibility, image access, network placement, and cleanup. The data owner confirms backup and restore. A successful migration preserves the managed identity and access path on the target; a successful archive proves that the supported configuration can be imported, not that external dependencies or volume data are available.

Confirm eligibility first

Cross-node migration performs capacity preflight, artifact and volume transfer, target verification, cutover, and cleanup recovery. The target must be online, have sufficient resources, support the selected runtime, and reach any required registry artifact.

GPU-attached workloads, secure-runtime workloads, host bind mounts, and Compose Projects are not portable in the current workflow. Treat this as a hard boundary rather than a condition to work around by altering Opfield-owned runtime configuration. To bring an existing Compose application under Opfield management on its current Node, adopt the Compose project instead.

Migration copies the data of the workload’s local named volumes and creates them on the target with the same names. Preflight stops the migration if the target already has a volume with the same name, or if a volume is shared with another workload, non-local, or disk-image backed. A Container or Deployment with a database or storage link cannot migrate (MIGRATION_MANAGED_LINK_UNSUPPORTED): delete the link, migrate, and link it again on the target Node. Docker versions with distribution suffixes, such as 26.1.5+dfsg1 on Debian, are compared by their release number.

Migrate a workload

1. Record Routes, database bindings, grants, volume dependencies, and the planned maintenance window.
2. Back up stateful volumes and confirm the target node has the required capacity and runtime profile.
3. Start migration from the workload and follow the operation through transfer and target verification.
4. Wait for cutover, then verify runtime health, routes, logs, and private application dependencies on the target.
5. Retain the source until Opfield reports cleanup completion and the verification window has passed.

If transfer, target startup, or cutover fails, inspect the operation stage. Use the provided cancellation or cleanup-recovery actions; manually deleting intermediate objects can prevent Opfield from completing or resuming safe cleanup.

Workloads on Docker Engine 20.10 through 28 migrate to Nodes with newer engines. Settings a newer engine cannot keep, such as a fixed MAC address or a kernel memory limit, are listed by the preflight with the same message the migration would stop with; when the source Node runs an older Docker daemon, the preflight shows a warning instead. A migration that waited for a Node to reconnect and then finished is shown as completed, and one cancelled after such a wait as cancelled.

Export and import GWCA archives

GWCA archives can be self-contained or registry-backed. They include the supported container configuration and can optionally include environment values, secrets, and writable-layer changes. They never include volume contents. On import, each archived volume is created empty under a new name, or you map it to an existing Opfield-managed volume.

Export supports a portable subset of container settings. Containers with host bind mounts, anonymous volumes, privileged mode or changed capabilities, devices or GPUs, host namespaces, healthchecks, custom logging (Opfield’s default log limit does not count), or other host-specific settings are rejected, and the error lists the unsupported settings. Containers that belong to a Compose project—any container with a com.docker.compose.project label—cannot be exported: the REST API and MCP refuse them with DOCKER_ARCHIVE_COMPOSE_CONTAINER (HTTP 409) and the Console hides Export archive. Manage them through their Compose Project. Blue/green Deployment slots are also rejected.

An archive never carries the credentials of the container’s database or storage links. An import cannot attach the container to the host network, to another container’s network namespace, or to Opfield’s internal networks, and it drops Compose and Opfield labels. MCP clients export and import archives through one-time links with a ready curl command—the link operation of download_docker_archive and upload_docker_container_archive—instead of base64 chunks in tool calls.

Before export, decide whether including secrets is necessary and ensure the archive is handled as sensitive material when it is. Before import, review the target node, image availability, runtime compatibility, network mapping, and occupied ports. Restore volumes separately, then verify the imported workload before routing traffic to it.

Rollback and cleanup consequences

Migration rollback concerns the workload placement and runtime configuration; it does not reverse writes made by the application during a cutover. Keep the original volume backup and source evidence until the target is proven healthy. Deleting an archive does not delete a workload, and deleting the source after a migration should happen only through the completed migration lifecycle.

Verification and acceptance

After migration, verify the target Node identity, runtime and health, attached volumes, Routes, database bindings, grants, logs, and one real client transaction. Confirm that the source is no longer serving or accepting writes before approving cleanup. Keep the source evidence and backups until the agreed observation window completes.

After archive import, compare image digest, command, environment, secrets handling, volumes, networks, ports, runtime, and resource limits with the export intent. Do not route production traffic until application-specific dependencies and data restore are complete.

Operator details: failure recovery

Migration is staged so a failure before cutover should leave the source as the serving workload. Preserve the operation record and use supported cancellation or cleanup recovery. If the target started but acceptance failed, determine whether Opfield still reports the source as authoritative before making manual changes. Never allow both copies to accept writes unless the application was designed for that state.

GWCA files that include secrets or writable-layer changes are sensitive artifacts. Store them with access control, integrity protection, retention limits, and an owner. On import failure, correct target compatibility or mappings and retry with the same reviewed archive; do not edit the archive in an unaudited way to bypass policy.