How Easegress Integrates with EaseMesh for Service Mesh Functionality

EaseMesh is built directly on top of Easegress, utilizing three core components—MeshController, Master, and Worker—to orchestrate service discovery, traffic routing, and observability across microservices deployments.

The megaease/easegress repository provides the foundational data-plane and control-plane logic that powers EaseMesh. By leveraging Easegress's programmable pipeline architecture, EaseMesh delivers sidecar-based service mesh capabilities without requiring a separate infrastructure layer. This integration allows operators to manage mesh traffic using the same configuration patterns and extension points available in standalone Easegress deployments.

Core Architecture Components

The integration relies on three primary components defined in pkg/object/meshcontroller/. Each component runs as an Easegress object managed by the supervisor.

MeshController (Business Controller)

The MeshController acts as the entry point for mesh functionality. Located in pkg/object/meshcontroller/meshcontroller.go, this component registers itself with the Easegress supervisor and instantiates the appropriate role based on configuration.

The controller supports three distinct roles:

• Master: Runs the control-plane leader logic
• Worker: Deploys as a sidecar alongside application containers
• Ingress-Controller: Handles north-south traffic into the mesh

The controller parses the MeshController specification and creates the corresponding role object, enabling the same Easegress binary to function as either a centralized controller or a distributed sidecar.

Master (Control-Plane Leader)

The Master component, implemented in pkg/object/meshcontroller/master/master.go, operates exclusively on the leader node in clustered deployments. It maintains the authoritative state of the service mesh through several critical functions:

• Service Registry: Stores service instance specifications and status in the cluster's KV store using keys defined by layout.ServiceInstanceSpecKey() and layout.ServiceInstanceStatusKey()
• Health Monitoring: Performs periodic heartbeat checks via checkLastHeartbeatTime() to identify and clean stale instances
• Certificate Management: When spec.Admin.Security is configured, creates a self-signed CA via certmanager.NewCertManager() to issue per-instance mTLS certificates

The master ensures only healthy, registered instances participate in mesh traffic and coordinates security material distribution to sidecars.

Worker (Sidecar)

The Worker component in pkg/object/meshcontroller/worker/worker.go implements the data-plane sidecar functionality. Deployed adjacent to application containers, the worker handles local traffic interception and mesh communication.

Key responsibilities include:

• Label Parsing: Reads Kubernetes pod labels defined in pkg/object/meshcontroller/label/label.go to determine service identity and configuration
• Instance Registration: Builds a ServiceInstanceSpec and registers with the master via registryServer.Register()
• Server Orchestration: Creates local Ingress and Egress servers that route intra-mesh traffic using Easegress's native pipeline capabilities
• Health Reporting: Periodically calls the mesh-alive-probe endpoint and updates heartbeat status via updateHeartbeat()

The worker bridges the application container with the mesh control plane, enabling transparent service discovery and load balancing.

Configuration and Deployment

MeshController Specification

Mesh configuration begins with a MeshController custom object. An example specification resides in example/config/mesh-controller-example.yaml:

kind: MeshController
name: easemesh-controller
apiPort: 13009
ingressPort: 19527
registryType: consul
heartbeatInterval: 5s

• apiPort: Exposes the master's API server for sidecar communication
• ingressPort: Defines where the Ingress-Controller role accepts external HTTP traffic
• registryType: Specifies the underlying service registry (Consul, Eureka, or Nacos)
• heartbeatInterval: Controls the frequency of health checks between workers and the master

Sidecar Injection via Labels

EaseMesh uses Kubernetes pod labels for sidecar discovery and configuration. The label constants are defined in pkg/object/meshcontroller/label/label.go:

Label Key	Purpose
mesh-role	Identifies the role: master, worker, or ingress-controller
mesh-service-name	Declares the service identity for the instance
mesh-service-labels	Optional comma-separated key=value pairs for service tagging
mesh-application-port	Port where the primary application container listens
mesh-alive-probe	HTTP endpoint URL for health checking

When a pod carries mesh-role=worker, the Easegress sidecar reads these labels during initialization in worker.New() to construct the local service configuration.

Service Registration and Health Monitoring

Instance Registration Process

When a worker sidecar starts, it executes the registration sequence defined in pkg/object/meshcontroller/worker/worker.go:

1. Spec Construction: Parses pod labels to populate a ServiceInstanceSpec structure (defined in pkg/object/meshcontroller/spec/spec.go)
2. Registry Connection: Connects to the master via registryServer.Register() using the cluster's KV store
3. Status Initialization: Writes initial heartbeat status to layout.ServiceInstanceStatusKey(service, instance)

The master stores this information persistently, enabling other workers to discover the new instance for load balancing.

Heartbeat and Lifecycle Management

The mesh maintains instance health through a coordinated heartbeat mechanism:

Worker Side:

• Runs worker.heartbeat() in a background goroutine
• Calls the mesh-alive-probe URL at the configured interval
• Reports status to the master via updateHeartbeat()

Master Side:

