Platform Migration Playbook

Plan and execute a platform migration with dependency mapping, authoritative data ownership, rehearsed cutover, reconciliation, and explicit recovery limits.

trigger="A supported business decision requires moving a live workload, capability, datastore, or system of record." owner="The migration lead accountable for continuity, scope, acceptance evidence, and cutover decisions." participants={["Business process owner", "Source and target application owners", "Data owner", "Integration owners", "Security reviewer", "Operations lead", "Support and communications owner"]} prerequisites={[ "A business reason, scope boundary, dependency inventory, and accepted recovery objectives.", "Access to export and migration mechanisms, representative data, and a tested target environment.", "A phase-specific authority map, cutover runbook, and approved stop and recovery controls." ]} outputs={[ "A migration wave plan with dependencies, consumer obligations, and a data mapping contract.", "A rehearsed cutover record with checkpoints, reconciliation results, and recovery evidence.", "An accepted operating handoff and an evidence-based legacy retirement plan." ]} doneWhen={[ "In-scope users, jobs, and integrations work through the target with accepted data and permissions.", "The authoritative writer is unambiguous and business invariants reconcile at agreed checkpoints.", "Operators have demonstrated rollback or forward recovery for the actual migration phase.", "Legacy obligations, data retention, support, and retirement ownership are resolved." ]} />

Govern the move before scheduling the switch

A migration changes more than application hosting. It can change identities, data meaning, URLs, integrations, support procedures, and the system that is allowed to accept a business action.

This playbook governs that transition across application, cloud, datastore, and SaaS moves. Use the microservices migration playbook for a service extraction and the strangler pattern guide for incremental interception. Neither pattern makes rollback automatic.

There is no general success percentage, overrun multiplier, or downtime promise here. The migration lead earns a go decision through measured evidence and an agreed recovery path.

1. Define scope and authority

The business owner states why the move is required, what must improve, what must remain equivalent, and what can be retired. A missing usage signal is a reason to investigate a feature, not authority to delete it.

List users, scheduled jobs, APIs, reports, exports, batch windows, webhooks, support tools, and downstream consumers. Identify deadlines, legal holds, export rights, licensing restrictions, source shutdown commitments, and target quotas. Confirm them with the accountable owners rather than inferring obligations from architecture.

The migration lead defines who can start, pause, reverse, or continue a cutover. Include a substitute decision-maker and a reachable escalation path. Decide when user communication is required and who publishes it.

| Record | Owner | Required evidence | | --- | --- | --- | | Business scope | Process owner | Included outcomes, excluded changes, accepted discontinuations | | Dependency map | Application and integration owners | Verified callers, jobs, credentials, endpoints, and schedules | | Data contract | Data owner | Mapping, identities, history, permissions, invariants, and retention | | Operational contract | Service owner | Capacity, availability, recovery objectives, alerts, and support | | Cutover authority | Migration lead | Stop conditions, decision rights, contacts, and communications |

Gate: every critical dependency has an owner and a test. Unknown source writers or unsupported export requirements block planning a write cutover.

2. Run the migration assessment before choosing waves

Do not turn an application inventory into a migration commitment. The assessment must connect business criticality, technical state, dependencies, data obligations and operating readiness. AWS distinguishes portfolio-level assessment from the deeper application-level assessment needed as a wave approaches. Its application portfolio assessment guide covers discovery, analysis and planning rather than treating inventory collection as the final output.

Start with a portfolio record that is complete enough to prioritize investigation:

| Assessment area | Evidence to collect | Decision supported | | --- | --- | --- | | Business outcome | Capability, users, critical periods, service impact, sponsor and contractual deadlines | Why move, retain, replace or retire the workload | | Application shape | Runtime, versions, deployment model, state, environments and lifecycle constraints | Technical feasibility and likely strategy | | Dependency graph | Upstream callers, downstream services, identity, network, files, jobs, reports and vendors | Wave grouping and hidden cutover obligations | | Data obligations | Owners, classification, residency, retention, deletion, volume, growth and write authority | Transfer, security and reconciliation design | | Operational evidence | Demand, incidents, service objectives, backup, restore, observability, support and cost | Target controls and acceptance criteria | | Change capacity | Accountable team, release constraints, testing assets, subject-matter availability and freeze windows | Wave size and credible schedule |

Then perform a detailed assessment for each candidate wave. Observe the deployed system and recent change history instead of relying only on questionnaires. Trace two or three critical user journeys, one scheduled or asynchronous flow, identity propagation and a recovery scenario. Compare architecture diagrams with actual network, configuration, telemetry and integration records.

Assess organizational readiness separately

A technically portable application can still be a poor first wave when landing-zone ownership, security decisions, operations, procurement or support are unresolved. AWS describes its Migration Readiness Assessment as a way to examine readiness across business, people, governance, platform, security and operations and to produce an action plan for gaps. See Evaluating migration readiness.

For this playbook, use that idea as a control rather than a score. Record every prerequisite that the migration team does not own, its accountable owner and the date by which the wave needs it. Examples include account vending, connectivity, identity federation, log retention, key management, vulnerability handling, budget allocation, support coverage and exception approval.

