Skip to content

CONCEPT Cited by 1 source

Tight migration scope

Tight migration scope is the posture of constraining a large infrastructure migration to the single system being swapped — the abstraction above and the abstraction below stay identical. Anything that changes "even things that feel nonfunctional" has second-order effects that are the usual cause of migration timelines blowing up.

Figma's formulation (ECS → EKS, 2024):

The safest scoping for a major migration limits the changes to the core system you want to swap out, and keeps the abstraction the same for all users of the platform.

The operational default: everything that isn't the new substrate itself stays the same. Deploy tooling, service-definition format, day-to-day CLI, monitoring UX, networking shape — unchanged.

Why second-order effects are the usual timeline killer

A migration touches:

  • The system being swapped (the change you signed up for).
  • Every system that depends on the old system's observable behavior — logs with specific shapes, metrics with specific names, CLI tools with specific flags, IAM shapes, etc.

If the new system behaves almost but not quite like the old one, every dependent system becomes a separate small migration. At N dependents, N small migrations in parallel — and their failure modes compound.

Tight scoping flips this: the new system is shaped to match the old one's observable surface (sometimes at extra implementation cost), so dependents see no change and nothing else needs migrating.

Exceptions

The rule has two deliberate exceptions:

  1. The old-behavior-match cost is higher than the second-order burn. If matching old behavior requires significant new work and the dependents are few or easy to update, burn the second-order effect instead. Figma's service-definition unification (Bazel → generated YAML, replacing Terraform-template + ECS-deploy two-step) was one such case: maintaining the old two-step on EKS would have been expensive, and the blast radius of changing it was contained.
  2. One-way-door decisions. Retrofitting later is expensive enough that you should take the scope hit now. Figma's three-active-cluster topology was this: adding it later would have meant a second migration on top of the first. Better to burn the scope now and compound the benefit across the migration and beyond.

What gets deferred (fast-follows)

Everything not in-scope and not a one-way door goes to the fast-follow list:

  • Figma deferred pod-level auto-scaling (Keda / HPA) — too much risk during the critical-path migration.
  • Figma deferred log-pipeline redesign (Vector sidecar replacing their Lambda-based CloudWatch forwarder) — same reason: porting the forwarder logic into Vector config during concurrent migration was high second-order risk.
  • Both shipped after the migration as parallel-tracked improvements, delivering benefits without upscoping the cutover.

The key insight: pipelining the migration and the improvements lets you both compound; trying to do them together makes both riskier.

Signals the scope is wrong

  • "We'll just also upgrade X while we're in there." Red flag unless X is load-bearing or a one-way door.
  • Discovery-phase estimates include "and we'll replace [adjacent-system]" — each addition is a second-order surface.
  • A dependent team is blocking because the new system's observable shape is slightly different.

Contrast with achievable-target-first migration

patterns/achievable-target-first-migration is about which workload to migrate first (pick a tractable one, not the hardest). Tight migration scope is about what set of changes to include in any migration (only the substrate, not improvements). Airbnb's observability migration and Figma's ECS→EKS migration apply both principles.

Seen in

Last updated · 200 distilled / 1,178 read