# How Easegress Integrates with EaseMesh for Service Mesh Functionality

> Discover how EaseMesh leverages Easegress's core components to deliver seamless service mesh functionality, including service discovery, traffic routing, and observability. Learn more today.

- Repository: [MegaEase/easegress](https://github.com/megaease/easegress)
- Tags: integration
- Published: 2026-03-07

---

**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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/example/config/mesh-controller-example.yaml):

```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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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.