# How to Configure Canary Releases Using Easegress: Complete Implementation Guide > Easily configure canary releases with Easegress. Learn how to route tagged traffic to specific service versions using pipeline filter rules. Master advanced deployments today. - Repository: [MegaEase/easegress](https://github.com/megaease/easegress) - Tags: how-to-guide - Published: 2026-03-07 --- **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](https://github.com/megaease/easegress/blob/main/docs/03.Advanced-Cookbook/3.04.Canary-Release.md), 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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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. ```yaml 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: ```yaml 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`: ```bash 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. ```yaml 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`: ```bash 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. ```yaml 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: ```bash 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: ```bash curl http://127.0.0.1:8888/order -H "cf-ipcity: Beijing" ``` Test device-based routing: ```bash 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): ```bash 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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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 ` command. This applies changes to header-matching rules, server URLs, or WASM configurations without requiring a full redeployment of the Easegress control plane.