Migrations and container archives

Migration moves an eligible workload between Docker nodes while preserving its Gateway 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 Gateway ownership and relationships. Use a Gateway 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 Gateway-owned runtime configuration.

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 Gateway 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 Gateway from completing or resuming safe cleanup.

Export and import GWCA archives

GWCA archives can be self-contained or registry-backed. They include supported configuration and ordinary environment values, and can optionally include secrets and writable-layer changes. They never include volume contents.

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 Gateway 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.