Configuring URI-Based Routing
1. Implementing Exact Path Matching
| Property | Description | Example |
|---|---|---|
| match.path | Specifies the exact path to match | /api/users |
| match.method | HTTP method to match (optional) | GET |
| match.headers | Headers to match (optional) | { "Accept": "application/json" } |
Example: Exact Path Match Configuration
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: example-service
spec:
hosts:
- example.com
http:
- match:
- path: /api/users
route:
- destination:
host: user-service
port:
number: 8080
2. Configuring Prefix Path Matching
| Property | Value | Description |
|---|---|---|
| route.prefix | /api/v1 |
Matches all paths that start with the specified prefix |
| route.path | /api/v1/users |
Exact path match (not prefix) |
| route.regex | /api/v1/.* |
Regular expression for path matching |
Example: Prefix Path Matching Configuration
routes:
- match:
prefix: /api/v1
route:
destination:
host: user-service
port:
number: 8080
Note: Prefix matching is case-sensitive and supports wildcards in the form of
/api/v1/* for trailing paths.
3. Implementing Regex Path Matching
| Property | Description | Example | Notes |
|---|---|---|---|
| route.match.path.regex | Regular expression pattern for matching URI paths | /api/v[0-9]+/users/.* |
Supports standard regex syntax; must be valid for the service mesh implementation |
| route.match.path.type | Matching type (e.g., prefix, exact, regex) | REGEX |
Must be set to REGEX for regex path matching |
Example: Regex Path Matching Configuration
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: example-service
spec:
hosts:
- example.com
http:
- match:
- uri:
regex: "/api/v[0-9]+/users/.*"
route:
- destination:
host: user-service
port:
number: 8080
Note: Regex patterns in service meshes are typically evaluated using the RE2 engine, which supports a subset of PCRE syntax. Ensure patterns do not include unsupported constructs like lookaheads or lookbehinds.
4. Setting Route Priorities
| Property | Description | Values | Notes |
|---|---|---|---|
| route.priority | Defines the priority of a route | integer |
Higher values are processed first. Default is 0. |
| route.match | Defines matching criteria for the route | string |
Used to match incoming requests based on URI path or headers. |
Example: Route Priority Configuration
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: example-service
spec:
hosts:
- example.com
http:
- route:
- destination:
host: service-a.example.svc.cluster.local
weight: 80
- destination:
host: service-b.example.svc.cluster.local
weight: 20
priority: 10
Note: Route priorities are used to control the order in which routes are evaluated. Routes with higher priority values are evaluated before those with lower values.
5. Configuring Default Routes
| Property | Description | Example |
|---|---|---|
| route.default | Defines the default route for traffic when no specific route matches | route.default = "/api/v1" |
| route.default.host | Host to use for default route matching | route.default.host = "api.example.com" |
| route.default.path | Path prefix for default route matching | route.default.path = "/v1" |
Note: Default routes are applied when no other route matches the incoming request. Ensure that default routes do not conflict with more specific routes.
6. Implementing Route Rewrites
| Property | Description | Example |
|---|---|---|
| route.rewrite.path | Specifies the new path to rewrite the request to | /api/v2/users |
| route.rewrite.prefix | Prefix to prepend to the path during rewrite | /api/v2 |
| route.rewrite.regex | Regular expression to match and replace parts of the path | /api/v([0-9]+)/users/(\d+) |
Example: Regex-Based Rewrite
routes:
- match:
path: /api/v1/users/123
rewrite:
regex:
pattern: /api/v([0-9]+)/users/(\d+)
replacement: /api/v2/users/$2
Note: Route rewrites are applied before the request is forwarded to the destination service.
7. Configuring Route Redirects
| Property | Values | Description |
|---|---|---|
| route.redirect | true |
Enables redirect for the route |
| route.redirect.code | 301, 302 |
HTTP status code for redirect |
| route.redirect.to | /new-path |
Target URI to redirect to |
Example: Redirect Configuration
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: example-redirect
spec:
hosts:
- example.com
http:
- match:
- uri:
prefix: /old-path
redirect:
uri: /new-path
statusCode: 301
8. Implementing Authority Rewrites
| Property | Description | Example |
|---|---|---|
| authority.rewrite | Defines the new authority to rewrite incoming requests to | authority.rewrite: "api.example.com" |
| authority.match | Pattern to match the original authority for rewriting | authority.match: "old-api.example.com" |
Example: Rewrite Authority in Route
routes:
- match:
path: "/api/v1"
rewrite:
authority: "api.example.com"
Note: Authority rewrites are useful for migrating services or changing domain names without updating client configurations.
9. Managing Cross-Namespace Routing
| Property | Description | Example | Notes |
|---|---|---|---|
| namespace | Namespace where the service is deployed | frontend |
Used in routing rules to target services in specific namespaces |
| destination | Destination service and namespace | backend:8080 |
Can include port and namespace in format service.namespace:port |
| route | URI path or pattern to match | /api/v1/users |
Supports wildcard matching like /api/v* |
Example: Cross-Namespace Route Configuration
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: cross-namespace-route
namespace: frontend
spec:
hosts:
- frontend-service
http:
- match:
- uri:
prefix: /api/v1/users
route:
- destination:
host: backend-service
port:
number: 8080
subset: v1
Note: Ensure that the
backend-service is accessible from the frontend namespace, typically via PeerAuthentication or AuthorizationPolicy.
Warning: Misconfigured cross-namespace routing can lead to security vulnerabilities or service disruptions. Always validate namespace access and permissions.
10. Configuring Route Delegation
| Property | Description | Values | Notes |
|---|---|---|---|
| route.delegation.enabled | Enables or disables route delegation | true | false |
Default: false |
| route.delegation.target | Specifies the target service for delegation | string |
Required when delegation is enabled |
| route.delegation.context | Defines the context path for delegated routes | string |
Must start with / |
Example: Route Delegation Configuration
route:
delegation:
enabled: true
target: api-service
context: /api/v1
Note: Route delegation allows a service mesh to forward requests to another service based on URI path matching.
11. Implementing Query String Routing
| Property | Description | Example |
|---|---|---|
| query.param | Matches a specific query parameter in the URI | query.param = "user_id" |
| query.value | Matches a specific value for the query parameter | query.value = "12345" |
| query.regex | Matches query parameter values using regex pattern | query.regex = "user_id=([0-9]+)" |
Example: Route based on query parameter
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: user-service-route
spec:
hosts:
- user-service
http:
- match:
- query:
param: "user_id"
value: "12345"
route:
- destination:
host: user-service-v1
Example: Route using regex pattern
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: product-service-route
spec:
hosts:
- product-service
http:
- match:
- query:
regex: "category=(\w+)"
route:
- destination:
host: product-service-v2
Note: Query string matching is case-sensitive and supports both exact match and regex patterns.
12. Managing Route Timeout Overrides
| Property | Values | Description |
|---|---|---|
| route.timeout | 30s |
Default timeout for route requests |
| route.idleTimeout | 5m |
Idle timeout for route connections |
| route.perRequestTimeout | 10s |
Per-request timeout override for specific routes |