What is a strangler fig pattern proxy and why does the routing layer decide the migration?
The strangler fig pattern replaces a legacy system one piece at a time. New code grows around the old system until the old system can be removed. A strangler fig pattern proxy is the reverse proxy you place in front of the monolith. It receives every request and decides, route by route, whether the monolith or a new service handles it. Clients keep calling the same hostnames and paths and never see the split.
Routing is where incremental migration succeeds or fails because every cutover, canary and rollback is a routing change. A typo in a location match can send checkout traffic to a half-built service. A forgotten rule can leave the monolith serving an endpoint you thought you had retired. Treat the proxy configuration like application code:
- Keep it under version control.
- Review changes before they ship.
- Validate syntax in CI.
- Test it against recorded requests before deploying.
This approach suits teams running a live monolith that cannot freeze for a rewrite. It also suits the backend and platform engineers who own production traffic and will be paged when a route goes wrong.
Start with no behavior change. Insert the proxy and pass 100% of traffic straight to the monolith. Then record a baseline:
- p50 and p99 latency
- Error rates by status code
- Log volume and format
Every later route change gets compared against these numbers.
The trade-off is that the proxy adds a network hop and becomes a single point of failure. Run more than one instance behind health checks, monitor the proxy itself, and put its changes under the same change control as a production deploy.
+-----------------------------+
| Clients: same hosts & paths |
+--------------+--------------+
|
v
+-----------------------------+
| LB with health checks |
| (redundant proxy instances) |
+------+---------------+------+
| |
v v
+----------------+ +-------------+ +-------------+ +------------------+
| Git repo | | nginx | | nginx | | Baseline metrics |
| proxy config |--->| proxy #1 | | proxy #2 |--->| p50/p99 latency |
| review + CI | +------+------+ +------+------+ | errors by status |
| syntax check | | | | log volume/format|
+----------------+ +-------+-------+ +------------------+
|
+-------------+--------------+
| 100% at step 1 : later routes
v v
+------------------+ +-------------------+
| Legacy monolith | | New service |
| all routes today | | 0% at step 1 |
+------------------+ +-------------------+
Step one of the strangler fig migration: redundant, version-controlled nginx proxies send 100% of traffic to the monolith while a latency, error-rate and log baseline is recorded. Later route changes will shift endpoints to the new service, shown by the dotted path.
When should you use the strangler fig pattern, and when should you avoid it?
The pattern fits a specific shape of problem: a legacy system that must keep serving users while it is replaced, whose HTTP boundaries line up reasonably well with business capabilities, and whose teams can afford to run two implementations of the same behavior for weeks or months. If any of those conditions is missing, the proxy just moves the difficulty somewhere harder to see.
Avoid or defer it in three situations:
- Chatty or transactionally coupled endpoints. Code that today shares a database transaction or makes dozens of in-process calls per request becomes network calls with latency and partial-failure modes once split.
- A small system. A rewrite or an in-place refactor is cheaper than the routing machinery.
- No commitment to finishing. A stalled migration leaves a permanent hybrid. You pay for two deployments, two on-call rotations and the proxy, which costs more than either the monolith or a finished migration.
Choosing the first endpoint
Pick one that is read-heavy, well bounded, has few side effects and has clear data ownership. A product catalog lookup is a good candidate. Checkout is not. The first cutover tests your routing, observability and rollback, and a read-only endpoint makes mistakes cheap.
Build the route inventory from access logs, not only from the codebase. The code shows every route that exists. The logs show which ones are called, how often, with which methods, and by which clients. Group requests by method and normalized path over a few weeks. Doing so usually turns up dead routes you can delete instead of migrating, and undocumented callers that would otherwise break silently at cutover.
#!/usr/bin/env bash
# Build a route inventory from nginx access logs in the default "combined" format.
# Usage: ./route-inventory.sh /var/log/nginx/access.log* (rotated .gz files are fine)
# Output: requests, method, normalized path, distinct user agents (a rough proxy for callers)
set -euo pipefail
# zcat -f reads gzip files and passes plain-text files through unchanged.
zcat -f "$@" | awk -F'"' '
{
# With " as the separator, $2 is the request line ("GET /path HTTP/1.1") and $6 is the User-Agent.
split($2, req, " ")
method = req[1]; path = req[2]; ua = $6
if (method == "" || path == "") next # skip malformed or empty request lines
sub(/\?.*/, "", path) # drop the query string; route identity is the path
# Collapse IDs so /products/42 and /products/97 count as one route.
n = split(path, seg, "/"); norm = ""
for (i = 2; i <= n; i++) {
s = seg[i]
if (s ~ /^[0-9]+$/) s = ":id"
else if (length(s) == 36 && s ~ /^[0-9a-fA-F-]+$/) s = ":uuid"
norm = norm "/" s
}
if (norm == "") norm = "/"
key = method " " norm
hits[key]++
# Count each distinct caller once per route.
if (!((key, ua) in seen)) { seen[key, ua] = 1; callers[key]++ }
}
END {
for (k in hits) printf "%d\t%s\t%d\n", hits[k], k, callers[k]
}' | sort -t$'\t' -k1,1nr
# Routes in the codebase that never appear here are candidates for deletion.
# Routes with unexpected user agents point to undocumented callers to find before cutover.
A shell and awk script that groups nginx access-log requests by method and ID-normalized path, counts hits and distinct callers per route, and builds an inventory that can be compared against the codebase.
How does nginx routing work for peeling off endpoints?
Define two upstream blocks, legacy and orders, so every routing decision names a pool rather than a hostname. The default location / sends everything to legacy. Each peeled endpoint gets its own location pointing at the new service.
Matching order decides who gets the request
nginx checks = exact matches first. Next it finds the longest matching prefix and remembers it. If that prefix carries ^~, regex locations are skipped. Otherwise regexes are tested in file order, and the first match wins over the remembered prefix. A broad regex such as ~ \.json$, added for one new endpoint, will also capture monolith URLs that happen to end in .json. Nothing errors. The new service just starts returning 404s for paths it never owned. Use ^~ on migrated prefixes and keep regexes rare.
What proxy_pass forwards
Directive in location /api/orders/ |
Request /api/orders/7?x=1 arrives as |
|---|---|
| `proxy_pass | /api/orders/7?x=1 (unchanged) |
| `proxy_pass | /7?x=1 (prefix replaced) |
| `proxy_pass | /v27?x=1 (broken: missing slash) |
The query string is kept in all three cases. Only the matched prefix is rewritten.
Headers and identity
Set Host $host, X-Forwarded-For $proxy_add_x_forwarded_for and X-Forwarded-Proto $scheme on both upstreams. Without these, redirects and absolute URLs leak internal hostnames or Use amapto pass along an incomingX-Request-ID, falling back to $request_id`. That gives one ID for tracing across both backends.
Users must not be able to tell which backend served them. Both services should read the same session cookie, with the same name, domain and path, and validate it against the same session store or signing key. If the new service sets cookies differently, proxy_cookie_domain and proxy_cookie_path can rewrite them. Return identical 401 and redirect behavior from both backends.
# http{} context: reuse an incoming X-Request-ID, otherwise generate one
map $http_x_request_id $req_id {
default $http_x_request_id;
"" $request_id;
}
upstream legacy { server 10.0.1.10:8080; } # the monolith
upstream orders { server 10.0.2.20:8080; } # first peeled-off service
server {
listen 80;
server_name shop.example.com;
# Defined at server level, so both locations inherit them.
# A proxy_set_header inside a location drops ALL of these there.
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Request-ID $req_id;
add_header X-Request-ID $req_id always; # echo the ID to clients
# Migrated prefix. ^~ stops regex locations from stealing these URLs.
# No URI after the upstream name: /api/orders/7?x=1 is forwarded unchanged.
location ^~ /api/orders/ {
proxy_pass
}
# Anti-pattern, kept commented out: this would also capture monolith
# URLs like /reports/daily.json and send them to orders.
# location ~ \.json$ { proxy_pass }
# Everything not yet migrated stays on the monolith.
location / {
proxy_pass
}
}
A strangler-fig nginx config that routes a migrated prefix to the new service with ^~, sends everything else to the monolith, forwards the original path, client and scheme headers, and keeps a single request ID across both backends.
How do you route by method, header, cookie or percentage for canary releases?
Path is only one routing dimension. Once a path is split, nginx can also choose a backend by method, header, cookie or hash bucket, usually with a map that sets a variable used in proxy_pass.
| Strategy | Typical use | Main pitfall |
|---|---|---|
Method ($request_method) |
GET to the new service, POST stays on the monolith | Read-after-write: a write lands in the monolith, and the next read hits a new service that is reading a lagging replica or cache |
Header or cookie ($http_x_canary, $cookie_canary) |
Internal testers opt in | Leaks to real users who copy the header or cookie; shared caches serve one backend's response to everyone |
split_clients |
Percentage canary | Hashing an unstable key such as $request_id makes a single user bounce between backends |
A method split is only safe when both backends read the same authoritative data with no meaningful lag. If they don't, route the whole resource together.
For header or cookie routing, accept only a value that the proxy or your SSO layer sets, and strip anything clients send. Responses that vary by that attribute need Vary or Cache-Control: private, otherwise a CDN may cache the canary response and serve it to everyone.
split_clients hashes whatever key you give it. Use a stable identifier, such as a user ID cookie or $remote_addr as a fallback, so that each user sees one backend consistently.
Every attribute you route on can expose concerns the monolith handled implicitly: auth, session lookup, rate limiting and CSRF tokens. Moving these into the proxy keeps behaviour consistent across backends. The trade-off is that more logic now sits in the proxy, so it needs the same tests and review as application code.
# http {} context. Upstream names must match the values the maps produce.
upstream monolith { server 10.0.1.10:8080; }
upstream new_orders { server 10.0.2.20:8080; }
# Testers: trust only a cookie value your SSO layer sets, never a client-chosen one.
map $cookie_canary $tester { "on" 1; default 0; }
# Stable hash key: user ID cookie, falling back to client IP.
# Never use $request_id here, or a user bounces between backends per request.
map $cookie_uid $canary_key { "" $remote_addr; default $cookie_uid; }
split_clients "${canary_key}" $pct_bucket {
5% new;
* old;
}
# Reads go to the new service for testers or the 5% bucket. Writes stay on the
# monolith. Only safe if both backends read the same primary, with no replica lag.
map "$tester:$request_method:$pct_bucket" $orders_backend {
~^1:(GET|HEAD): new_orders;
~^0:(GET|HEAD):new$ new_orders;
default monolith;
}
server {
listen 80;
location /api/orders/ {
# Drop client-supplied routing hints before they reach either backend.
proxy_set_header X-Canary "";
proxy_set_header Host $host;
# The response depends on cookies, so shared caches must not reuse it.
proxy_hide_header Cache-Control;
add_header Cache-Control "private" always;
add_header Vary "Cookie" always;
proxy_pass
}
}
An nginx config that sends GET/HEAD for /api/orders/ to the new service for SSO-flagged testers and a stable 5% hash bucket keyed on user ID, keeps all writes on the monolith, strips client routing headers and marks responses private so caches cannot leak the canary.
How do you validate parity and handle shared data before cutover?
Before any route flips, prove the new service returns the same answers as the monolith. nginx's mirror directive sends a copy of each matching request to a second upstream and discards that upstream's response, so users only ever see the monolith's reply. Alternatively, replay a sample of logged production requests against the new service. Either way, capture both responses and compare them offline. Strip or normalize fields that legitimately differ, such as timestamps, generated IDs, request IDs and ordering of unordered collections. Then diff status codes, headers that matter, and bodies. Treat every unexplained diff as a blocker. A diff you don't understand is a behaviour you haven't ported.
Mirroring is only safe for idempotent reads. A mirrored POST executes twice. That means two charges, two emails, or two inventory decrements, unless the shadow service writes to fully isolated storage and its outbound side effects are stubbed.
Shared data
Pointing the new service at the monolith's database is a common stopgap. It also creates schema coupling: any column rename in the monolith can break the new service. Sequence ownership so only one system writes a given piece of data at a time:
- The new service reads while the monolith writes.
- Write ownership moves to the new service in a single cutover.
- The monolith either calls the new service's API or reads a replica.
Until the old path is deleted, you are paying for two implementations. Every bug fix and rule change must land twice, and any drift between them shows up as inconsistent results depending on which backend served the request.
Making every route change reversible, observable and finished
Treat the routing config as production code. Keep it in version control, require review for every change, and add config tests that start nginx against stub upstreams, send a fixed set of requests, and assert which upstream each one reached. A test asserting that POST /orders goes to the new service while GET /orders/export still hits the monolith catches the prefix-match and ordering mistakes that reviewers miss. Run nginx -t in CI and again before every reload. Then reload gracefully with nginx -s reload: old workers finish in-flight requests while new workers pick up the config, so a route change drops no connections.
Make the split visible. Add $upstream_addr to the access log format. Better still, set a custom variable such as $route_target in each location block so logs and metrics carry a readable label instead of an IP. Dashboards can then compare error rate and latency per upstream for the same path.
Write rollback criteria before cutover, for example "5xx rate above the monolith's baseline for ten minutes." Keep each migrated endpoint in its own location block. Rolling back then means reverting one commit and reloading, with no build and no redeploy. This saves engineering time in three ways. The blast radius is one endpoint. Triage starts from a log field instead of a guess. Recovery takes as long as a reload.
An endpoint is fully strangled only when all three of these are true:
- The dead monolith code is deleted.
- The legacy fallback rule is removed.
- The endpoint is off a published count of remaining monolith routes.
Track that count where the team sees it. When nobody can see how much of the monolith is left, the migration has no defined end and tends to stop short of one.
What are the alternatives to a strangler fig proxy, and how do they compare on cost?
The proxy is one of several ways to move traffic gradually. The choice depends on where you want the seam: at the network edge, inside the code, or nowhere.
| Approach | Cutover risk | Reversibility | Operational overhead | Team coordination | Development cost |
|---|---|---|---|---|---|
| Strangler fig proxy | Low, per route | Config change | New hop to run | Moderate | Dual implementation |
| Big-bang rewrite | High, all at once | Poor after data moves | Low until launch | High at launch | Full rewrite, frozen features |
| Branch by abstraction | Low | Code deploy | None added | Low, one codebase | Interface work in monolith |
| Modular monolith | Low | Code deploy | None added | Low | Refactoring only |
| Gateway or mesh routing | Low, per route | Config change | Shared platform | Needs platform team | Dual implementation |
| Feature flags | Low | Flag toggle | Flag service and cleanup | Low | Both paths in one app |
Illustrative estimate (assumed numbers, not a benchmark)
The proxy is worth it when:
(P_bigbang − P_incremental) × incident_cost > dual_hours_per_week × weeks + proxy_setup_hours
Assume the following inputs:
- Dual maintenance costs 4 hours per week for 30 weeks.
- Proxy setup takes 40 hours.
- That gives a total overhead of 160 hours.
- A failed cutover costs 400 hours.
- The chance of a failed cutover is 0.5 for big-bang and 0.1 for incremental.
The expected saving is (0.5 − 0.1) × 400 = 160 hours. That is exactly break-even. Change any one input and the answer flips, so run the calculation with your own numbers before deciding.
When to choose each alternative:
- Branch by abstraction or a modular monolith: the target is cleaner code, not separate deployment. Neither adds network overhead.
- Gateway or mesh routing: one already exists and a platform team runs it.
- Feature flags: the new path lives in the same process.
- Big-bang rewrite: the system is small, has few integrations, and can tolerate a feature freeze.
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 proxy, 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.