What is strangler fig pattern routing, and why does the proxy decide whether the migration succeeds?
Strangler fig pattern routing places a routing layer in front of a running monolith. That layer sends requests for selected routes to new code and passes everything else to the legacy system. Each route moves on its own schedule. Over time the new code handles more of the traffic, until the monolith serves nothing and can be switched off.
client
|
+---------------+
| routing seam | per-route rules: owner, target, weight
+---------------+
| |
(unmigrated) (migrated)
| |
+----------+ +-------------+
| monolith | | new service |
+----------+ +-------------+
\ /
+-------------+
| shared DB |
+-------------+
The alternative is a big-bang legacy rewrite, which postpones all risk to one cutover date and delivers no value until that date. An incremental migration changes the risk profile. Each cutover is small. Each migrated route ships to production as soon as it is ready. Each route also has its own rollback path: if the new code fails, the routing rule points back at the monolith.
That rollback path exists only if the proxy is built to support it. This is the core claim of the article: treat the routing layer as versioned, observable, reversible infrastructure, with an explicit owner for every route. If routing rules are edited by hand and nobody can see per-route error rates, rollback stops being reliable and the migration stalls.
The pattern suits teams that have a large HTTP-facing monolith and a platform or backend team able to own the routing layer. It is the right choice when two conditions hold. First, the system must keep serving traffic throughout the migration. Second, the boundaries you want to cut along are reasonably HTTP-shaped, so a path, method or header can identify them.
+--------+
| client |
+--------+
|
v
+-----------------------------------------------------------+
| routing seam (proxy) |
| route owner target weight |
| /orders/* team-orders new service 100% |
| /invoices/* team-billing new service 10% |
| (default) platform monolith 100% |
| |
| versioned config | per-route metrics | rollback = revert |
+-----------------------------------------------------------+
| |
unmigrated routes migrated routes
| |
v v
+---------------+ +---------------+
| monolith | | new service |
| (legacy) | | |
+---------------+ +---------------+
| |
+-----------------+-----------------+
|
v
+---------------+
| shared DB |
+---------------+
The routing seam holds a versioned rule for every route, with its owner, target and traffic weight, and sends unmigrated routes to the monolith and migrated routes to the new service, both backed by the shared database; rollback means reverting a rule (route names and weights are illustrative).
Where should the routing seam live: edge proxy, API gateway, in-process facade or service mesh?
The seam is where the routing decision executes, and its location determines who can change a route and how quickly.
| Seam | Config owner | Deploy cadence | Added latency | TLS / auth | Request context visible |
|---|---|---|---|---|---|
| Edge reverse proxy | Platform/infra team | Config reload, independent of apps | One extra hop | Usually terminates TLS; auth optional | Host, path, method, headers, cookies |
| API gateway | API platform team | Gateway release or config push | One hop plus plugin processing | Terminates TLS; often validates tokens | Above plus authenticated identity, API key |
| In-process facade | Monolith team | Ships with the monolith | None for local routes; a hop for forwarded ones | Inherits the monolith's | Full session, user, feature flags, domain objects |
| Service mesh | Platform team | Mesh control-plane update | Sidecar hop on each side | mTLS between services | Mostly L7 headers; little business context |
Choose an in-process facade when the platform team cannot change the edge, or when the routing decision depends on data only the monolith holds, such as the tenant plan. Choose an edge reverse proxy when the new code runs on separate infrastructure and you want to cut over without redeploying the monolith. A gateway fits if one already handles auth. A mesh is useful only if both sides already run inside it.
Every option except the in-process facade adds a network hop, latency and a new failure point. If the proxy is a single instance, the migration makes the whole system less reliable than the monolith it replaces. Run at least two proxy instances behind a load balancer. Give each upstream an active health check so traffic stops reaching a dead backend. Set connect and read timeouts on the proxy below the client's timeout, so the proxy fails fast instead of holding connections open.
How do you decide which endpoints to migrate first?
Start from access logs, not the codebase. The router file shows what the monolith can serve, but the logs show what clients actually call. Dead routes, forgotten admin pages and undocumented endpoints that a partner integration still depends on only show up in production traffic.
Paths contain IDs, so normalize them before counting. Replace numeric segments, UUIDs and other opaque tokens with placeholders, so /orders/48213/items becomes /orders/{id}/items. Then count by method and template. With a combined-format log, the method and path are in the quoted request field, and a pipeline of field extraction, a substitution pass and a sort-and-count produces the list. The example below shows one way to build it. Strip query strings first, or they will split one route into thousands of rows.
Rank each template on three axes:
- Traffic: high volume gives you fast feedback on correctness.
- Coupling: count the shared tables it touches and how many other modules write to them.
- Business risk: consider what breaks, and for whom, if the endpoint returns wrong data for ten minutes.
Migrate low-risk, read-heavy endpoints first. A bad read can be rolled back without leaving corrupted state behind.
Look closely at the long tail. Rarely called, poorly understood endpoints are where migrations stall. Both systems stay alive to serve a handful of requests, and that hybrid costs more to run than either system would alone. Decide early, for each tail endpoint, whether to migrate it, retire it, or deliberately keep it in the monolith.
The proxy only sees HTTP traffic. Background jobs, batch processes and logic shared across many endpoints never pass through it, so each of these needs its own migration plan.
#!/usr/bin/env bash
# Build a route inventory from combined-format access logs.
# Usage: ./route-inventory.sh access.log [access.log.1 ...]
# Output: request count, method, path template; busiest first.
set -euo pipefail
awk -F'"' '
{
# Field 2 is the quoted request: METHOD PATH PROTOCOL
split($2, req, " ")
method = req[1]; path = req[2]
if (method == "" || path == "") next # skip malformed lines such as "-"
sub(/\?.*/, "", path) # drop query strings so one route stays one row
# Normalize each segment so IDs collapse into a single template
n = split(path, seg, "/")
out = ""
for (i = 2; i <= n; i++) {
s = seg[i]
if (s ~ /^[0-9]+$/)
s = "{id}" # numeric IDs
else if (length(s) == 36 && s ~ /^[0-9a-fA-F-]+$/)
s = "{uuid}" # UUIDs
else if (length(s) >= 20 && s ~ /^[A-Za-z0-9_-]+$/ && s ~ /[0-9]/)
s = "{token}" # long opaque tokens
out = out "/" s
}
if (out == "") out = "/"
print method "\t" out
}' "$@" \
| LC_ALL=C sort \
| uniq -c \
| sort -rn
# The bottom of this list is your long tail: decide migrate, retire, or keep for each.
An awk pipeline that extracts the method and path from combined-format access logs, strips query strings, replaces numeric IDs, UUIDs and opaque tokens with placeholders, and counts requests per method and path template so the busiest routes and the long tail are both visible.
How does strangler fig routing work at the match-rule level?
Routing granularity sets the migration unit. A path prefix such as /invoices/ moves a whole resource tree at once. An exact path moves a single endpoint. Method plus path lets GET /invoices/{id} move while POST /invoices stays put, which is often the safest first step because reads carry less risk than writes. Header- or cookie-based rules add a second dimension: the same path goes to new code only for flagged clients or internal testers.
In nginx, a typical layout has three parts:
- An exact-match
location =for one endpoint. - A longer prefix block for the migrated tree.
- A catch-all
location /that proxies to the monolith.
nginx resolves conflicts by precedence, not file order. Exact matches win outright. Otherwise the longest matching prefix is selected, unless a regex location also matches, because regexes are checked in file order and the first one wins. A broad regex can therefore shadow a specific prefix unless that prefix uses ^~. Many gateways and route tables instead use first-match-wins in declared order. Under that model, a /api/ rule listed above /api/invoices/ silently captures everything. Before each change, test which backend serves a representative set of URLs.
The new service must also reproduce behavior the monolith provided implicitly, or clients will see a contract change:
- Session cookie validation and authentication.
- Cookie names, paths and flags.
- Response headers and CORS preflight handling.
- Trailing-slash redirects.
- Error body shape and status codes.
- Rate limits and timeouts. Check that the proxy's upstream timeout fits the new service's latency profile.
upstream monolith { server 10.0.0.10:8080; }
upstream invoices_svc { server 10.0.0.20:8080; }
upstream reports_svc { server 10.0.0.30:8080; }
# Method plus path: only reads move; writes stay on the monolith.
map $request_method $invoices_backend {
GET invoices_svc;
HEAD invoices_svc;
default monolith;
}
# Cookie-based: only clients with beta_reports=1 reach the new code.
map $cookie_beta_reports $reports_backend {
"1" reports_svc;
default monolith;
}
server {
listen 80;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Exact match: wins outright; moves one endpoint.
location = /invoices/summary { proxy_pass }
# ^~ stops regex checks, so the regex below cannot shadow this tree.
location ^~ /invoices/ {
proxy_pass
proxy_read_timeout 10s; # sized for the new service's latency
}
location /reports/ { proxy_pass }
# Without ^~ above, this would capture /invoices/123.pdf.
location ~* \.pdf$ { proxy_pass }
# Fallback: anything not yet migrated goes to the monolith.
location / { proxy_pass }
}
An nginx config that routes one exact endpoint, a GET-only invoices tree and a cookie-flagged reports tree to new services, uses ^~ to keep a broad regex from shadowing the migrated prefix, and sends everything else to the monolith.
How do you cut over traffic gradually and roll back instantly?
Route by a stable key, not by request. Hash the user or tenant ID, take the result modulo 100, and send the request to the new service when the bucket falls below the current rollout percentage. For example, hash(tenant_id) % 100 < 5 sends 5% of tenants. A user then stays on one implementation across sessions. Raising the percentage only adds buckets, so users who already moved never move back. Random per-request splitting causes problems: a user sees a field rendered one way, refreshes, and sees it rendered differently. Their bug report then describes behavior that nobody can reproduce, because the next request went to the other backend.
Start with an allowlist of internal accounts, then move to 1%, 5%, 25% and higher, holding at each step long enough to compare error rates and latency. Keep the percentage in runtime configuration, not in a deploy artifact. Rollback should be a single documented change: set the value to 0 and reload the proxy. Write that change in the runbook before the first cutover.
Before any real traffic moves, you can mirror requests to the new code and discard its responses. Diff the two outputs only after normalizing the fields that always differ. Strip timestamps and generated IDs, and sort arrays where order is not part of the contract. Otherwise every comparison fails and real differences get lost in the noise.
Mirror only idempotent reads blindly. A mirrored write runs twice: it can send a duplicate email, charge a card, call a partner API or increment a counter. Shadow writes only when the new code's downstream calls are stubbed.
import hashlib
import json
INTERNAL_TENANTS = {"tenant-internal-qa", "tenant-internal-staff"}
NOISY_KEYS = {"created_at", "updated_at", "request_id", "order_id"}
UNORDERED_KEYS = {"tags", "line_items"} # arrays whose order is not in the contract
def bucket(tenant_id: str) -> int:
# Use a stable hash. Python's built-in hash() is salted per process,
# so it would reshuffle tenants on every restart.
digest = hashlib.sha256(tenant_id.encode("utf-8")).digest()
return int.from_bytes(digest[:8], "big") % 100
def use_new_service(tenant_id: str, rollout_percent: int) -> bool:
# rollout_percent comes from runtime config. Setting it to 0 rolls everyone back,
# internal tenants included.
if rollout_percent <= 0:
return False
if tenant_id in INTERNAL_TENANTS:
return True
# Raising the percent only adds buckets, so migrated tenants never move back.
return bucket(tenant_id) < rollout_percent
def normalize(value, key=None):
# Drop fields that always differ, and sort arrays where order is not meaningful.
if isinstance(value, dict):
return {k: normalize(v, k) for k, v in value.items() if k not in NOISY_KEYS}
if isinstance(value, list):
items = [normalize(v) for v in value]
if key in UNORDERED_KEYS:
items.sort(key=lambda v: json.dumps(v, sort_keys=True))
return items
return value
def shadow_diff(old_body: dict, new_body: dict) -> bool:
# True when the mirrored response matches the response that was served.
return normalize(old_body) == normalize(new_body)
Sticky tenant bucketing with a stable hash and a single rollback value, plus normalization that drops timestamps and generated IDs and sorts unordered arrays before shadow responses are compared.
How should writes and shared data be handled during an incremental migration?
Routing moves requests in an instant, but data cannot follow that quickly. The database is the hardest seam because two codebases can disagree about the same row long after the proxy rules look finished.
| Option | How it works | Main risk | Fits when |
|---|---|---|---|
| Call the monolith for writes | New service reads directly, delegates writes to a monolith endpoint | Latency and coupling to legacy code | Writes are rare or complex |
| Shared store, migrate data last | Both systems use one database; schema moves after the code | Schema changes need coordination | Most migrations |
| Change data capture | Monolith stays the writer; changes stream into a new store | Replication lag, eventual consistency | New service mostly reads |
| Dual writes | Each write goes to both stores | Partial failure, ordering, drift | Rarely; only with reconciliation |
Dual writes look simple and fail quietly. One store commits and the other times out, so the stores now disagree. Two concurrent updates can land in a different order on each side. Small bugs in field mapping cause drift that nobody notices for weeks. If you choose dual writes, declare one store the source of truth for each entity and run reconciliation jobs that detect and repair divergence.
In many cases the cheaper default is to keep one store and migrate the data last. You avoid every consistency problem above, and the schema split becomes a separate, smaller project.
Count the human cost too. Two implementations of the same behavior mean on-call engineers must know both, every bug fix lands twice, and the operational load doubles. That cost lasts until the legacy code is deleted, not until the traffic shifts.
How do you keep route ownership, observability and cleanup from becoming permanent cruft?
Every response should carry a marker of the backend that served it, such as a response header or a structured log field set by the proxy. Without that marker, a latency spike on /orders cannot be attributed to the new service or to the monolith. With it, you can put latency percentiles, error rate and status-code distributions for each route side by side. A shift from 404s to 400s often reveals a validation difference that aggregate dashboards hide.
Define exit criteria before shifting traffic. For example: 100% of traffic on the new backend for two full business cycles, with no rollbacks and with error rates within an agreed margin of the legacy baseline. A route that meets the criteria is fully migrated. A route that does not stays visibly unfinished and does not drift into a permanent split.
Treat the route table as code. It should be versioned and reviewed, and every entry should name an owning team. Add tests that assert which backend serves which path. A table-driven fixture can pair each path and method with its expected backend, so that GET /orders/42 resolves to orders-svc and POST /legacy/reports resolves to monolith. If a reordered prefix rule silently captures traffic, CI fails before the change ships.
After a route meets its exit criteria, delete the legacy handler, its tests and the proxy rule. This keeps the cost of the migration bounded. Each cutover stays small and routine, a regression points to a single route, and a rollback is a config change rather than a redeploy.
When should you avoid the strangler fig pattern, and what are the alternatives?
That bounded cost assumes the system has seams a proxy can see. Several conditions remove that assumption:
- No HTTP boundary. If the important logic runs in batch jobs, queue consumers or shared libraries called in-process, a reverse proxy has nothing to intercept.
- A small codebase. When a rewrite takes weeks rather than quarters, running a routing layer for the whole migration costs more than it saves.
- Entangled data. If every route reads and writes most tables, each cutover drags the whole schema with it. Routes no longer give you independent units of risk.
- No long-term owner. A proxy that nobody maintains becomes the most fragile component in the request path.
| Approach | Risk | Time to first value | Operational overhead | Reversibility |
|---|---|---|---|---|
| Proxy-based strangling | Low per step | Early | High (extra hop, routing config) | Per route, via config |
| Modular monolith refactor | Low | Early | None added | Per commit |
| Branch by abstraction | Low | Medium | Low (flags in code) | Per toggle |
| Big-bang rewrite with parallel run | High | Late | High while both run | Only until old system is retired |
| Leave it alone | Grows slowly | None | Existing cost only | N/A |
Branch by abstraction is the in-process version of the same idea. You put an interface in front of the old implementation, build the new one behind it, and switch over gradually. It works where a proxy can't, such as in batch code and internal calls.
Choose proxy-based strangling when the system has clean HTTP boundaries, a team to own the proxy, and enough remaining lifespan to pay back the extra infrastructure.
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.