Monolith to Microservices: A Docker + K8s Migration Story

Migrating from a monolithic application to a microservices architecture is a transformational step for any organization. For teams looking to scale, improve agility, or resolve operational bottlenecks, this guide shares insights on refactoring a monolithic system into containers, leveraging Docker and Kubernetes (K8s) for service deployment, and implementing service discovery and communication. Learn from lessons gained during this transition to ensure a smoother migration in your own context.

Table of Contents

1. The Original Monolithic Architecture
2. Refactoring the Application into Containers
3. Service Discovery and Communication in Kubernetes
4. Lessons Learned During the Migration
5. Final Thoughts

The Original Monolithic Architecture

Monolithic architectures are characterized by tightly coupled components running as a single application. This design works well for small teams or early-stage products but often struggles to scale or adapt to feature velocity as the codebase grows.

Architecture Overview

The original architecture had the following characteristics:

• Single Codebase: All logic (frontend, backend, and database) resided in one repository.
• Technology Stack: A Spring Boot backend with embedded services for authentication, payment processing, and data aggregation.
• Deployment: The entire application was deployed as a single .war file on a virtual machine or single cloud instance.
• Challenges:
  • Scalability limitations: Scaling required creating multiple copies of the entire application.
  • Release dependencies: A bug in one module required rebuilding and redeploying the entire application.
  • Team bottleneck: Developers working on different features frequently caused integration conflicts.

Illustration of Monolithic Architecture:

+--------------------------------------------------+
|                  Monolith Application            |
|  +--------+   +---------+   +-----------------+  |
|  | User   |   | Payment |   | Data Aggregator |  |
|  | Auth   |   | Service |   | Service         |  |
|  +--------+   +---------+   +-----------------+  |
|                Single Build & Deployment         |
+--------------------------------------------------+

Why Migrate to Microservices?

1. Independent Scaling: Services like “payment” or “authentication” can scale independently based on load.
2. Faster Deployments: Teams deploy specific components without tying up the entire application.
3. Fault Isolation: A single service failure doesn’t bring down the entire app.

Refactoring the Application into Containers

The first step toward microservices was containerization.

Key Steps to Break Down the Monolith

1. Identify Service Boundaries:
   Decouple the monolith by identifying modules that can function as standalone services. For instance, PaymentService was separated from the main app and converted into its own service.
   • Example breakdown for services:
     • User Authentication Service
     • Payment Service
     • Data Aggregator Service
2. Create Independent Codebases:
   Split each service into a separate repository, enabling independent development and testing.
3. Define APIs for Communication:
   Use RESTful endpoints for inter-service communication. For example: POST /payment/process GET /auth/validate Spring Boot Example: @RestController public class PaymentController { @PostMapping("/process") public ResponseEntity<String> processPayment(@RequestBody Payment payment) { return ResponseEntity.ok("Payment processed."); } }
4. Create Dockerized Services:
   Containerize each service using Docker. Each service gets its Dockerfile. Example Dockerfile: FROM openjdk:17-jdk-slim WORKDIR /app COPY target/payment-service.jar /app/payment-service.jar ENTRYPOINT ["java", "-jar", "payment-service.jar"] Build and tag the Docker image: docker build -t payment-service .
5. Store Images in a Container Registry:
   Push the built images to Docker Hub or an internal container registry: docker tag payment-service myregistry/payment-service:v1 docker push myregistry/payment-service:v1

Microservices Architecture (Containerized):

+-------------------------+   +-------------------------+
| User Auth Service       |   | Payment Service         |
| Containerized via Docker|   | Containerized via Docker|
+-------------------------+   +-------------------------+
          \                          /  
           +------------------------+  
           |     Data Aggregator     |
           +------------------------+

Service Discovery and Communication in Kubernetes

Once the services were containerized, they were deployed in Kubernetes for scalability, service discovery, and management.

1. Deploying Services in Kubernetes

Each microservice is deployed as a Kubernetes Deployment to ensure high availability and resilience.

• Example Deployment (Payment Service): apiVersion: apps/v1 kind: Deployment metadata: name: payment-service spec: replicas: 2 selector: matchLabels: app: payment-service template: metadata: labels: app: payment-service spec: containers: - name: payment-service image: myregistry/payment-service:v1 ports: - containerPort: 8080
• Expose with a Kubernetes Service apiVersion: v1 kind: Service metadata: name: payment-service spec: selector: app: payment-service ports: - protocol: TCP port: 80 targetPort: 8080 type: ClusterIP

2. Service Discovery in Kubernetes

Kubernetes automatically registers Services, enabling other pods to discover them using DNS.

• Internal DNS Resolution: http://payment-service.default.svc.cluster.local

3. Inter-Service Communication

The User Auth Service can call Payment Service via an HTTP client:

RestTemplate restTemplate = new RestTemplate();
String response = restTemplate.getForObject("http://payment-service/process", String.class);

4. Load Balancing and Scaling

HPA Example:
Automatically scale Pods based on CPU utilization:

kubectl autoscale deployment payment-service --cpu-percent=50 --min=2 --max=10

Lessons Learned During the Migration

Migrating a monolith into microservices is no trivial task. Here are some key lessons from the migration process:

1. Break Down Gradually:
   Refactor one module at a time rather than breaking the entire monolith at once. Start with less-business-critical services to build confidence.
2. Test APIs Thoroughly:
   API contracts between services should be rigorously tested using tools like Postman or integration tests to avoid breaking communication.
3. Monitor Everything:
   Implement observability from day one using Prometheus and Grafana. Track metrics like latency, errors, and resource utilization.
4. Database Challenges:
   Migrating from a single database to service-specific databases is challenging. Use strategies like CDC (Change Data Capture) for data-sharing between services.
5. Cultural Shift:
   Microservices require teams to adopt a DevOps-focused mindset. Invest in CI/CD pipelines to automate builds and deployments.

Lessons Summary Diagram:

+----------------------+-------------------------+
| Monolith Issues      |   Microservice Solution |
+----------------------+-------------------------+
| Single Point of Fail | Independent Services    |
| Difficult to Scale   | Horizontal Scaling      |
| Slow Deployments     | Faster, Smaller Deploys |
+----------------------+-------------------------+

Final Thoughts

Migrating from a monolith to microservices is a rewarding yet complex process. It unlocks advantages like scalability, modularity, and ease of deployment while introducing challenges in orchestration and management. Docker and Kubernetes provide a powerful ecosystem to support this transition effectively.

Use this guide’s actionable steps and insights to plan your own migration strategy and ensure a seamless evolution from monolithic to microservices architecture.