Skip to main content

Workflow: Header-Based Canary

Route specific users (internal testers, partners, opt-in beta users) to the canary version via HTTP headers or cookies, rather than wait for a percentage-based split.

When to Use​

  • Internal testing — Route team members with X-Canary: true header to the new version.
  • Partner access — Give specific partners a cookie to see the preview.
  • Opt-in beta — Let users opt in via a cookie or URL parameter.
Important Notes

Argo Rollouts' setHeaderRoute step is Istio-only out of the box. With Traefik, header/cookie routing is expressed directly on the IngressRoute match rule using the traefik_manage_weighted_routing tool, which generates the correct Traefik matcher syntax automatically.

Also, when both a cookie and a header parameter are set, the cookie parameter takes priority in the tool's generation matrix.

Journey Diagram​

Workflow Scenarios (Tools & Resources)​

Scenario A: Header & Cookie-Based Canary Routing​

Tests traefik_manage_weighted_routing (create) with optional header/cookie matchers, plus generator YAML for the baseline TraefikService/IngressRoute if desired.

StepActionTool / Resource
1Baseline routeTool: traefik_manage_weighted_routing (action=create, route_name=frontend-route, namespace=staging, stable_service=frontend-stable, stable_weight=100, canary_weight=0)
Or use traefik_generate_routing_manifest for GitOps YAML.
2Header CanaryTool: traefik_manage_weighted_routing (action=create, route_name=frontend-canary-header, namespace=staging, stable_weight=0, canary_weight=100, header_name=X-Canary, header_value=true)
Creates a second IngressRoute whose match includes Traefik Header matcher for X-Canary.
3Monitor Route / MetricsResource: traefik://traffic/staging/frontend-canary-header/distribution or traefik://metrics/staging/frontend-canary/summary
Use the route_name you assigned in step 2.
4Cookie CanaryTool: traefik_manage_weighted_routing (action=create, cookie_name=canary, cookie_regex=.yes.)
Beta-flag style routing via Cookie header regex.

Note: The header-qualified route has a more specific match rule (Host + Header), so Traefik's internal priority system automatically favors it over the default route (Host only) when overlapping.

Natural Language Prompts​

Use these exact prompts with the MCP Server to test or automate the workflow operations effortlessly.

Execution Prompts​

"Generate an IngressRoute pointing to the 'frontend-weighted' TraefikService at 'app.example.com' in 'staging'."

"Create a header-based canary route for 'frontend-canary' in 'staging' at hostname 'app.example.com' — route requests with header 'X-Canary: true' to the canary."

"Show me the traffic distribution for 'frontend-canary-header' in 'staging'."

"Show performance metrics for 'frontend-canary' in 'staging'."

"Set up cookie-based canary routing for 'frontend-canary' in 'staging' at 'app.example.com' — route users with cookie 'canary=yes' to the new version."

Next Steps​