Ease Mesh

A service mesh compatible with the Spring Cloud ecosystem. Using Easegress as a sidecar for service management & EaseAgent as a monitor for service observability.

1. Purposes

Why do we reinvent another wheel?

  • Service mesh compatible with Spring Cloud ecosystem: The micro-services developed in Spring Cloud ecosystem have their own service registry/discovery system, this is quite different with Kubernetes ecosystem which uses the DNS as the service discovery. Currently, the major Service Mesh solution (e.g. Istio) using the Kubernetes domain technology. So, this is painful and conflicted with Java Spring Cloud domain. EaseMesh aims to make Service Mesh compatible with Java Spring Cloud completely.

  • Integrated Observability: Currently Kubernetes-based service mesh only can see the ingress/egress traffic, and it has no idea what’s happened in service/application. So, combining with Java Agent technology, we can have the full capability to observe everything inside and outside of service/application.

  • Sophisticated capability of traffic split: The EaseMesh has the sophisticated capability of traffic split, it can split traffic of a request chain into not only first service but also last. The capability could be applied in the canary deployment, online production testing scenarios.

Shortly, the EaseMesh leverages the Kubernetes sidecar and Java Agent techniques to make Java applications have service governance and integrated observability without change a line of source code.

2. Principles

  • Spring Cloud Compatibility: Spring Cloud domain service management and resilient design.
  • No Code Changes: Using sidecar & Java-agent for completed service governance and integrated observability.
  • Service Insight: Service running metrics/tracing/logs monitoring.

3. Architecture

The architecture diagram

4. Features

  • Non-intrusive Design: Zero code modification for Java Spring Cloud application migration, only small configuration update needed.
  • Java Register/Discovery: Compatible with popular Java Spring Cloud ecosystem’s Service register/discovery(Eureka/Consul/Nacos).
  • Traffic Orchestration: Coloring & Scheduling east-west and north-south traffic to configured services.
  • Resource Management: Rely on Kubernetes platform for CPU/Memory resources management.
  • Canary Deployment: Routing requests based on colored traffic and different versions of the service.
  • Resilience: Including Timeout/CircuitBreaker/Retryer/Limiter, completely follow sophisticated resilience design.
  • Observability: Including Metrics/Tracing/Log,e.g. HTTP Response code distribution, JVM GC counts, JDBC fully SQL sentences, Kafka/RabbitMQ/Redis metrics, open tracing records, access logs, and so on. With such abundant and services-oriented data, developers/operators can diagnosis where the true problems happened, and immediately take corresponding actions.

5. Dependent Projects

  1. MegaEase EaseAgent
  2. MegaEase Easegress

6. Quick Start

6.1 Environment Requirement

  • Linux kernel version 4.15+
  • Kubernetes version 1.18+
  • Mysql version 14.14+

6.2 Sanity Checking

  • Running kubectl get nodes to check your Kubernetes cluster’s healthy.

6.3 Installation

Please check out install.md to install EaseMesh.

7. Demonstration

  • Spring Cloud PetClinic microservice example.

  • It uses Spring Cloud Gateway, Spring Cloud Circuit Breaker, Spring Cloud Config, Spring Cloud Sleuth, Resilience4j, Micrometer and Eureka Service Discovery from Spring Cloud Netflix technology stack.

The topology migration diagram

Prepare the emctl

git clone https://github.com/megaease/easemesh
cd emctl && make
export PATH=$(pwd)/bin:${PATH}

7.1 Start PetClinic in EaseMesh

7.1.1 Step 1: Apply mesh configuration

Apply the EaseMesh configuration files

emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/a-pet-tenant.yaml
emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/api-gateway.yaml
emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/customers.yaml
emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/ingress.yaml
emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/vets.yaml
emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-conf/visits.yaml

7.1.2 Step 2: Create namespace

leverage kubectl to create spring-petclinic namespace

kubectl create namespace spring-petclinic

7.1.3 Step 4: Setup Database

Petclinic needs to access database, the default is memory database. But in the EaseMesh quick start, you need to prepare a Mysql database for the demo.

Use the DB table schemes and records from PetClinic example to set up yours.

7.1.4 Step 3: Apply petclinic stack

Deploy petclinic resources to k8s cluster, we have developed an operator to manage the custom resource (MeshDeployment) of the EaseMesh. Meshdeployment contains a K8s’ complete deployment spec and a piece of extra information about the service.

The Operator of the EaseMesh will automatically inject a sidecar to pod and a JavaAgent into the application’s JVM

kubectl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-deployments/api-gateway-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-deployments/customers-service-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-deployments/vets-service-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/mesh-deployments/visits-service-deployment.yaml

ATTENTION: There is a ConfigMap spec in yaml file, it describes how to connected the database for applications. You need to change as per your real environment

7.1.5 Get exposed port of EaseMesh ingress service

kubectl get service -n easemesh easemesh-ingress-service

ATTENTION: From the output, you may notice exposed port of the Ingress service. If you needn’t use reverse proxy service, you can directly access pet-clinic application via http://{your_host}:{exposed_port}/

7.1.6 Step 5: Configure reverse proxy

ATTENTION: The step is optional. It can be omitted when you have no requirements about reverse proxy. Config reverse proxy via Easegress

ATTENTION: Only for scenarios that the Easegress acts as the role of reverse proxy service

If you leverage the Easegress as a reverse proxy service, the following configuration can be applied.

HTTP Server spec (file name: http-server.yaml):

