How to Migrate from Monolith to Microservices Without Destroying Everything

Let me tell you about our first microservices migration attempt in 2019. We had a Rails monolith that worked fine, but management wanted to "scale for the future." What we had: a Jenkins box that worked sometimes, zero monitoring beyond server CPU graphs, and the confidence that only comes from never having debugged distributed systems.

The migration was supposed to take 4 months. It took 22 months, and we had to bring in 3 contractors just to keep the lights on. Here's what we learned the hard way about the infrastructure and mindset you actually need before you even think about extracting your first service.

You Need Actual Monitoring, Not Dashboard Theater

The Hard Truth About Observability
When your user service is down but still responding 200 OK to health checks, and your payment service is throwing 500s but your load balancer thinks everything is fine, you'll understand why monitoring actually matters.

We started with ELK stack version 7.8 because it's "industry standard." Elasticsearch 7.8.0 ate all our memory - went from 8GB to 32GB and still ran out during log ingestion spikes. The specific error was "CircuitBreakerService: [parent] Data too large" every damn time. Logstash configurations are written in a language that makes Perl look readable, and Kibana crashed with "CircuitBreakingException" every time we tried to query more than 1GB of logs.

Eventually settled on Grafana + Prometheus. Prometheus 2.40 is powerful but the query language makes SQL look friendly - try figuring out rate(http_requests_total[5m]) when you've been debugging for 6 hours straight. Grafana 9.3's documentation assumes you already know how everything works, which is fucking useless when you're trying to set up your first dashboard at 2am.

What You Actually Need:

• Distributed tracing that doesn't require a PhD to understand (Jaeger 1.38 works, but good luck with the setup - we spent 2 days figuring out why spans weren't correlating properly)
• Centralized logging that can handle your actual log volume (not the demo 100 events/day bullshit) - ELK stack or Loki
• Alerts for when shit breaks (which it will, constantly) - Prometheus AlertManager is decent once you figure out the YAML syntax hell
• The ability to correlate errors across services (harder than it sounds - trace IDs get lost between HTTP calls) - check OpenTelemetry
• Metrics collection that actually tells you what's broken, not just CPU usage graphs - Prometheus metrics are the standard
• Health checks that aren't just "HTTP 200 OK" - we had services returning 200 while their databases were completely down - implement proper health checks
• Service discovery so services can find each other (Consul 1.16 works but the networking configuration will make you cry - check Consul docs)
• Circuit breaker patterns to prevent cascading failures (implement these BEFORE everything breaks, not after) - Martin Fowler's pattern is the classic reference
• APM tools like Datadog or New Relic if you have budget - they actually help with debugging distributed traces
• Centralized configuration management so you don't hardcode everything

CI/CD That Actually Works (Not Jenkins Held Together With Duct Tape)

Your current Jenkins 2.401.3 setup that requires 20 minutes of prayer and clicking "rebuild" three times won't cut it when you have 15 services that need to deploy independently. We had builds failing with "java.lang.OutOfMemoryError: Java heap space" every other day because Jenkins was trying to build 8 services simultaneously with 2GB of RAM allocated. The fucking thing would crash with "hudson.AbortException: script returned exit code 137" and we'd lose 45 minutes of build time.

Each microservice needs its own build, test, and deploy pipeline. When authentication service v2.1.3 breaks user login, you need to rollback just that service to v2.1.2 without touching anything else. If your deployment process involves SSHing into servers and running sudo systemctl restart application, stop reading this and go fix that first - you're not ready for microservices.

GitLab CI is decent if you can stomach YAML hell - we had 847-line pipeline files that nobody understood. CircleCI works but gets expensive fast (we paid $2,400/month for 15 services) - they execute pipelines 40% faster than GitHub Actions but your wallet will feel it. GitHub Actions is fine for simple stuff but will make you want to throw your laptop when you need anything complex - their Docker layer caching is dogshit. Jenkins is the old reliable that everyone hates but still uses - at least when it breaks, you can actually debug it with Blue Ocean plugin.

Team Reality Check (AKA Why Your Developers Will Hate You)

What Management Thinks: "Our team can handle microservices, they're smart!"

What Actually Happens: Your senior dev quits 6 months in when they realize authentication now requires understanding OAuth flows, JWT validation, service mesh networking, and debugging distributed transactions that span 8 services. Your junior dev has a panic attack trying to figure out why a request is timing out somewhere between the API gateway and the database.

