What is strangler fig pattern routing, and why use a proxy as the control plane?
Strangler fig pattern routing puts a routing layer in front of a running monolith. For each endpoint, that layer decides whether the legacy code or a new service handles the request. The monolith keeps serving everything you haven't moved. Over time, routes shift one by one until the legacy path carries nothing.
The proxy acts as the control plane because it is the one place where a migration step can be observed, compared and reversed:
- Observed: Every request passes through it, so both backends get the same request ID and the same per-route metrics.
- Compared: It can shadow traffic, sending a copy to the new service and discarding the response, so you can diff results before any user depends on them.
- Reversed: Routing lives in configuration, so rolling back means editing a rule rather than redeploying either application.
These three properties are what separate incremental extraction from a big-bang cutover.
┌──────────────── legacy migration proxy ───────────────┐
client ───────▶ │ assign/propagate request ID · emit per-route metrics │
│ route table: /orders → new · everything else → legacy │
└───────┬──────────────────────┬────────────────┬───────┘
│ primary │ primary ┆ shadow copy
▼ ▼ ┆ (response dropped)
┌───────────────┐ ┌───────────────┐◀┄┄┄┄┄┄┄┘
│legacy monolith│ │ new service │
└───────┬───────┘ └───────┬───────┘
└──────────┬───────────┘
▼
shared / legacy datastore
The pattern suits backend and platform teams whose monolith is still in production and still gaining features. Those teams can't freeze development long enough for a rewrite, so each extraction has to ship alongside ongoing feature work.
client
│ request
▼
┌──────────────────── migration proxy (control plane) ─────────────────────┐
│ 1. assign or propagate request ID; same ID sent to every backend │
│ 2. look up route table (config; rollback = edit a rule, no redeploy) │
│ /orders/* → new service │
│ /invoices/* → legacy, shadow copy to new service │
│ * → legacy │
│ 3. emit per-route metrics: route, backend, status, latency │
│ 4. compare shadow response with primary, then discard it │
└──────────┬──────────────────────┬─────────────────────────┬──────────────┘
│ primary │ primary ┆ shadow copy
▼ ▼ ┆ response:
┌───────────────┐ ┌───────────────┐ ┆ diffed, dropped
│legacy monolith│ │ new service │◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
└───────┬───────┘ └───────┬───────┘
│ │
└───────────┬──────────┘
▼
┌──────────────────────────────┐
│ shared / legacy datastore │
└──────────────────────────────┘
The proxy assigns request IDs and per-route metrics, then uses a config-driven route table to send each endpoint to the legacy monolith or the new service, with an optional shadow copy whose response is compared and dropped, while both backends still share the legacy datastore.
When should you avoid the strangler fig pattern?
The pattern assumes an endpoint can be cut loose along a clean seam. When that assumption fails, the proxy adds cost without removing risk.
Shared transactions or in-process state. If an endpoint commits in the same database transaction as other monolith code, or reads an in-memory cache the monolith mutates, extracting it means replacing a local commit with distributed coordination: sagas, outboxes, compensating writes. That is a redesign, not a routing change.
Small systems. A service a few engineers fully understand can often be rewritten and cut over in one release faster than the strangler infrastructure can be built.
No capacity to run a highly available proxy. Every request now passes through an extra hop. If the proxy fails, both implementations become unreachable, so the system is less reliable than the monolith it replaces.
Parallel running cost. For the whole transition, two implementations of each in-flight endpoint need deploys, alerts, dashboards and on-call coverage. Incidents now start with "which side served this?" Teams budget for the build and underestimate this ongoing load.
| Approach | Risk | Reversibility | Operational overhead | Fits when |
|---|---|---|---|---|
| Big-bang rewrite | High | Poor after cutover | Low during build, high at cutover | Small, well-understood system |
| Branch by abstraction | Low–medium | Good, via code change | Low, one deployable | Coupling is internal to the codebase |
| Modular monolith refactor | Low | Good | Low | Problem is structure, not deployment |
| Feature-flag switching | Low–medium | Fast, flag flip | Moderate, flag hygiene | New code can live in the same process |
How do you choose the first endpoint to extract?
The first endpoint you move is mostly a test of the tooling, so its business value matters less than how cleanly it can be separated. Score candidates against four criteria:
- Bounded data ownership. The endpoint reads from or writes to tables that no other module modifies. If three other code paths update the same rows, you cannot move the endpoint without also moving or coordinating with them.
- Clear request/response contract. Inputs and outputs are explicit and stable. Avoid endpoints that depend on session state, server-side redirects, or undocumented side effects.
- Measurable traffic. The endpoint needs enough requests to compare latency and error rates between the old and new paths, but not so many that a mistake causes a large outage.
- Low coupling to shared transactions. The endpoint does not take part in a database transaction that spans other modules.
Read-heavy endpoints make safer first candidates. A wrong response from a read can be detected, compared against the legacy result, and fixed without corrupting state. A wrong write persists, can spread to other systems, and may need data repair even after you roll the route back.
| Candidate endpoint | Data ownership | Contract clarity | Traffic signal | Transaction coupling | Verdict |
|---|---|---|---|---|---|
GET /products/{id} |
Isolated catalog tables | Stable JSON | Steady, moderate | None | Strong first pick |
GET /orders/history |
Shares order tables | Clear | High | Read-only | Second wave |
POST /checkout |
Spans orders, inventory, payments | Complex | High | Multi-module | Defer |
PUT /profile |
User table, shared with auth | Clear | Low | Partial | Later |
Picking a small, low-risk endpoint first also saves time later. That first extraction proves out the proxy configuration, the per-route dashboards, and the rollback procedure, and every later endpoint reuses them. If you discover tooling gaps on a simple read path, they are cheap to fix. If you discover them during a checkout migration, they are expensive.
How do you put a legacy migration proxy in front of the monolith?
Deploy the proxy as a pure passthrough first
Before you extract anything, put the proxy in front of the monolith with one default rule that forwards every request unchanged. Ship this as a separate release. If something breaks at this stage, the proxy is the only thing that changed.
Test the new hop on its own:
- Latency: Compare request timing at the proxy with the monolith's own timing to measure what the extra hop adds.
- Fidelity: Confirm that
Host, forwarded client-IP headers, cookies and request bodies arrive intact. - Timeouts: Set upstream timeouts longer than the monolith's slowest legitimate request. Otherwise the proxy returns gateway errors the old system never produced.
- Logging: On every request, log the matched rule, the upstream target, the upstream status and the upstream response time.
The proxy now handles all traffic. Run at least two instances behind your existing load balancer. Assign an owning team with on-call coverage before cutover, not after the first incident.
Design routing rules
Match on path, method and, only when needed, headers. Write one explicit rule per extracted endpoint and let everything else fall through to the passthrough default.
Specificity is where most mistakes happen. In NGINX, location = /api/orders matches only that exact path. A prefix rule like location /api/orders also captures /api/orders/export and /api/orders-v1, which quietly sends neighboring routes to the new service. Use exact matches by default. Anchor any regex deliberately, because NGINX evaluates regex locations in file order.
Methods need their own rules too. If only GET has been rebuilt, POST must still reach the monolith.
# Lives in the http {} context. Stage 1 ships only the passthrough default.
# Stage 2 adds one explicit rule per extracted endpoint.
upstream monolith {
server 10.0.1.10:8080;
server 10.0.1.11:8080;
}
upstream orders_service {
server 10.0.2.20:9000;
}
# Only GET has been rebuilt. Every other method on this path stays on the monolith.
map $request_method $orders_upstream {
GET orders_service;
default monolith;
}
# Log the matched rule, the upstream target, the upstream status and the upstream timing on every request.
log_format strangler '$remote_addr "$request" status=$status route=$route '
'upstream=$upstream_addr ustatus=$upstream_status '
'urt=$upstream_response_time rt=$request_time';
server {
listen 80;
access_log /var/log/nginx/strangler.log strangler;
# Keep the request faithful so the monolith sees the same headers it saw before the proxy existed.
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Set this longer than the monolith's slowest legitimate request so the proxy never adds new 504s.
proxy_connect_timeout 5s;
proxy_read_timeout 120s;
# Passthrough default: anything without an explicit rule goes to the monolith unchanged.
location / {
set $route passthrough;
proxy_pass
}
# Exact match only. /api/orders/export and /api/orders-v1 are not captured, so they fall through to /.
location = /api/orders {
set $route orders_exact;
proxy_pass
}
}
An NGINX config that forwards all traffic to the monolith by default and logs each hop, then adds a single exact-match rule that sends only GET /api/orders to the new service.
How does progressive traffic shifting and shadowing work?
Begin with opt-in routing that only your own staff can trigger. A request header such as X-Route-To: new, or a cookie set from an internal admin page, lets engineers and support staff use the new service against production data while every customer stays on the monolith. Strip that header at the edge so external clients cannot set it.
Next, move to percentage splits, bucketed by a stable key rather than per request. Hash the user ID or tenant ID, take the result modulo 100, and route to the new service when the bucket is below the current rollout percentage. Raising the threshold from 5 to 25 only adds users, and nobody already moved returns to the monolith. A random per-request split would make a user bounce between implementations. A pagination cursor issued by one implementation could then be rejected by the other, and bug reports would be hard to reproduce. For B2B systems, bucket by tenant so a whole account sees consistent behavior.
For read endpoints, shadow traffic before you shift it. The proxy mirrors each request to the new service, returns the legacy response to the client, and discards the new service's response after logging it. A diff job then compares the two after normalizing fields that legitimately differ, such as timestamps, generated IDs, and array ordering where order is not part of the contract. Without normalization, that noise hides real mismatches.
Do not mirror writes unless the new service is idempotent on the same keys or writes to a sandboxed datastore. A mirrored POST can send a second email, charge a card twice, or emit duplicate audit events.
Shadowing also roughly doubles downstream load on every mirrored route, including any database both services read from. Plan capacity for that before you enable it.
import hashlib
# Rollout percentage per migrated route; raise it over time (e.g. 5 -> 25 -> 100).
ROLLOUT_PERCENT = {"GET /api/invoices": 25}
def bucket(key: str, route: str) -> int:
# Use a stable hash, not Python's built-in hash(), which is randomized per process.
# Salting with the route name gives each route an independent cohort.
digest = hashlib.sha256(f"{route}:{key}".encode()).digest()
return int.from_bytes(digest[:8], "big") % 100
def choose_backend(route: str, headers: dict, user_id: str, tenant_id: str | None) -> str:
# Internal opt-in. The edge proxy strips X-Route-To from external
# requests, so only staff traffic can still carry it here.
if headers.get("X-Route-To") == "new":
return "new"
percent = ROLLOUT_PERCENT.get(route, 0)
# B2B: bucket by tenant so a whole account sees one implementation.
key = tenant_id or user_id
# Same key always lands in the same bucket, so raising the threshold
# only adds users; nobody moves back to the monolith.
return "new" if bucket(key, route) < percent else "legacy"
if __name__ == "__main__":
for tenant in ["tenant-acme", "tenant-globex", "tenant-initech"]:
print(tenant, choose_backend("GET /api/invoices", {}, "user-42", tenant))
Routing logic that honors an internal-only opt-in header first, then assigns each tenant (or user) to a stable hash bucket so percentage rollouts are sticky and only ever grow.
Who owns the data during incremental extraction, and what breaks the contract?
Shadowing only answers "do the responses match?" The harder question is which system owns a record while both are live. Pick exactly one writer per entity at any moment, because two writers turn every disagreement into a merge problem.
| Approach | Consistency gap | Ordering problems | Complexity |
|---|---|---|---|
| New service reads legacy storage first | None for reads; schemas stay coupled | None, single writer | Low at first, but the legacy schema leaks into the new service |
| Change-data-capture into new store | Replication lag, so reads can be stale | Per-key order usually holds; cross-table order often does not | Medium: connector, offsets, replay handling |
| Dual-write from the application | Partial failures leave stores disagreeing | Concurrent writers can apply updates in different orders | High: retries, idempotency, compensation |
No option is both simple and strongly consistent. Choose the gap you can monitor. Then run reconciliation: a scheduled job that compares keys and hashes of the relevant fields across both stores for a recent window. Alert on drift rates, not individual mismatches, because lag produces transient noise.
Cutovers more often break on contract fidelity than on data. Check these details:
- Status codes, such as 200 with an error flag vs 4xx
- Error body shapes that clients parse
- Header semantics, including casing assumptions,
Location, and custom headers - Pagination: cursor format, page size defaults, ordering stability
- Auth and session handling, including cookie scope and expiry
- Cache headers like
Cache-ControlandETag
Reproduce legacy bugs first, even ugly ones. Each fix you ship during extraction adds expected diffs. Those diffs hide real regressions, and they make rollback comparisons harder to trust. Log known bugs, then fix them after cutover as separate changes.
How do you define rollback, observe each route, and finish the migration?
Rollback is a config change, decided in advance
Write the rollback before the first request moves. It should be one change in the proxy, such as setting orders_route.new_weight: 0, that sends all traffic for the route back to legacy without a deploy of either service. Run it in staging and once in production at low traffic, so you know how long it takes to propagate. Agree on the triggers up front: error rate above legacy's baseline, p99 latency over a set budget, or shadow diff rate above the known-bug level. If you choose these thresholds during an incident, you are negotiating under pressure.
Label every request with its backend
Every metric and log line from the proxy should carry the backend that served it, for example route=/orders backend=legacy status=200 latency_ms=84 request_id=7f3c…. With that label you can plot the error and latency distributions of both backends side by side, which averages hide. Propagate the same request ID to legacy and the new service, so a diff or failure can be traced across all three hops.
Finishing means deleting
When the route has stayed at full weight on the new service for a soak period you agreed on, delete the legacy code path. Then remove the legacy branch of the routing rule and decommission the tables, queues and credentials that only legacy used. Put a removal deadline on each rule when you create it. Without deadlines, the proxy builds up conditional logic and becomes a second monolith.
Running two backends in parallel stays temporary only if this cleanup is scheduled. The proxy config, diff tooling and dashboards you built for the first endpoint carry over, so each later extraction costs less than the first.
# Route weight for /orders. Hashing on $request_id splits per request.
# ROLLBACK: comment out the orders_new line so "*" sends 100% to legacy,
# then run: nginx -t && nginx -s reload (no deploy of either service).
# Rule owner: orders-team. Remove legacy branch by: 2027-03-31.
split_clients "${request_id}" $orders_backend {
10% orders_new;
* orders_legacy;
}
upstream orders_legacy { server legacy.internal:8080; }
upstream orders_new { server orders-svc.internal:9090; }
# Every log line names the backend that served it, so error and
# latency distributions can be compared per backend, not averaged.
log_format orders_kv 'route=/orders backend=$orders_backend '
'status=$status request_time_s=$request_time '
'upstream_time_s=$upstream_response_time '
'request_id=$request_id';
server {
listen 80;
location /orders {
access_log /var/log/nginx/orders.log orders_kv;
# Same ID reaches legacy and the new service, so one request
# can be traced across proxy, legacy and new-service logs.
proxy_set_header X-Request-ID $request_id;
# Tell the backend which branch it is (useful in its own metrics).
proxy_set_header X-Served-Backend $orders_backend;
proxy_pass
}
}
An nginx config that splits /orders traffic between legacy and new upstreams, labels each access-log line with the serving backend and a propagated request ID, and makes rollback a one-line edit plus reload.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to strangler fig pattern routing, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.