AWS App Mesh Virtual Service Builder

What This Tool Does

Build an AWS App Mesh virtual service backed by a virtual router with header-matched, weighted-target HTTP routes, plus a retry policy specifying which HTTP events (server-error, gateway-error) trigger a retry. A virtual service's Provider must be either a VirtualRouter (for a service that needs multiple routes/weighted targets, like the v2/v3 canary split in the example) or a VirtualNode directly (for a simpler pass-through case), and these two provider modes aren't just different ways of writing the same config, a virtual node provider skips routing logic entirely and can't do weighted target splitting at all.

Technical Details

Common Use Cases

1. 1Providing a VirtualRouter (rather than a bare VirtualNode) specifically because the service needs weighted-target routing across backend-v2 and backend-v3, a direct-to-VirtualNode provider has no routing layer to do that split.
2. 2Matching on a specific request header (x-api-version: v2) in the route's HttpRoute.Match, so a route only applies to requests explicitly requesting that API version, letting other versions fall through to a different route or the mesh's default behavior.
3. 3Setting RetryPolicy.HttpRetryEvents to server-error and gateway-error specifically (5xx-class failures) rather than retrying on any non-2xx response, since retrying a legitimate 4xx client error just wastes a retry attempt on a request that will fail identically every time.
4. 4Tuning Priority on competing routes within the same virtual router, since App Mesh evaluates routes in priority order and the first matching route wins, a canary route with a specific header match needs a priority that puts it ahead of a catch-all route, or it never gets evaluated.

Common Questions

Can a virtual service skip the virtual router and go directly to a virtual node?

Yes, using Provider.VirtualNode instead of Provider.VirtualRouter, but that mode has no routing logic at all, no weighted targets, no header matching, no retry policy scoped per-route, it's a direct pass-through to one specific virtual node. If you need any of that routing flexibility (as the weighted canary split in the example needs), you must use the VirtualRouter provider, not VirtualNode.

Does RetryPolicy retry on every failed request?

Only for the HTTP events explicitly listed in HttpRetryEvents, retrying on server-error and gateway-error (5xx-class responses) but not on a 4xx client error, since a 4xx typically indicates the request itself was malformed and would fail identically on retry. Retrying indiscriminately on all failures wastes retry budget on inherently unretryable failures and can amplify load during a real outage.

What happens if two routes on the same virtual router could both match a request?

App Mesh evaluates routes by Priority (lower number generally evaluated first, matching the field's documented behavior) and applies the first one that matches, similarly to ALB listener rule priority. If two routes both plausibly match a request but only one is intended to, incorrect priority ordering means the wrong route (and its weighted targets or retry policy) applies.

Expert Tips

Related Learning Guides

• VPC Architecture Patterns28 min read
• AWS Networking Deep Dive30 min read