Skills You Actually Need (Not Suggestions, Requirements):

• Someone who's debugged Docker networking issues at 3am
• Someone who understands eventual consistency and doesn't panic when data isn't immediately consistent
• Someone who can read Kubernetes YAML without crying
• Someone who's comfortable with the fact that "it works on my machine" is now meaningless

Database Separation: Where Dreams Go to Die

Splitting your database is not "just add foreign keys to another DB." We spent 8 months just figuring out how to handle user authentication across services without violating GDPR or creating 47 different user tables. JWT tokens kept expiring mid-request with "TokenExpiredException" in production because our services had clock drift issues.

The problem isn't technical - it's archaeological. Your monolith's database has years of accumulated technical debt, implicit relationships that exist only in application code, and business rules scattered across stored procedures, triggers, and application logic. Extracting a clean service from this mess is like performing surgery with a chainsaw.

What Nobody Tells You:

• Transactions across services are basically impossible - welcome to the Saga pattern hell where you implement rollback logic for 8 different failure modes
• Your carefully normalized database will become 6 different databases with duplicated data (and they'll drift apart over time)
• Database migrations become coordination nightmares across teams ("Did the user service deploy their schema change yet?")
• Referential integrity is now your application's problem, not the database's - enjoy debugging orphaned records

When to Definitely NOT Do This

If Your Monolith Works Fine: Seriously, just stop. A working monolith beats a broken microservices architecture 100% of the time. Netflix didn't adopt microservices because they were cool - they adopted them because their monolith literally couldn't handle their scale. Your e-commerce site with 50 concurrent users does not have Netflix's scale.

If You Don't Have 24/7 Operations: Microservices fail in creative ways at 2am on Saturday. If your team isn't prepared to wake up and debug why the payment service is returning 503s while everything else looks fine, stick with your monolith.

If Your Team Has Never Used Docker in Production: Containerization is not optional for microservices. If Dockerfile is a foreign language to your team, spend 6 months learning containers first.

The biggest red flag: if your reason for migrating is "we want to use modern technology" or "it will be easier to maintain," you're migrating for the wrong reasons. Microservices are harder to maintain, not easier.

The stuff above isn't optional - it's the foundation that will determine whether your migration succeeds or becomes a cautionary tale. Most teams skip these basics and wonder why their first service extraction takes 6 months and breaks production twice.

Once you've got your monitoring, CI/CD, and team reality checks sorted (and only then), you're ready to start the actual migration process. Which, as you'll see in the next section, is where the real fun begins.

So you've got monitoring that might actually tell you when things break, CI/CD that doesn't require blood sacrifice, and a team that won't quit when they see what they've signed up for. Now comes the actual migration - the part where theory meets the brutal reality of production systems.

Forget the strangler fig metaphor - it sounds nice but doesn't help when you're debugging why user authentication is randomly failing for 3% of requests. Here's what the migration actually looks like, based on our painful experience extracting 12 services from a 200K line Rails monolith.

Phase 1: Setting Up Your Traffic Control (And Immediately Regretting It)

Step 1: The Proxy Layer That Will Haunt Your Dreams

You need something between your users and your services. We started with NGINX because "it's simple." NGINX config files are not simple. They're written in a language that hates you personally. Try debugging a 400-line nginx.conf file at 3am when you can't remember which location block is handling /api/users/profile. The NGINX documentation is comprehensive but assumes you already know what you're doing.

After three weeks of fighting NGINX's URL rewriting rules and SSL termination configs (and getting "400 Bad Request" errors with zero useful logging), we switched to AWS Application Load Balancer. More expensive ($22/month per ALB) but at least when it breaks, it's Amazon's fault, not yours. Kong is another option if you enjoy Lua configuration hell - finding developers who understand Kong plugins is harder than finding blockchain experts.

The routing rules look simple on paper:

/api/users/* → User Service
/api/orders/* → Order Service  
Everything else → Monolith

Reality: Half your URLs don't match clean patterns, you have nested routes that overlap, and now you need to handle authentication at the proxy layer too.

Step 2: Pick Your First Victim (I Mean, Service)

Everyone will tell you to start with something "simple" like notifications or reporting. This is bullshit advice. Here's what actually works:

Start with something read-only that you can easily rollback when it inevitably breaks. We chose our admin dashboard API because if it went down for a few hours, only internal users would complain.

DO NOT start with:

• Authentication (you'll break login for everyone)
• Payments (your company will lose money)
• Core business logic (users will notice immediately)
• Anything with complex database transactions

Step 3: The Anti-Corruption Layer (AKA Feature Flag Hell)

You need a way to switch between old and new implementations without redeploying everything. Here's what we built:

class UserServiceRouter
  def get_user(id)
    if use_microservice?(id)
      call_user_microservice(id)
    else
      User.find(id)
    end
  rescue => e
    # When the microservice is broken, fallback to monolith
    Rails.logger.error "Microservice failed: #{e.message}"
    User.find(id)
  end
  
  def use_microservice?(user_id)
    # Gradually roll out by user ID
    (user_id.to_i % 100) < Settings.microservice_percentage
  end
end

This worked until we realized we needed this pattern for 47 different method calls. Now we have 47 feature flags and nobody remembers what they all do.

Phase 2: Building Services That Actually Work (Harder Than It Sounds)

Step 4: Your First "Production-Ready" Service

Production-ready is in quotes because your first service will not be ready for production. It will crash in ways you didn't know were possible.

Database Per Service Is Not Optional

Don't try to share databases between services. Just don't. We tried this with our user service sharing the users table with the monolith. Six months later we had PostgreSQL 13 deadlocks every 20 minutes with "ERROR: deadlock detected, process 2847 waits for ShareLock on transaction 95832", migration conflicts from Rails 6.1 vs Spring Boot 2.7 (trying to deploy schema changes simultaneously), and a user table with 73 columns because every service kept adding "just one more field." The database became a dependency nightmare where changing one column required coordinating deploys across 6 different services. Read about the database per service pattern to understand why this matters.

API Versioning Will Make You Cry

Version your APIs from day one, even if you think you won't need it. We didn't version our user API. Three months later when we needed to change the response format, we had to coordinate deployments across 8 different services that consumed the API.

Use /v1/users not /users. Trust me. Check out API versioning best practices or Stripe's API versioning approach for examples of how to do this right.

Step 5: Data Migration: The Thing That Takes 80% of Your Time

The Strangler Fig pattern assumes clean boundaries between services. Your monolith has no clean boundaries. Everything is connected to everything else.

Our user service migration took 4 months because:

• Users were referenced by 23 different tables
• Some references were soft-deleted records we couldn't find
• The user login logic was scattered across 12 different files
• We had 3 different "user" concepts (customer users, admin users, API users)

What Actually Happens:

1. You think you've identified all the dependencies
2. You move the user data to the new service
3. Password reset breaks because it was using a direct database query
4. You fix password reset
5. Admin reports break because they were joining users with orders
6. You fix admin reports by adding an API call
7. Page load times go from 200ms to 2 seconds because of the API call
8. You spend 3 weeks optimizing API calls and caching
9. You discover user preferences are stored in a different table you forgot about
10. Everything breaks again

Phase 3: Traffic Migration (Where Everything Goes Wrong)

Step 6: Parallel Running (AKA Doubling Your AWS Bill)

Before switching traffic, run both the old and new code for every request and compare the results. This sounds expensive because it is expensive. Our AWS bill went up 40% during this phase.

You'll discover:

• The new service returns slightly different JSON formats
• Null handling is different between systems
• Date formatting is inconsistent
• The new service is 3x slower than the old code

Step 7: Gradual Rollout (Prayer-Driven Development)

Start with 5% traffic, not 10%. When the new service starts returning 500 errors for 15% of requests at 2am on a Sunday, you'll want that rollback to be as fast as possible.

Our rollout schedule that actually worked:

• 5% for 1 week (you'll find basic bugs like "NullPointerException")
• 10% for 1 week (you'll find load-related bugs like connection pool exhaustion)
• 25% for 1 week (you'll find race conditions and "ConcurrentModificationException")
• 50% for 2 weeks (you'll find the really subtle bugs like timezone issues)
• 100% only after you're confident it won't explode at 3am on Saturday

Circuit Breakers Are Not Optional

When your new service goes down (not if, when), you need automatic fallback to the monolith. We used Hystrix at first but it's been deprecated since 2018. Switched to resilience4j which is fine but the documentation assumes you already know how circuit breakers work. Also consider Polly for .NET applications.

Phase 4: The Cleanup That Never Ends

Step 8: Removing Old Code (Harder Than Writing New Code)

You extracted the user service, everything works, time to delete the old code, right? Wrong.

You'll discover:

• Some admin tool still uses the old user model
• A batch job runs once a month that nobody knew about
• There's a webhook that directly queries the user table
• The old user validation logic is subtly different from the new logic

We have 47 "TODO: remove after user service migration" comments from 2 years ago that are still in the codebase. Git blame shows they were added in commit a7f2c91 on March 15, 2022.

Step 9: Doing It Again (And Again, And Again)

Each service extraction teaches you new ways distributed systems can fail:

• Service A calls Service B which calls Service C, and now a single request spans 3 different failure domains
• Database transactions don't work across services, so you need to implement saga patterns or event sourcing
• Your monitoring needs to trace requests across multiple services
• Debugging requires tailing logs from 6 different places

By the time you extract service #5, you'll be an expert at distributed systems failure modes. This is not a good thing.

What Nobody Tells You About Conway's Law

Your microservices architecture will mirror your team structure whether you want it to or not. If you have a monolithic team, your "microservices" will be tightly coupled. If you have separate teams that don't talk to each other, you'll end up with services that duplicate functionality. Conway's Law is inevitable.

The technical migration is the easy part. The organizational changes - figuring out who owns which service, how teams coordinate deployments, who gets woken up when things break - that's the hard part that will make or break your migration.

By now you should be thoroughly convinced that microservices migration is harder than anyone told you. But if you're still determined to proceed (or your boss won't let you out of it), you need to understand which migration patterns actually work in practice versus which ones just sound good in architecture meetings.

Spoiler alert: most of the "industry standard" patterns are bullshit that only work in pristine codebases that don't exist in the real world.

Patterns are nice and all, but you still need actual tools to implement this migration disaster. The vendor marketing materials will tell you everything is "enterprise-ready" and "production-proven." The reality is most tools are designed by people who've never operated them in production.

Here's what we learned about the tools that will either save your ass or destroy your will to live, usually discovered at 3am on a Friday while your boss is asking why everything is broken.

Container Orchestration: Choose Your Nightmare

Kubernetes: You'll Hate It, But You Need It
Kubernetes won the container war. Everyone uses it because everyone else uses it. Learning curve is brutal - YAML files that are longer than your college thesis, networking concepts that require a PhD in distributed systems, and error messages like "CrashLoopBackOff" that tell you absolutely nothing useful.

But once you get past the initial "what the fuck is a pod" phase, it actually works. Auto-scaling works most of the time (unless you set the CPU thresholds wrong). Rolling deployments work until they don't (and then you have 3 pods running the old version and 2 running the new one). Service discovery works if you configure DNS correctly and understand the difference between ClusterIP, NodePort, and LoadBalancer.

The real problem: your first Kubernetes 1.28 deployment will take 3 months longer than planned because nobody on your team actually understands how ingress controllers work. We spent 2 weeks debugging "502 Bad Gateway" errors that turned out to be misconfigured NGINX ingress rules - the backend service was running on port 8080 but the ingress was trying to reach port 80.

Docker Swarm: The Simple Option Nobody Uses
Docker Swarm is what Kubernetes should have been - simple, predictable, does what it says. Problem is Docker Inc basically abandoned it. Use it for small teams or when you can't justify hiring a Kubernetes expert.

API Gateways: Your Traffic Control Nightmare

AWS API Gateway: Expensive But Someone Else's Problem
AWS API Gateway works well, scales automatically, costs a fortune when you have high traffic. Configuration is done through the world's worst web interface. Cold starts will randomly add 2 seconds to your requests. Check the pricing calculator before committing - we hit $1,200/month with moderate traffic.

Good choice if you have money and hate managing infrastructure. Bad choice if you're watching costs or need sub-100ms response times. Consider AWS Lambda proxy integration for serverless setups.

Kong: The DIY Option That Requires a Lua Expert
Kong is powerful and free (the open source version). Problem is you need to learn Lua to configure anything complex. Their documentation assumes you're already a Kong expert.

We used Kong for 2 years. It worked fine once we figured out the plugin system. Finding developers who understand Lua plugins is harder than finding blockchain experts.

NGINX: Simple Until It Isn't
NGINX config files look simple until you need SSL termination, load balancing, and custom routing rules. Then they look like someone's fever dream written in a language that hates readability. The NGINX documentation is comprehensive but not beginner-friendly.

But it's fast, stable, and every DevOps engineer knows how to fix it when it breaks. Consider NGINX Plus if you need commercial support.

Databases: Where Your Migration Goes to Die

PostgreSQL: The Safe Choice
PostgreSQL 15 handles 90% of use cases well. ACID transactions actually work (unlike some databases I could mention). JSON support is decent - better than MySQL's half-assed attempt. Performance is predictable once you understand query planning and have proper indexes. Your DBAs already know how to optimize it, and there's a metric fuckton of documentation.

Use it unless you have a specific reason not to. "We want to try something new" is not a specific reason - that's how you end up with CouchDB in production and nobody knows how to query it. PostgreSQL 15 has been battle-tested by companies bigger than yours.

MongoDB: When You Want to Hate Your Future Self
MongoDB 6.0 is fine for prototyping and storing unstructured data. It's terrible for anything requiring complex queries or data consistency. We lost 3 hours of user data during a "balancer migration" that failed silently.

We migrated one service to Mongo because "document storage matches our domain model." Six months later we were running 47-line aggregation queries that would have been 3 lines of SQL.

Redis: Fast But Your Data Will Disappear
Redis is blazing fast for caching and sessions. It's also volatile - your data can disappear if the server reboots. Use it for data you can afford to lose, not for anything important.

Perfect for session storage and cache. Terrible for your main data store, no matter what the Redis marketing team tells you.

Message Queues: Event-Driven Complications

Kafka: Powerful and Painful
Kafka 3.3 handles massive scale and never loses messages. It also requires a team of Java experts to tune, understand, and debug. Zookeeper 3.8.0 management will make you question your career choices - we had "ZooKeeper ensemble not ready" errors bring down the entire messaging system for 4 hours.

Use it if you actually need the scale (millions of events per day). Use something simpler if you don't.

RabbitMQ: It Just Works (Until It Doesn't)
RabbitMQ is reliable and straightforward. Management UI is decent. Clustering can be tricky but it's manageable.

Good choice for most teams. Handles 99% of message queue needs without requiring a PhD in distributed systems.

Monitoring: Because Everything Will Break

Prometheus + Grafana: The Standard Nightmare
Prometheus is the de facto standard for metrics. PromQL query language makes SQL look friendly. Grafana dashboards are powerful once you figure out how they work.

Setup takes weeks. Once working, it's solid. Budget for a full-time person to maintain the dashboards and queries.

ELK Stack: Elasticsearch Will Eat Your RAM
The ELK stack (Elasticsearch, Logstash, Kibana) is standard for centralized logging. Elasticsearch will consume all available memory and ask for more. Logstash configs are written in a DSL that hates humans.

Works well once configured. Budget 2x the memory you think you need.

Datadog: Expensive But Worth It
Datadog costs a fortune but actually works out of the box. Good dashboards, useful alerts, traces that help you debug distributed failures.

If you have the budget, just use Datadog. Your time is worth more than the cost difference.

CI/CD: Automation That Automates Your Pain

GitLab CI: Decent All-in-One Solution
GitLab CI is integrated with version control and works well for most teams. YAML pipeline configs are readable. Docker support is solid.

Main downside: when GitLab is down, your entire development process stops.

Jenkins: The Enterprise Monster
Jenkins can do anything. It can also do nothing if you configure it wrong. Plugin ecosystem is huge and mostly broken. UI looks like it's from 2003 because it is.

Use it if you have complex enterprise requirements or someone forces you to. Otherwise, use anything else.

GitHub Actions: Simple and Effective
GitHub Actions is straightforward and well-documented. Easy to set up, hard to mess up. Limited compared to Jenkins but sufficient for most projects.

Good default choice unless you have weird requirements.

The Reality Check

Most migrations fail because teams choose tools they don't understand. Kubernetes isn't better than Docker Swarm if your team doesn't know Kubernetes. Kafka isn't better than RabbitMQ if you don't need Kafka's scale.

Start with the simplest thing that could possibly work. Add complexity only when you actually need it, not because it sounds impressive in meetings.

The best tool is the one your team can actually operate in production at 3am when everything is on fire.

All this tool knowledge is useless if you don't know what questions to ask when everything inevitably breaks. The next section covers the questions people actually ask when they're 6 months into their migration and wondering if they should update their LinkedIn profile.