/CD pipelines, and document new operational runbooks.

Code Examples

Monolith Route Extraction via API Gateway (Kong)

# kong.yaml
_format_version: "3.0"
services:
  - name: legacy-monolith
    url: http://monolith-internal:8080
    routes:
      - name: legacy-all
        paths: ["/api"]
        strip_path: false
  - name: order-service
    url: http://order-service:3000
    routes:
      - name: order-route
        paths: ["/api/orders"]
        strip_path: false
        strip_path: false

New Microservice Entry Point (Node.js/Express)

const express = require('express');
const { createTracer } = require('./observability');
const app = express();
const tracer = createTracer('order-service');

app.use(express.json());

app.post('/api/orders', async (req, res) => {
  const span = tracer.startSpan('create-order');
  try {
    const order = await OrderRepository.create(req.body);
    await EventBus.publish('order.created', order);
    res.status(201).json(order);
  } catch (err) {
    span.setStatus({ code: 2, message: err.message });
    res.status(500).json({ error: 'Order creation failed' });
  } finally {
    span.end();
  }
});

app.listen(3000, () => console.log('Order service running'));

Architecture Decisions

Pitfall Guide

1. The Distributed Monolith
   Extracting code without decoupling data or communication patterns creates a network-bound monolith. Services still share databases, synchronous chains, and tight coupling. Result: higher latency, identical failure modes, increased operational overhead.

2. Synchronous Service-to-Service Chaining
   Deep call chains (>3 services) amplify tail latency and create cascading failures. Replace with event-driven publishing or async request patterns. Implement timeouts and circuit breakers at every hop.

3. Ignoring Eventual Consistency
   Attempting to preserve monolithic ACID guarantees across services leads to distributed transactions, two-phase commits, and operational complexity. Design for eventual consistency with idempotent consumers and reconciliation jobs.

4. Underinvesting in Observability
   Microservices multiply failure surfaces. Without distributed tracing, structured logging, and metric correlation, debugging becomes guesswork. Deploy OpenTelemetry instrumentation before routing production traffic.

5. Treating Migration as a Feature Project
   Migration requires dedicated architectural runway, not sprint backlog items. Without executive sponsorship, baseline metrics, and incremental validation, teams default to feature delivery, stalling extraction.

6. Neglecting Team Topology (Conway's Law)
   Microservices amplify organizational structure. If teams remain centralized, service boundaries become political rather than technical. Align service ownership with cross-functional product teams.

7. Premature Containerization Without Decoupling
   Wrapping a monolith in containers or Kubernetes does not extract services. It packages coupling, multiplies resource waste, and creates false progress. Decouple first, containerize second.

Production Bundle

Action Checklist

• Instrument monolith with OpenTelemetry, structured logging, and dependency graphing
• Map bounded contexts using DDD tactical patterns and change-frequency analysis
• Deploy API gateway with route-based traffic splitting and contract testing
• Extract highest-value bounded context; duplicate data subset via CDC
• Implement event-driven communication for cross-service state changes
• Establish SLOs, error budgets, and progressive delivery pipelines
• Run chaos experiments to validate failure isolation and degradation paths
• Decommission legacy code paths; archive artifacts; update runbooks

Decision Matrix

Configuration Template

# k8s/service.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  labels:
    app: order-service
    version: v1
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
      annotations:
        sidecar.istio.io/inject: "true"
    spec:
      containers:
      - name: order-service
        image: registry.internal/order-service:1.2.0
        ports:
        - containerPort: 3000
        env:
        - name: OTEL_SERVICE_NAME
          value: "order-service"
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: host
        resources:
          requests:
            cpu: 250m
            memory: 512Mi
          limits:
            cpu: 1000m
            memory: 1Gi
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10
---
# gateway/route.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: order-route
spec:
  parentRefs:
  - name: api-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/orders
    backendRefs:
    - name: order-service
      port: 3000
      weight: 100

Quick Start Guide

1. Baseline & Instrument: Deploy OpenTelemetry agents to the monolith. Export dependency graphs, latency percentiles, and error rates. Establish pre-migration SLOs.
2. Define & Route: Identify the first bounded context. Deploy an API gateway. Configure route-based traffic splitting. Validate contract compatibility with consumer-driven tests.
3. Extract & Sync: Build the new service. Mirror relevant data using CDC or logical replication. Implement event publishing for state changes. Run shadow traffic for 7–14 days.
4. Cutover & Validate: Shift 100% of traffic to the extracted service. Monitor SLOs, error budgets, and cost metrics. Decommission legacy code. Document runbooks and iterate.

Migration is not an architectural destination; it is a continuous extraction discipline. Teams that treat it as incremental validation, not wholesale replacement, achieve sustainable velocity, isolated failure domains, and cloud-native resilience.