Skip to main content
Mapagam

Configuring Header-Based Routing

1. Implementing Exact Header Matching

Header Name Matching Rule Example
Authorization Exact match on header value Authorization: Bearer abc123
Content-Type Exact match on media type Content-Type: application/json
User-Agent Exact match on user agent string User-Agent: curl/7.64.1

Example: Exact Header Match Configuration

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: example-route
spec:
  hosts:
  - example.com
  http:
  - match:
    - headers:
        Authorization:
          exact: Bearer abc123
    route:
    - destination:
        host: backend-service

2. Configuring Regex Header Matching

Property Values Description
header.name Authorization Name of the HTTP header to match
header.value.regex ^Bearer [A-Za-z0-9\-_]+\.([A-Za-z0-9\-_]+)\.([A-Za-z0-9\-_]+)$ Regular expression pattern to match the header value
header.value.caseSensitive false Whether the regex matching is case-sensitive

Example: Regex Header Matching Configuration

routes:
  - match:
      headers:
        - name: Authorization
          value:
            regex: ^Bearer [A-Za-z0-9\-_]+\.([A-Za-z0-9\-_]+)\.([A-Za-z0-9\-_]+)$
            caseSensitive: false
    route:
      destination:
        host: api.example.com

3. Implementing Prefix Header Matching

Property Description Example
match.type Specifies the type of header matching to use. For prefix matching, set to prefix. prefix
match.header.name Name of the HTTP header to match. X-User-ID
match.header.value Prefix value to match in the header. admin-

Example: Prefix Header Matching Rule

routes:
  - match:
      headers:
        - name: X-User-ID
          match:
            type: prefix
            value: admin-
    route:
      destination:
        host: admin-service
Note: Prefix matching is case-sensitive and matches from the beginning of the header value.

4. Setting Up Custom Header Routes

Field Description Example
match Defines the header match criteria { "headers": { "version": "v2" } }
route Specifies the destination service and port { "destination": { "service": "api-v2", "port": 8080 } }
weight Optional weight for traffic distribution (0-100) 50

Example: Route Based on Accept-Language Header

routes:
  - match:
      headers:
        accept-language:
          exact: en-US
    route:
      destination:
        service: api-en
        port: 8080

Example: Route Based on Custom Authorization Header

routes:
  - match:
      headers:
        authorization:
          prefix: "Bearer "
    route:
      destination:
        service: auth-service
        port: 9000
Note: Header matching is case-insensitive by default in most service mesh implementations.

5. Implementing Method-Based Routing

Property Description Example
httpRoute.match.method HTTP method to match for routing GET, POST
httpRoute.route Destination service and port service: "api-service", port: 8080

Example: Route POST requests to API service

httpRoute:
  match:
    method: POST
  route:
    - destination:
        host: api-service
        port:
          number: 8080
Note: Method-based routing is useful for directing different HTTP methods to appropriate backend services.

6. Configuring Query Parameter Routing

Property Values Description
queryParameter.name string Name of the query parameter to match
queryParameter.value string Exact value to match (optional)
queryParameter.regex string Regex pattern to match query parameter value (optional)

Example: Route based on query parameter value

routes:
  - name: "user-query-route"
    match:
      queryParameters:
        - name: "userId"
          value: "12345"
    route:
      destination:
        host: "user-service"

Example: Route based on regex pattern in query parameter

routes:
  - name: "product-query-route"
    match:
      queryParameters:
        - name: "category"
          regex: "electronics|clothing"
    route:
      destination:
        host: "product-service"
Note: Query parameter matching is case-sensitive by default.
Property Description Example
cookie.name Name of the cookie to match session_id
cookie.value Value of the cookie to match abc123
cookie.path Path restriction for the cookie /api/v1 
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: example-route
spec:
  hosts:
  - example.com
  http:
  - match:
    - headers:
        cookie:
          name: session_id
          value: abc123
    route:
    - destination:
        host: backend-service
        port:
          number: 80
Note: Cookie-based routing can be used in conjunction with other header-based matching criteria to create more complex routing rules.

8. Setting Up User-Agent Routing

Property Value Description
route.match.userAgent string Matches the User-Agent header value using a regex pattern.
route.match.userAgent.regex string Regex pattern to match against the User-Agent header.
route.match.userAgent.exact string Exact string match for the User-Agent header.

Example: User-Agent Based Route Configuration

routes:
  - name: mobile-app-route
    match:
      userAgent:
        regex: "Mobile.*Android"
    route:
      destination:
        host: mobile-service
Note: User-Agent matching is case-sensitive by default. Ensure patterns are crafted to match the actual format of the User-Agent header sent by clients.

9. Configuring Request Header Manipulation

Operation Description Example
add Adds a new header to the request 
{
  "add": {
    "X-Request-ID": "12345"
  }
}
remove Removes a header from the request 
{
  "remove": ["User-Agent"]
}
set Sets or replaces a header value 
{
  "set": {
    "X-Forwarded-Proto": "https"
  }
}

Example: Adding a Custom Header

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: example-vs
spec:
  hosts:
  - example.com
  http:
  - route:
    - destination:
        host: example-service
    headers:
      request:
        add:
          X-Custom-Header: "custom-value"
Note: Header manipulation is applied before routing decisions are made.

10. Configuring Response Header Manipulation

Operation Description Example
add Adds a new response header to the outbound response. 
responseHeadersToAdd:
  - header:
      key: X-Custom-Header
      value: "custom-value"
remove Removes a response header from the outbound response. 
responseHeadersToRemove:
  - X-Internal-Header
replace Replaces an existing response header or adds a new one if it does not exist. 
responseHeadersToReplace:
  - header:
      key: Content-Type
      value: application/json

Example: Adding a Custom Response Header

routes:
  - match:
      path: /api/users
    route:
      responseHeadersToAdd:
        - header:
            key: X-Response-Time
            value: "{{duration}}ms"

Example: Removing a Response Header

routes:
  - match:
      path: /api/data
    route:
      responseHeadersToRemove:
        - Server
Note: Header manipulation is applied after the route match and before the final response is sent to the client.

11. Implementing Weighted Header Routes

Route Configuration Values Description
match.headers user-agent Header name to match on
match.headers.value mobile-app/1.0 Exact header value to match
weight 70 Percentage of traffic to route (out of 100)

Example: Weighted Header Route Configuration

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: weighted-header-route
spec:
  hosts:
    - api.example.com
  http:
    - match:
        - headers:
            user-agent:
              exact: mobile-app/1.0
      route:
        - destination:
            host: api-mobile.example.com
          weight: 70
        - destination:
            host: api-desktop.example.com
          weight: 30
Note: The weights must sum to 100 for all routes in a single HTTP route block.

12. Managing Header Propagation

Header Name Propagation Behavior Notes
Authorization propagate Used for authentication; typically propagated to downstream services
Content-Type propagate Indicates the media type of the resource; often propagated in REST APIs
X-Forwarded-For append Tracks the original client IP address; commonly appended in proxy chains
X-Request-ID generate Unique identifier for tracking requests; typically generated per request
User-Agent propagate Identifies the client software; often propagated for logging or analytics
Host remove Removed to prevent spoofing; handled by the service mesh layer

Example: Configuring Header Propagation in Istio

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: example-service
spec:
  hosts:
  - example-service
  http:
  - route:
    - destination:
        host: example-service
    headers:
      request:
        add:
          X-Request-ID: "{{request.headers[X-Request-ID]}}"
        remove:
        - Host
Note: Header propagation rules can be defined at the VirtualService or DestinationRule level in Istio.

Was this article helpful?

Related Cheat Sheets