What is strangler fig pattern routing, and why put a reverse proxy in front first?
Strangler fig pattern routing is incremental migration driven by a routing layer. You put a reverse proxy in front of the monolith. Then you move functionality out one route at a time. The proxy decides, per request, whether the monolith or a new service handles it. The monolith shrinks as routes leave it, and eventually it can be switched off.
Install the proxy first, before you extract anything, and point every route at the monolith. This step has no visible effect, which is the point. It shows that the proxy handles your real traffic correctly: headers, timeouts, body sizes, TLS and client IPs. It does this before any second system exists to confuse the diagnosis. Once that holds, every later cutover is only a routing change, not a client change or a DNS change.
How requests flow
- Steady state: client → proxy → monolith, for all paths.
- Mid-migration: client → proxy. A request to
/invoices/*goes to the new billing service. Everything else still goes to the monolith.
Why teams use it
Each step is small and can be reversed. If the new service misbehaves, you point the route back at the monolith. You don't need to roll back a deploy.
It also separates deployment from release. You can deploy the new service to production, warm it up and test it directly while the proxy still sends it no user traffic. Releasing traffic becomes a separate, quick change to the proxy config. That saves engineering time: teams stop coordinating big-bang launch windows, and a bad release is limited to one route.
(1) STEADY STATE: proxy installed first, every route points at the monolith
+--------+ +----------------+ all paths +-----------------+
| Client |----->| Reverse proxy |--------------->| Monolith |
+--------+ +----------------+ | (all endpoints) |
+-----------------+
(2) MID-MIGRATION: one route moved; cutover is only a proxy config change
+--------+ +----------------+ other paths +-----------------+
| Client |----->| Reverse proxy |--------------->| Monolith |
+--------+ | | | (shrinking) |
| routing table | +-----------------+
| /invoices/* ->| /invoices/* +-----------------+
| billing |--------------->| Billing service |
| /* -> monolith| | (new) |
+----------------+ +-----------------+
Deploy != release: billing runs and is tested directly before any
route points at it. Releasing traffic means editing the routing table.
Rollback: point /invoices/* back at the monolith. No redeploy needed.
The reverse proxy goes in front of the monolith with every route unchanged, so each later extraction, such as moving /invoices/ to a new billing service, is a reversible routing change and not a client or DNS change.*
Who should use strangler fig routing, and when should you avoid it?
The pattern fits best when the monolith already speaks HTTP and its endpoints map cleanly to business capabilities. If /invoices/* reads and writes only invoice tables, the proxy can move that prefix as a unit. It also needs a team that will run the proxy as critical infrastructure, with on-call ownership, config review and capacity planning, rather than as a convenience layer someone set up once.
Poor fits
- Multi-endpoint transactions. A checkout that calls three endpoints inside one database transaction cannot be split by path. If one call goes to the new service, you lose atomicity and inherit distributed-consistency problems the proxy cannot solve.
- In-process state. Session data held in memory, local caches that other handlers depend on, or sticky-session assumptions all break when requests for one user land on two different processes.
- Small codebases. If a rewrite takes weeks, the proxy, dual deployments and parallel monitoring can cost more than simply replacing the system.
- Teams without capacity to finish. A half-migrated system is harder to operate than either end state. It has two codebases, two deploy pipelines and routing rules nobody fully remembers.
The proxy's own cost
Every request now passes through one more component. That adds a network hop of latency, a component that has to be sized for peak traffic plus headroom, and a single point of failure unless you run it redundantly. Plan for the proxy's availability to cap the availability of everything behind it.
How do you choose the routing key and the first endpoint to move?
The routing key determines how much traffic a misconfigured rule can misdirect, and how quickly you notice.
| Routing key | Blast radius | Typical failure mode |
|---|---|---|
| Exact path | One endpoint | New route stays on the monolith because of a trailing slash or case mismatch |
| Path prefix | Every route under the prefix | Neighbouring endpoints silently move with it |
| HTTP method | One verb on a path | Writes and reads split across two codebases with divergent validation |
| Header | Clients that send it | Missing header falls back to the monolith without warning |
| Tenant or user ID | Selected accounts | Uneven load, and bugs that affect only those accounts |
Prefer exact-path rules. A prefix like /orders also matches /orders/export and /orders/{id}/refund, including endpoints added to the monolith after you wrote the rule. Those requests reach a service that returns 404 or, worse, a plausible but wrong response. An exact-path rule fails closed: anything unlisted stays where it was.
Choose the first endpoint by coupling, not importance. A read-only or low-write route that touches few tables lets you test the proxy, deployment and observability path without also solving data consistency. A lookup or status endpoint works well for this. Checkout is a poor first choice.
Before moving a route, map its data dependencies. Trace one request and list every table it reads or writes. Include triggers, ORM lazy loads and side effects such as audit rows or cache invalidation. Then search for other code paths that write those tables. If a table has writers outside the route you are moving, the new service either needs read access to the shared schema for now, or the route is not ready to move.
How do you implement the shadow, canary, cutover and delete sequence?
Keep the proxy config in version control and change it one stage at a time, so every routing decision is a reviewable diff with a one-commit rollback.
Shadow a read endpoint
Start with an exact-path match (in NGINX, location =) rather than a prefix. A prefix like /orders silently captures /orders-export and /orders/legacy. Use the mirror directive to send a copy of each request to the new service. NGINX discards the mirrored response, so clients only ever see the monolith's answer. Mirror only reads. A mirrored POST that charges a card, sends an email or writes a row executes twice. That is acceptable only if the new service writes to isolated storage and calls stubbed third parties.
Diff responses with normalization
Log both responses and compare them offline. Raw diffs are mostly noise, so normalize before comparing:
- Error formats: map both error formats to a common shape.
- Pagination: compare pagination by item set, not cursor tokens.
- Rounding: round decimals to the precision the contract promises.
- Header casing: lowercase header names.
Track the remaining mismatch rate per field.
Canary by cohort
Use split_clients keyed on a user or tenant ID header or cookie, not the client IP. Hashing the ID keeps each user on the same backend across requests, which avoids inconsistent reads mid-session. Raise the percentage in small steps.
Cutover, delete, and test the routes
Cutover means pointing the location at the new upstream. Delete the monolith handler only after a full release cycle without rollback.
Test routing like code. Keep a table of request paths and expected upstreams, and assert against it in CI. This catches prefix overlaps and ordering bugs before they reach production.
# http context. Stage changes land as separate commits: shadow -> canary -> cutover.
upstream monolith { server monolith.internal:8080; }
upstream orders_v2 { server orders-v2.internal:8080; }
# Sticky cohort: hash the tenant ID, not the client IP, so a tenant
# stays on one backend across requests. Raise 5% in small steps.
split_clients "${http_x_tenant_id}" $invoices_backend {
5% orders_v2;
* monolith;
}
server {
listen 80;
# Stage 1: shadow a READ endpoint. Exact match, so /api/orders-export
# and /api/orders/legacy are not captured.
location = /api/orders {
limit_except GET { deny all; } # never mirror writes
mirror /_shadow_orders; # copy goes to orders_v2
mirror_request_body off;
proxy_pass # clients only see this response
}
# Internal target for the mirror; NGINX discards its response.
location = /_shadow_orders {
internal;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass
}
# Stage 2: canary by cohort. Variable resolves to an upstream name.
# Stage 3 (cutover) replaces this with: proxy_pass
location = /api/invoices {
proxy_pass
}
# Everything else stays on the monolith until migrated.
location / { proxy_pass }
}
An NGINX config that shadows an exact-path read endpoint with a discarded mirror and canaries another endpoint by hashing a tenant ID header with split_clients.
How do you preserve request semantics and observability across the proxy?
What must survive the hop
A proxy that quietly rewrites requests makes the new service look broken when it isn't. Check each item:
- Host and scheme. Pass the original
Hostor setX-Forwarded-HostandX-Forwarded-Proto. Otherwise redirects and absolute URLs point at internal hostnames or ` - Client IP. Append to
X-Forwarded-For(orForwarded). Have the new service trust that header only from the proxy's addresses, so rate limits and audit logs don't key on the proxy. - Auth and sessions. Forward
Authorizationand cookies unchanged. Session cookies must decode the same way on both backends, which usually means a shared session store or signing key. - Limits and timeouts. Match the monolith's request body limit. Set the proxy timeout longer than the upstream's, so the upstream fails first with a meaningful error instead of a generic 504.
- Streaming. Disable response buffering on chunked, server-sent event and large-download routes. Otherwise clients stall until the proxy has received the whole body.
Cross-cutting concerns
Authentication, rate limiting and CSRF checks often live in monolith middleware. You have three options:
- Duplicate them in the new service. This is the fastest option, but the two copies drift apart over time.
- Move them to the proxy. Policy lives in one place, but the proxy becomes security-critical and the monolith's behavior changes too.
- Share a library or verification service. You keep one implementation, but deploys become coupled.
Whichever option you choose, no route should end up with zero checks.
Observability
Have the proxy tag logs and metrics with the backend that served each request. Propagate the W3C traceparent header so one trace covers both the proxy and the upstream. You can then compare latency and error rates for the same route on the old and new paths.
# http {} context. One log line per request records which backend served it.
log_format strangler '$remote_addr "$request" $status backend=$backend '
'upstream=$upstream_addr rt=$request_time urt=$upstream_response_time '
'traceparent="$http_traceparent"';
upstream monolith { server monolith.internal:8080; }
upstream orders_svc { server orders.internal:9000; }
server {
listen 443 ssl;
server_name shop.example.com;
ssl_certificate /etc/nginx/tls/shop.example.com.crt;
ssl_certificate_key /etc/nginx/tls/shop.example.com.key;
access_log /var/log/nginx/strangler.log strangler;
client_max_body_size 10m; # same body limit the monolith enforces today
# Set once at server level: a proxy_set_header inside a location would
# stop these from being inherited. Authorization, Cookie and traceparent
# are passed through unchanged by default.
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
location /api/orders/ {
set $backend orders;
proxy_pass
proxy_read_timeout 35s; # service's own deadline is 30s, so it fails first
}
location /api/orders/export { # large streamed download
set $backend orders;
proxy_pass
proxy_buffering off; # send bytes to the client as they arrive
proxy_read_timeout 300s;
}
location / { set $backend monolith; proxy_pass }
}
An nginx strangler proxy that preserves Host, scheme and client IP, matches the monolith's body limit, unbuffers a streaming route, sets the proxy timeout above the service's own deadline, and logs the serving backend alongside the incoming traceparent so you can compare old and new paths.
How do you handle data ownership and rollback during the migration?
Routing moves traffic in seconds, but data does not move that fast. Before the first write reaches the new service, decide which datastore is authoritative for each entity, and record that decision for every phase of the migration. If two stores can each accept writes and neither is named authoritative, divergence is guaranteed, and you will find out about it in a support ticket.
| Option | Coupling | Partial-failure risk | Stale-read risk |
|---|---|---|---|
| New service reads the monolith's database | High: schema changes break both | Low: one store | None, but you inherit the old schema |
| Dual writes from application code | Medium | High: one write succeeds, the other fails, and nothing reconciles them | Low |
| Change-data-capture sync | Low: consumes a change stream, not tables | Low: replay from the log | Replication lag causes reads after a write to return old data |
Dual writes look simple and fail quietly. Without a distributed transaction, you need a reconciliation job, so this option is rarely cheaper than CDC. With CDC, routes that read their own writes must stay on the side that owns the writes until lag is bounded and monitored.
Rollback is a routing change: flip the route back to the monolith. Rehearse it until it takes seconds. Agree on the trigger thresholds before cutover: error rate, p95 and p99 latency, and the response-diff mismatch rate from shadowing. That way nobody has to argue during an incident about whether to roll back.
Before cutover, rollback is free. After the new service has taken writes, rollback is only safe if those writes flow back to the monolith's store, through reverse CDC or a shared database. Otherwise, routing back hides data that users have already created.
What does strangler fig routing cost, and what are the alternatives?
The proxy itself is cheap to run. The expensive part is that every endpoint in flight has two implementations: two codebases, two deploy pipelines, and two on-call surfaces. Fixes also stop landing in one place. A bug patched in the new service is lost if you route back, and a patch in the monolith's handler does nothing once traffic has moved. That duplication is tolerable for weeks. A migration that stalls halfway leaves you paying for both systems indefinitely.
Finishing each slice is what keeps the cost bounded. Once an endpoint has served 100% of traffic for an agreed soak period without a rollback, remove three things in one change: the monolith handler, its tests, and the proxy rule. Put one number on a dashboard: routes still pointing at the monolith. If that number is not falling, the migration is not converging.
Illustrative estimate (assumed numbers, not a benchmark): monthly duplication cost = routes in dual state × maintenance hours per route per month. With 12 routes × 3 hours, that is 36 engineer-hours a month, spent only on keeping both versions alive.
| Approach | Better choice when | Main risk |
|---|---|---|
| Strangler fig routing | Boundaries map cleanly to routes, and you must keep shipping | Stalling with two live systems |
| Big-bang rewrite | The system is small, its behaviour is well specified, and features can be frozen | Months with no delivered value, plus missed edge cases |
| Branch by abstraction | The seam is internal, such as data access or a library, not an HTTP route | The abstraction layer outlives the migration |
| Modularise in place | The problem is coupling, not independent deployment or scaling | Deploys and runtime remain shared |
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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.