Do not average a missing security or recovery control into an overall readiness percentage. Classify the wave as:

• ready for strategy and design: critical dependencies and platform prerequisites are known;
• ready after named prerequisites: gaps have owners, acceptance evidence and dates;
• requires deeper discovery: the current state or business obligation is too uncertain;
• not a migration candidate now: the value does not justify risk or required change.

Produce a decision-grade assessment pack

The assessment pack contains the verified portfolio record, dependency diagram, data and identity boundary, observed demand, critical journeys, target constraints, candidate strategy, main risks, unanswered questions and evidence links. It also states what was not inspected. That limitation matters when the wave plan is later treated as a delivery commitment.

Gate: do not assign a cutover date until critical unknowns have either been resolved or explicitly included as discovery work with enough schedule and authority to change the plan.

The assessment is complete only when another reviewer can trace each recommended wave to its business outcome, verified dependencies, readiness prerequisites and remaining uncertainty. A colored scorecard without that evidence is not a migration plan.

3. Select a strategy for each workload

Compare moving, adapting, replacing, retaining, and retiring the workload. AWS migration guidance describes seven strategies: retire, retain, rehost, relocate, repurchase, replatform, and refactor or re-architect. These are planning categories, not a ranking of business value or guaranteed timelines.

| Strategy choice | Question to answer before commitment | | --- | --- | | Retain or retire | Is continued operation or removal explicitly accepted, with dependent work accounted for? | | Rehost or relocate | Does the target support the workload, licensing, network, operations, and performance needs? | | Replatform | Which runtime or managed-service differences change behavior and recovery? | | Repurchase | Can the replacement preserve required workflows, permissions, history, and exportability? | | Refactor or re-architect | Which measured requirement justifies application change during the move? |

A planned outage may be safer than a complex overlap for a small, bounded system whose users accept interruption. Incremental migration can reduce the scope of a cutover but requires compatibility and parallel operating capacity. Record the tradeoff rather than declaring one pattern universally safest.

Sequence work by dependency, business deadline, learning value, and containment. A low-risk pilot should still exercise representative identity, data, and integration behavior. Do not defer an unproven critical dependency until the last wave merely because it is difficult.

4. Build the target and prove operating readiness

The target owner prepares identity, least-privilege access, networking, secrets, encryption keys, deployment, observability, backup, restore, capacity, and cost controls. Test the route from real consumer locations and identities, including DNS, certificates, allowlists, private endpoints, and timeouts.

Run representative load and failure tests with the required data size. Include throttling, dependency failure, retries, cold startup, and background schedules. Compare completion and business outcomes as well as endpoint health.

The operations lead restores a protected copy and proves that the application can use it. Verify permissions, keys, runtime compatibility, and dependencies after restoration. A backup-job success message is not recovery evidence.

Gate: the target can serve the selected slice, fail safely, and be operated by the receiving team. Migration scripts do not substitute for this readiness check.

5. Define the authoritative data path

The data owner records the source of truth by entity or explicitly fenced partition for every phase. Avoid informal manual entry into both systems. A successful write in one system followed by failure in the other creates divergence even when the user sees an error.

Choose a supported transfer method:

| Method | Required controls | Known limit | | --- | --- | --- | | Offline export and import | Fence writes, validate snapshot and mapping, test restart | Requires accepted interruption and complete export scope | | Snapshot plus change capture | Consistent start point, ordering, deletes, checkpoints, backlog monitoring | Engine and schema limitations; replication lag | | Transactional outbox | Business change and publication intent committed together; duplicate handling | Delivery and target application are still separate steps | | Event replay | Complete retained history, event versions, deterministic projection, effect isolation | Missing history or incompatible events can prevent reconstruction | | Temporary application dual operation | Durable coordination, stable operation IDs, reconciliation, explicit authority | Independent uncoordinated dual writes are not atomic |

The transactional outbox pattern addresses the database-and-message dual-write problem; consumers still need idempotent processing. It does not turn two arbitrary databases or SaaS APIs into one transaction.

Preserve source IDs, target IDs, operation IDs, source revision, transformation version, and deletion state. Define null, time zone, precision, currency, status, attachment, and relationship mappings. Test records that cannot be represented and agree whether they are repaired, quarantined, or excluded with authorization.

6. Reconcile at a known checkpoint

Counts alone cannot show that balances, relationships, permissions, or statuses are correct. The data owner combines record-level checks where feasible with business invariants and explicitly documented sampling or coverage gaps.

Compare source and target at a known snapshot or replication watermark. Otherwise, legitimate ongoing writes can appear as discrepancies. Track failed, pending, and excluded validations separately from successful checks. Tool support varies by engine and data type; AWS DMS validation documentation lists relevant restrictions and operational behavior.

"type": "svg-architecture", "title": "Copy state while retaining one authoritative writer", "nodes": [ ], "links": [ ], "caption": "The target remains a candidate until the authority-transfer gate. Transfer success and application correctness are separate checks." }} />

