How to Configure Canary Releases Using Easegress: Complete Implementation Guide

Easegress enables canary releases by tagging inbound traffic with headers and routing tagged requests to specific service versions through pipeline filter rules.

Easegress is an open-source cloud-native traffic orchestration system that supports sophisticated canary release strategies through header-based traffic tagging and pipeline routing. This guide explains how to configure canary releases using Easegress based on the official documentation and source code in the megaease/easegress repository, with practical examples from the megaease/easegress-canary-example reference implementation.

Understanding the Canary Architecture in Easegress

The canary release implementation in Easegress relies on three core components working together: traffic tagging, traffic scheduling through filter rules, and the ServiceCanary CRD.

Traffic Tagging and Header Matching

According to the Canary-Release documentation, the fundamental principle is to tag inbound traffic with labels such as geographic location (cf-ipcity), device type (x-ua-device), or operating system (x-ua-os). These tags can originate from Cloudflare headers, Cloudflare Workers, or custom Easegress WASM filters.

The ServiceCanary CRD and Mesh Controller

Canary metadata is stored in the ServiceCanary custom resource definition. In pkg/object/meshcontroller/spec/spec.go at line 240, the ServiceCanary struct defines the specification including service name, priority, and routing rules. The mesh-controller API exposes REST endpoints at /servicecanaries for CRUD operations, implemented in pkg/object/meshcontroller/api/api_servicecanary.go. These endpoints allow the egctl CLI and UI to manage canary configurations programmatically.

Pipelines and Traffic Scheduling

Traffic scheduling is expressed as filter rules within Pipeline specifications. A Pipeline chains filters (such as WasmHost or Proxy) to process requests, while an HTTPServer binds to a port and forwards traffic to the appropriate pipeline based on path rules. The Proxy filter uses pools with filter conditions to match headers and route to specific server groups representing different service versions.

Configuring Geographic-Based Canary Releases

To route traffic from specific cities to a new service version, configure a Pipeline that matches the cf-ipcity header injected by Cloudflare.

name: order-pipeline
kind: Pipeline
flow:
- filter: order-service
filters:
- name: order-service
  kind: Proxy
  pools:
  - servers:
    - url: http://0.0.0.0:5002   # new version

    filter:
      headers:
        cf-ipcity:
          exact: Beijing        # Beijing traffic → v2

  - servers:
    - url: http://0.0.0.0:5001   # old version (default)

Expose this pipeline through an HTTPServer on port 8888:

kind: HTTPServer
name: ecommerce-server
port: 8888
https: false
keepAlive: true
keepAliveTimeout: 75s
maxConnection: 10240
rules:
- paths:
  - pathPrefix: /order
    backend: order-pipeline
  - pathPrefix: /notify
    backend: notify-pipeline

Deploy the configuration using egctl:

egctl create -f order-service.yaml
egctl create -f ecommerce-server.yaml

Configuring Device-Based Canary Releases

For routing based on user device types (parsed by Cloudflare Workers or similar), match the x-ua-device header. This example sends Mac device users to version 2 while others remain on version 1.

name: notify-pipeline
kind: Pipeline
flow:
- filter: notify-service
filters:
- name: notify-service
  kind: Proxy
  pools:
  - servers:
    - url: http://0.0.0.0:5002   # new version

    filter:
      headers:
        x-ua-device:
          exact: Mac           # Mac device → v2

  - servers:
    - url: http://0.0.0.0:5001   # old version

Update existing configurations using egctl apply:

egctl apply -f notify-service.yaml

Configuring OS-Based Canary Releases with WASM

When you need to parse User-Agent strings directly within Easegress, use a WASM filter to add custom headers before the Proxy filter evaluates routing rules.

name: order-pipeline
kind: Pipeline
flow:
- filter: wasm
- filter: order-service
filters:
- name: wasm
  kind: WasmHost
  maxConcurrency: 2
  code: /path/to/easegress.wasm   # compiled uaparser WASM

  timeout: 100ms
- name: order-service
  kind: Proxy
  pools:
  - servers:
    - url: http://0.0.0.0:5002   # new version

    filter:
      headers:
        x-ua-os:
          exact: MacOS          # MacOS → v2

  - servers:
    - url: http://0.0.0.0:5001   # old version

Deploy or update with:

egctl apply -f order-pipeline.yaml

Testing and Validating Canary Configurations

Verify your canary rules using curl with custom headers to simulate different client types.

Test geographic routing:

curl http://127.0.0.1:8888/order -H "cf-ipcity: Beijing"

Test device-based routing:

curl http://127.0.0.1:10080/ecommerce -H "user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

Test OS-based routing (after WASM processing):

curl http://127.0.0.1:10080/ecommerce -H "user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

Summary

• Easegress canary releases rely on tagging traffic with headers and routing via pipeline filter rules.
• The ServiceCanary CRD in pkg/object/meshcontroller/spec/spec.go stores canary metadata, managed through the mesh-controller API at /servicecanaries.
• Three tagging methods are supported: Cloudflare headers (geography), Cloudflare Workers (device type), and WASM filters (custom parsing).
• Configure canary routing by defining Proxy filters with header-matching pools in Pipeline specifications.
• Use egctl create for initial deployment and egctl apply for updates to canary configurations.

Frequently Asked Questions

What is the ServiceCanary CRD in Easegress?

The ServiceCanary CRD is a custom resource definition defined in pkg/object/meshcontroller/spec/spec.go at line 240 that stores canary release metadata including service names, priorities, and routing rules. It is converted to protobuf for the mesh-controller API, enabling programmatic management of canary specifications through REST endpoints.

How does Easegress route traffic to different service versions?

Easegress routes traffic using filter rules within Pipeline specifications. The Proxy filter evaluates incoming request headers against configured matching rules (such as exact matches for cf-ipcity or x-ua-device) and forwards requests to specific server pools representing different service versions.

Can I use WASM for custom traffic tagging in Easegress?

Yes, Easegress supports WASM-based traffic tagging through the WasmHost filter. You can compile custom logic (such as User-Agent parsing) into a WASM module, configure it in your pipeline flow before the Proxy filter, and have it inject headers like x-ua-os that subsequent routing rules evaluate for canary traffic splitting.

How do I update an existing canary configuration?

Update existing canary pipelines and servers using the egctl apply -f <filename.yaml> command. This applies changes to header-matching rules, server URLs, or WASM configurations without requiring a full redeployment of the Easegress control plane.

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