• Executes master.checkLastHeartbeatTime() periodically
• Compares last heartbeat timestamp against timeout thresholds
• Marks instances OUT-OF-SERVICE when probes fail
• Cleans stale entries from the KV store when instances remain unhealthy beyond the cleanup threshold

This ensures traffic routes only to healthy instances while automatically removing failed nodes from the service registry.

Traffic Management and Security

Ingress and Egress Servers

Each worker creates local traffic proxies to handle mesh communication without modifying application code:

• Ingress Server: Accepts incoming requests from other mesh services and forwards them to the local application container on mesh-application-port
• Egress Server: Intercepts outbound calls from the application and routes them to target services via the mesh control plane

These servers leverage Easegress's native HTTP pipeline capabilities, allowing operators to apply filters, rate limiting, and circuit breaking to inter-service traffic.

Optional mTLS Implementation

When security is enabled via spec.Admin.Security, the mesh automatically provisions certificates:

1. CA Creation: The master initializes certmanager.NewCertManager() to generate a self-signed Certificate Authority
2. Certificate Issuance: The master creates per-instance certificates signed by the CA
3. Distribution: Workers receive certificates through the control plane API and configure them in the AgentConfig
4. Encryption: Sidecars use these certificates to establish mutual TLS connections for all mesh traffic

This provides zero-trust security without requiring manual certificate management.

Ingress Controller Role

When configured with mesh-role=ingress-controller, the component creates an IngressController object (pkg/object/meshcontroller/ingresscontroller). This role:

• Watches the mesh service registry for available backends
• Builds Kubernetes-compatible ingress rules (spec.Ingress) mapping external host/path combinations to internal mesh services
• Exposes the mesh to north-south traffic on the configured ingressPort

This allows external clients to reach mesh services through a unified entry point while maintaining the internal service mesh architecture.

End-to-End Traffic Flow

The complete request path through an EaseMesh deployment follows this sequence:

1. External Request: Client hits the Ingress Controller on ingressPort
2. Routing Decision: Ingress Controller selects a healthy backend instance from the master registry
3. Mesh Transport: Request travels to the target worker's Ingress server
4. Local Delivery: Worker forwards to the application container on mesh-application-port
5. Outbound Handling: If the application calls another service, the Egress server intercepts and routes through the mesh
6. Health Verification: Workers continuously report status via mesh-alive-probe to maintain registry accuracy

Summary

• EaseMesh extends Easegress through three core components: MeshController, Master, and Worker, all residing in pkg/object/meshcontroller/.
• MeshController orchestrates the control plane and supports three roles: master (leader), worker (sidecar), and ingress-controller.
• Kubernetes labels drive sidecar configuration, with keys like mesh-service-name and mesh-application-port defined in pkg/object/meshcontroller/label/label.go.
• Automatic health management occurs through heartbeats between workers and the master, with instances marked OUT-OF-SERVICE when probes fail.
• Optional mTLS provides zero-trust security via the master's certificate manager, issuing per-instance certificates stored in the cluster KV store.

Frequently Asked Questions

How does EaseMesh differ from standalone Easegress?

EaseMesh is a specific application of Easegress designed for service mesh architectures. While standalone Easegress functions as a standalone API gateway or traffic processor, EaseMesh utilizes Easegress's object model to run distributed sidecars (Workers) alongside application containers, coordinated by a centralized Master. The integration leverages the same pipeline engine but adds service-specific abstractions like automatic registration, heartbeat health checks, and mTLS certificate management through the pkg/object/meshcontroller package.

What Kubernetes labels are required for EaseMesh sidecar injection?

The sidecar requires specific labels defined in pkg/object/meshcontroller/label/label.go. The mandatory labels include mesh-role (set to worker for sidecars), mesh-service-name (identifying the service), and mesh-application-port (the port your application container exposes). Optional but recommended labels include mesh-alive-probe (HTTP endpoint for health checks) and mesh-service-labels (key=value pairs for service versioning or team attribution). These labels enable the Worker to construct a ServiceInstanceSpec and register with the Master control plane.

How does EaseMesh handle service discovery and health checking?

Service discovery operates through the Master component in pkg/object/meshcontroller/master/master.go, which maintains a registry of active instances in the cluster's KV store using keys generated by layout.ServiceInstanceSpecKey() and layout.ServiceInstanceStatusKey(). Health checking follows a heartbeat pattern: each Worker sidecar periodically calls the URL specified in mesh-alive-probe and reports status via updateHeartbeat(). The Master runs checkLastHeartbeatTime() to compare timestamps against timeouts, marking instances as OUT-OF-SERVICE when heartbeats fail and cleaning stale entries from the registry.

Can EaseMesh encrypt traffic between services?

Yes, EaseMesh supports mutual TLS (mTLS) for zero-trust encryption between services. When spec.Admin.Security is enabled in the MeshController configuration, the Master initializes a certificate manager via certmanager.NewCertManager() to create a self-signed Certificate Authority. The Master issues unique certificates for each service instance, storing them in the cluster state. Workers retrieve these certificates through the control plane API and configure them in the AgentConfig for the local Ingress and Egress servers. This ensures all intra-mesh traffic is encrypted without requiring application code changes or manual certificate management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}