kind: HTTPServer
name: spring-petclinic-example
port: 443
https: true
keepAlive: true
keepAliveTimeout: 75s
maxConnection: 10240
cacheSize: 0
  key: {add your certs information to here}
  - paths:
    - pathPrefix: /
      backend: http-petclinic-pipeline

HTTP Pipeline spec (file name: http-petclinic-pipeline.yaml):

name: http-petclinic-pipeline
kind: HTTPPipeline
  - filter: requestAdaptor
  - filter: proxy
  - name: requestAdaptor
    kind: RequestAdaptor
    method: ""
    path: null
      del: []
        Host: "{you host name, can be omitted}"
        X-Forwarded-Proto: "https"
        Connection: "upgrade"
        Host: "{you host name, can be omitted}"
  - name: proxy
    kind: Proxy
      - url: http://{node1_of_k8s_cluster}:{port_exposed_by_ingress_service}
      - url: http://{node2_of_k8s_cluster}:{port_exposed_by_ingress_service}
        policy: roundRobin

Change contents in {} as per your environment, and apply it via Easegress client command tool egctl:

egctl apply -f http-server.yaml
egctl apply -f http-petclinic-pipeline.yaml

egctl is the client command line of the Easegress

Visiting PetClinic website with $your_domain/#!/welcome Config reverse proxy via Easegress

ATTENTION: Only for scenarios that the Nginx acts as the role of reverse proxy service

if you leverage the Nginx as a reverse proxy service, the following configuration should be added.

Then configure the NodPort IP address and port number into your traffic gateway’s routing address, e.g, add config to NGINX:

location /pet/ {
    proxy_pass http://{node1_of_k8s_cluster}:{port_exposed_by_ingress_service}/;

ATTENTION: that the PetClinic website should be routed by the / subpath, or it should use NGINX’s replacing response content feature for correcting resource URL:

location /pet/ {
    proxy_pass http://{node1_of_k8s_cluster}:{port_exposed_by_ingress_service/;
    sub_filter 'href="/' 'href="/pet/';
    sub_filter 'src="/' 'src="/pet/';
    sub_filter_once  off;

Visiting PetClinic website with $your_domain/pet/#!/welcome.

7.2 Canary Deployment

Canary deployment demonstrates how to route coloring traffic (request) to a canary version of the specific service.

EaseMesh Canary topology

  • Customer Service (v2) is the canary version service.
  • The line of red color in the diagram represents coloring traffic (request).
  • The coloring traffic is correctly routed into canary version service after it has passed through the first service (API Gateway).

7.2.1 Step 1: Coloring traffic

Coloring traffic with HTTP header X-Canary: lv1 by using Chrome browser’s ModHeader plugin. Then EaseMesh will route this colored traffic into the Customer service’s canary version instance.

7.2.2 Step 2: Apply canary configuration of the EaseMesh

Apply mesh configuration file:

emctl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/canary/customer-canary.yaml`

7.2.3 Step 3: Prepare a canary version of the application

ATTENTION You can skip the step, we have provides the canary image to docker hub megaease/spring-petclinic-customers-service:canary you can found it in the docker hub.

Developing a canary version of Customer service to add an extra suffix to the city field for each record.

diff --git a/spring-petclinic-customers-service/src/main/java/org/springframework/samples/petclinic/customers/model/Owner.java b/spring-petclinic-customers-service/src/main/java/org/springframework/samples/petclinic/customers/model/Owner.java
index 360e765..cc2df3d 100644
--- a/spring-petclinic-customers-service/src/main/java/org/springframework/samples/petclinic/customers/model/Owner.java
+++ b/spring-petclinic-customers-service/src/main/java/org/springframework/samples/petclinic/customers/model/Owner.java
@@ -99,7 +99,7 @@ public class Owner {

    public String getAddress() {
-        return this.address;
+        return this.address + " - US";

    public void setAddress(String address) {k

7.2.4 Step 4: Build canary image

ATTENTION You can skip the step, we have provides the canary image to docker hub megaease/spring-petclinic-customers-service:canary you can found it in the docker hub.

Building the canary Customer service’s image, and update image version in https://github.com/megaease/easemesh-spring-petclinic/blob/main/canary/customers-service-deployment-canary.yaml. Or just use our default canary image which already was in it.

7.2.5 Step 5. Deploy canary version

Being similar to 7.1.4, we leverage kubectl to deploy the canary version of MeshDeployment

kubectl apply -f https://raw.githubusercontent.com/megaease/easemesh-spring-petclinic/main/canary/customers-service-deployment-canary.yaml`

ATTENTION: There is a ConfigMap spec in echo yaml spec, it describes how to connect the database for applications. You need to change its contents for your environment.

7.2.6 Step 6: Sending coloring traffic

Turning on the chrome ModHeader plugin to color the traffic, then visit PetClinic website. You can see the change to the table which adds an “-US” suffix to every city record.


7.3 Clean

  • Run kubectl delete namespace spring-petclinic.
  • Run
emctl delete ingress pet-ingress
emctl delete service api-gateway
emctl delete service customers-service
emctl delete service vets-service
emctl delete service visits-service
emctl delete tenant pet

8. Roadmap

See EaseMesh Roadmap for details.

9. Contributing

See MegaEase Community to follow our contributing details.

10. License

EaseMesh is under the Apache 2.0 license. See the LICENSE file for details.

11. User Manual

See EaseMesh User Manual for details.