Canary Deployments with Traefik Mesh Weighted Routing

Deploying a new version without flipping every switch at once

You just built orders-api-v2. The stable orders-api-v1 is still handling production traffic, and you want to send a small percentage of live requests to the new build before committing to a full rollout. Doing this manually often means maintaining separate ingress rules, load balancer weights, or custom discovery logic just for a temporary experiment.

Traefik Mesh can split traffic between versions of the same service automatically. It runs on top of Traefik Proxy and HashiCorp Consul Connect. Sidecar proxies sit next to your service instances and manage east-west service-to-service traffic. Consul Connect keeps a catalog of healthy services and enforces intentions—named authorization rules that also require mTLS, or mutual TLS, between services.

How weighted splitting fits the mesh

Traefik Mesh discovers services through the Consul catalog. Before any traffic can be split, both the stable and canary instances must register with Consul and pass health checks. The mesh then distributes requests across the registered endpoints according to the weight you assign to each backend. Consul Connect intentions apply to the split as well, so canary traffic stays encrypted and access-controlled just like stable traffic.

Configuration keys and resource names vary between Traefik Mesh releases. Treat the examples below as structural placeholders, and confirm the exact syntax against the documentation for your installed version.

Worked example: 10 percent canary traffic

Assume you run two versions of orders-api in the same Consul namespace:

• orders-api-v1: stable, currently receiving 100 percent of traffic.
• orders-api-v2: canary, running alongside v1 with the same schema and shared database.

On an admin machine with access to your Consul cluster and Traefik Mesh control plane, you would:

1. Confirm both versions are registered and healthy in the Consul catalog. Required permission: read access to the Consul catalog.
2. Apply a traffic weight of 90 percent to v1 and 10 percent to v2 using your mesh’s traffic-split resource or API. Required permission: write access to the mesh routing configuration for the target namespace.
3. Observe request distribution in Traefik Mesh metrics or access logs.

Placeholder configuration structure—do not copy this verbatim without checking your release:

service: orders-api
namespace: 
backends:
  - name: orders-api-v1
    weight: 90
  - name: orders-api-v2
    weight: 10

Expected check: after applying, both Consul service instances should show a passing health status, and Traefik Mesh access logs should show roughly one in ten requests reaching the canary upstream. Risk: if the canary instances are unhealthy but still registered, misconfigured health checks can send live traffic to failing instances.

Trade-offs and limitations

Weighted splitting is not a substitute for database migration planning. If v2 writes to the same database as v1 and uses a different schema, both versions must be able to coexist during the split. Consul Connect intentions control network access, but they do not prevent application-level data conflicts.

Running Consul alongside sidecars adds operational overhead: Consul cluster health, sidecar memory and CPU, and intention lifecycle management all require attention. Weighted routing typically operates at the service-resolver level; fine-grained header-based canary rules may require additional Traefik middleware.

Verify the split and roll back if needed

Check the Consul catalog for healthy instances of both versions, then compare request counts per upstream in Traefik Mesh access logs over a five-minute window. If error rates or latency rise on the canary, roll back by setting the canary weight to zero and the stable weight to 100. This is a state-changing operation, so apply it with the same write permissions used for the original split.

Start small, monitor, and increase the canary weight only after the new version behaves consistently under real traffic.