Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Traffic Management

Header and Path-Based Routing

Route requests in Istio by URI, header, method and query parameter, rewrite paths, redirect, and set or remove headers, with matcher stand-ins you can run.

A VirtualService can look at each HTTP request and pick a destination from what it says: the path, the method, a header, a query parameter. This is L7 routing, and it is what lets you give testers the new version, serve an API and a web app on one host, or send mobile clients to a dedicated backend.

Match conditions

A match is a list of conditions that are ANDed within one entry, and the entries in the list are ORed. Each string field accepts exact, prefix or regex.

YAML
http:
  - match:
      - headers:
          x-canary:
            exact: "true"
      - headers:
          cookie:
            regex: ".*group=beta.*"
    route:
      - destination: { host: catalog, subset: v2 }
  - match:
      - uri:
          prefix: /api/orders
        method:
          exact: POST
    route:
      - destination: { host: orders }
  - route:
      - destination: { host: catalog, subset: v1 }

Reading it: a request with x-canary: true or a beta cookie goes to v2. A POST to a path starting /api/orders goes to orders. Everything else, via the last rule without match, goes to v1. The order matters because the first matching rule wins.

Available fields include uri, scheme, method, authority (the host header), headers, queryParams, port, sourceLabels (the labels of the calling workload) and sourceNamespace. Matching on sourceLabels allows "the web app sees v2, other callers see v1".

What can a match look at?

Path exact, prefix or regex.
Headers Any request header.
Query Parameters like ?beta=1.
Source Calling pod labels.
1 / 2

Rewrites and redirects

A rewrite changes the request on the way to the backend; the client does not see it:

YAML
- match:
    - uri:
        prefix: /shop/catalog
  rewrite:
    uri: /
  route:
    - destination: { host: catalog }

Here the public URL /shop/catalog/books reaches the service as /books. A redirect answers the client with a 3xx instead, and the client makes a new request:

YAML
- match:
    - uri:
        exact: /old-docs
  redirect:
    uri: /docs
    redirectCode: 301

A route can have either a route or a redirect, not both.

Changing headers

Headers can be set, added or removed on the request going upstream or the response going back:

YAML
route:
  - destination: { host: catalog, subset: v2 }
    headers:
      request:
        set:
          x-routed-by: mesh
        remove:
          - x-debug
      response:
        add:
          x-served-by: catalog-v2

Use this to tag traffic, strip internal headers at the edge, or add a cache hint. Never rely on a header for security unless something trusted sets it: clients can send any header they like, so authorization based on x-user-role is unsafe unless the gateway strips and re-sets it (see Authorization Policies).

Delegation and other fields

Large teams split routing with delegate VirtualServices: a root one at the gateway owns the host, and delegates path prefixes to VirtualServices in team namespaces. Other route-level fields you will meet: corsPolicy (answer CORS preflights), directResponse (return a fixed body without a backend), mirror, fault, retries and timeout.

Stand-ins

The first stand-in implements the AND/OR rule of match. The second builds a rewrite. Both use simplified semantics (prefix and exact only), written for learning.

Python Stand-in: AND within, OR between matches

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: prefix rewrite

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A prefix match on /api also matches /apikeys. If you mean a path segment, match exact: /api and prefix: /api/ separately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How are several entries in a match list combined?

    Entries are alternatives; conditions inside one entry must all hold.
  2. 2. What is the difference between a rewrite and a redirect?

    Rewrites happen inside the mesh; redirects return a 3xx response.
  3. 3. Why shouldn't you trust a client-supplied header for authorization?

    Unless the edge strips and sets the header, a caller can forge it.
  4. 4. Which match field lets you route by the calling workload's labels?

    sourceLabels matches the labels of the source workload, for per-caller routing.

Summary

  • match supports path, method, headers, query parameters, port and source labels, with exact, prefix and regex.
  • Entries in a match list are ORed; conditions in one entry are ANDed; first matching rule wins.
  • Rewrites change the upstream request; redirects send a 3xx to the client.
  • Set, add or remove headers per route; never trust unauthenticated client headers.
  • Delegate VirtualServices split ownership of routes among teams.

Next: Traffic Mirroring and Fault Injection