How to Configure Blue-Green Deployment Switching with Easegress

Easegress implements blue-green deployment by using ServiceCanaries that inject the X-Mesh-Service-Canary header to route traffic between tagged service instances, allowing instant traffic switching by updating a single configuration object.

Blue-green deployment switching in Easegress enables zero-downtime releases by routing traffic between two identical production environments labeled "blue" and "green." This guide explains how to configure blue-green deployment switching using Easegress ServiceCanary objects and the mesh controller, based on the implementation in the megaease/easegress open-source repository.

Understanding the Blue-Green Mechanism

Easegress treats blue-green deployment as a specialized form of service canarying. The system uses ServiceCanary objects to match service instances based on labels and automatically inject the X-Mesh-Service-Canary HTTP header into requests. When this header is present, the mesh adaptor rewrites it to the canary name, causing the traffic to be routed exclusively to the matching instances.

Switching from the blue version to the green version is therefore just a matter of changing which canary is selected—either by updating the canary's selector to match different labels or by replacing the active canary object entirely. This approach requires no pipeline restarts and takes effect immediately.

Step-by-Step Configuration

1. Tag Service Instances with Release Labels

First, label your service instances to distinguish between blue and green deployments. In example/config/pipeline-example.yaml (lines 100-106), the tags field demonstrates how instances are categorized for canary selection.

Create ServiceInstance objects with distinct labels:

# Blue version of the service

apiVersion: easegress/v2alpha1
kind: ServiceInstance
metadata:
  name: order-blue-001
spec:
  address: 127.0.0.1
  port: 5002
  labels:
    release: "blue"
---

# Green version of the service

apiVersion: easegress/v2alpha1
kind: ServiceInstance
metadata:
  name: order-green-001
spec:
  address: 127.0.0.1
  port: 5003
  labels:
    release: "green"

2. Define ServiceCanary Objects

Create ServiceCanary resources that select instances based on these labels. The ServiceCanary struct is declared in pkg/object/meshcontroller/spec/spec.go (lines 40-48).

Define the blue canary:

apiVersion: easegress/v2alpha1
kind: ServiceCanary
metadata:
  name: order-blue
spec:
  selector:
    matchServices: ["order"]
    matchInstanceLabels:
      release: "blue"
  trafficRules:
    headers: {}

Define the green canary:

apiVersion: easegress/v2alpha1
kind: ServiceCanary
metadata:
  name: order-green
spec:
  selector:
    matchServices: ["order"]
    matchInstanceLabels:
      release: "green"
  trafficRules:
    headers: {}

The empty headers map in trafficRules instructs the mesh adaptor to add the X-Mesh-Service-Canary header when it is absent in the incoming request.

3. Configure the Pipeline

When the pipeline is built, the controller automatically appends two critical components. In pkg/object/meshcontroller/spec/builder.go, the appendMeshAdaptor function (lines 30-36) inserts the canary header when missing, and appendProxyWithCanary (lines 55-65) adds a proxy pool that matches requests based on that header.

Create the base pipeline configuration:

apiVersion: easegress/v2alpha1
kind: Pipeline
metadata:
  name: order-pipeline
spec:
  flow:
    - filter: order-proxy
  filters:
    - name: order-proxy
      kind: Proxy
      pools:
        - servers: []   # Main pool used when no canary header is present

Deploy the configuration using egctl:

egctl create -f service-instances.yaml
egctl create -f blue-canary.yaml
egctl create -f pipeline.yaml

Executing the Traffic Switch

Switch traffic from blue to green by either updating the existing canary's selector or replacing the canary object entirely.

Method 1: Update the selector in place

Modify the active ServiceCanary to match the green label:

spec:
  selector:
    matchInstanceLabels:
      release: "green"

Apply the change:

egctl apply -f updated-canary.yaml

Method 2: Replace the canary object

Delete the blue canary and create the green canary:

egctl delete servicecanary order-blue
egctl create -f order-green-canary.yaml

Because the mesh adaptor in builder.go automatically adds the X-Mesh-Service-Canary header when missing, the change takes effect instantly—all new requests are routed to the green instances, achieving a single-step traffic switch without service interruption.

How It Works Under the Hood

The blue-green routing logic relies on three key components in the megaease/easegress source code:

• pkg/object/meshcontroller/spec/spec.go (lines 40-48): Defines the ServiceCanary struct, including the selector and trafficRules fields that determine which instances receive traffic.

• pkg/object/meshcontroller/spec/builder.go (lines 30-36): The appendMeshAdaptor function adds a filter that inspects incoming requests and injects the X-Mesh-Service-Canary header when it is not already present.

• pkg/object/meshcontroller/spec/builder.go (lines 55-65): The appendProxyWithCanary function constructs a proxy pool that specifically matches requests where the X-Mesh-Service-Canary header equals the canary name, ensuring traffic is isolated to the correct version.

Together, these components create a routing chain: instance labeling → canary selector → mesh adaptor injection → proxy pool routing. By updating a single ServiceCanary object, you instantly switch the entire traffic flow from the blue version to the green version.

Summary

• Label instances with distinct release tags (e.g., release: blue and release: green) to create your deployment environments.
• Create ServiceCanaries with empty trafficRules.headers to enable automatic header injection by the mesh adaptor.
• Deploy pipelines that automatically incorporate canary-aware proxy pools through the builder functions in spec/builder.go.
• Switch traffic instantly by updating the ServiceCanary selector or replacing the canary object, without restarting services.
• Leverage the mesh adaptor to handle header injection automatically, ensuring seamless routing between blue and green environments.

Frequently Asked Questions

What is the difference between blue-green and canary deployment in Easegress?

Blue-green deployment routes 100% of traffic to one environment or the other, while traditional canary deployment gradually shifts percentages. In Easegress, both use the same ServiceCanary object, but blue-green switching typically involves changing the selector to match an entirely different label set (blue vs. green) rather than adjusting traffic weights.

How does the mesh adaptor inject the X-Mesh-Service-Canary header?

According to pkg/object/meshcontroller/spec/builder.go (lines 30-36), the appendMeshAdaptor function adds a filter that checks for the presence of the X-Mesh-Service-Canary header. When the header is missing and the trafficRules.headers map is empty in the ServiceCanary spec, the adaptor automatically inserts the header with the canary name as the value.

Can I automate the traffic switch in a CI/CD pipeline?

Yes. Because the traffic switch is accomplished by updating a ServiceCanary object via the Easegress HTTP API or egctl CLI, you can automate blue-green switching in your CI/CD pipeline. Simply update the matchInstanceLabels selector or perform a delete/create operation on the ServiceCanary resource as part of your deployment job.

What happens to existing requests during a blue-green switch?

Existing requests with the X-Mesh-Service-Canary header already set will continue to route to their original destination (blue or green) for the duration of that request. New incoming requests will receive the updated header value and route to the new active environment. This ensures in-flight requests complete successfully while new traffic immediately follows the updated routing rules.

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