Stop if a discrepancy threatens an agreed invariant, if validation coverage is unknown, or if the backlog cannot converge within the cutover window. Recovery may mean repairing the mapping and rebuilding the target while the source remains authoritative.

7. Control SaaS integrations and shadow effects

For SaaS replacement, the process owner assigns one authoritative system for each workflow during overlap. Make the other read-only or route all changes through a controlled integration. Map users and permissions separately from business-record identities.

Inventory vendor automations, outbound email, webhooks, billing actions, duplicate detection, and background jobs. An import can trigger real side effects. Test in an isolated tenant or approved sandbox and verify which automation controls apply to bulk and API operations.

Shadow application requests only when they are read-only or their effects are isolated. Remove live write credentials and block outbound actions in the candidate path. Asynchronous copying can still consume quotas and disclose data to another provider; approve that handling before enabling it.

Retain ambiguous API results for reconciliation. If a request timed out after the target accepted it, check the operation identity before retrying. Manual “fix it in both systems” work needs an audited procedure and an explicit owner.

8. Rehearse and execute the cutover

The runbook owner rehearses on representative state, including interruption halfway through a step. Every step names its operator, input, expected result, verification, time allowance, and safe stop point.

A write-authority transfer commonly follows this sequence, adapted to the platform's supported mechanism:

"type": "flow", "title": "Transfer write authority through verified checkpoints", "steps": [ ], "caption": "If fencing or reconciliation fails, do not enable the target writer. Once new writes occur, recovery must account for them." }} />

Account for connection pools, cached configuration, DNS, long-running jobs, queued messages, and old credentials. A connection-string update alone may leave source writers active.

Keep a timestamped decision log. Compare the agreed service objectives, backlog, data checks, permissions, and business workflows during the observation window. Do not invent a universal acceptable error percentage or require every unrelated business metric to increase.

9. Choose recovery from the actual phase

| Phase or failure | Safe recovery candidate | Gate before resuming | | --- | --- | --- | | Target not yet authoritative | Stop transfer or return routed reads to the source | Source capacity, routing, and unchanged authority verified | | Cutover paused before target writes | Reopen source writes after abort procedure | Target writer remains fenced; no ambiguous accepted work | | Target has accepted new writes | Tested reverse propagation and reconciliation, or forward repair | Current writer fenced; complete compatible state established | | New schema semantics cannot be represented by old code | Forward recovery or approved restoration and replay | Explicit recovery objective and affected-work reconciliation | | External effects already happened | Authorized compensating business actions | Operation ledger and downstream confirmation | | Contract or deletion step removed old state | Restore and replay if supported, otherwise approved repair | Proven recovery source, keys, history, and accepted interruption |

Expand-contract provides a compatibility period only while old and new code can safely use the retained schema. Destructive removal, changed meanings, and new incompatible writes can close that period. Keep the contract step separate and require approval after consumer and recovery checks.

An old database is a recovery asset only if its freshness and compatibility are maintained or a tested repair path exists. Do not call it rollback merely because it is still running. Test reverse replication for loops, ordering, and schema compatibility before depending on it.

10. Retire and hand over deliberately

The receiving service owner accepts on-call procedures, dashboards, escalation, restore steps, cost ownership, and known limitations. Support confirms that users can complete their work and that exceptions have an owner.

Select retirement evidence from business cycles, delayed integrations, offline clients, retention obligations, and the recovery window. Check jobs and exports as well as interactive traffic. Disable legacy writes and credentials in a controlled stage before destroying retained state.

Reconcile final records and accepted exclusions. Archive the approved mapping and cutover evidence under the retention policy. Confirm that source billing and contracts are addressed, without assuming decommission automatically realizes savings.

11. Reuse the wave record

Wave, business outcome, scope, and accountable lead:
Consumers, jobs, integrations, and contacts:
Source and target versions, permissions, and export constraints:
Data mapping, identity mapping, and business invariants:
Authority by phase and mechanism for fencing every writer:
Transfer checkpoint, backlog, validation coverage, and exceptions:
Runbook rehearsal, stop triggers, and last safe abort point:
New-write recovery, reverse sync or replay, and effect reconciliation:
Go/no-go decision, timestamp, operator, and evidence links:
Operating handoff, retention, and legacy retirement criteria:

"The scope and retirement decisions have explicit business approval.", "Critical dependencies and hidden writers have owners and tests.", "Target operation, capacity, backup restoration, and access checks pass.", "Data authority and record identity remain unambiguous throughout overlap.", "Reconciliation uses a known checkpoint and reports coverage gaps.", "Shadowing and imports cannot trigger unintended real effects.", "Cutover fencing and recovery after new writes have been rehearsed.", "Destructive contract and retirement steps have separate approval gates." ]} />

Limitations

No generic runbook establishes zero data loss or zero downtime. Database versions, SaaS export behavior, replication restrictions, and business obligations require system-specific verification. Retain unresolved risks in the go/no-go record.

The final deliverable is an evidence pack for the migration decision. Editorial review does not authorize a production cutover or replace application, data, security, and business-owner approval.