Platform Migration Playbook

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

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.

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:

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.

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:

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 Database Migration Service (DMS) validation documentation lists relevant restrictions and operational behavior.

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:

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

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.