When external-facing URLs differ from internal service paths, incoming requests fail to reach the correct backend endpoints. A rewrite policy modifies the path or hostname in requests before the cloud-native gateway forwards them to backend services -- for example, stripping a version prefix like /v1 or routing traffic to a different host during a migration.
How rewrite policies work
Cloud-native gateways support two categories of rewrite:
Path rewrite -- Changes the URL path. Three methods are available: exact rewrite, prefix rewrite, and regex rewrite.
Host rewrite -- Changes the hostname. Only exact rewrite is supported.
Rewrite method compatibility
Each rewrite method requires a specific route matching type. Before you configure a rewrite policy, verify that the route uses a compatible matching type.
| Route matching type | Compatible rewrite methods |
|---|---|
| Exact Match | Exact Rewrite |
| Prefix Match | Prefix Rewrite, Regex Rewrite |
| Regex Match | Exact Rewrite, Regex Rewrite |
Path rewrite methods
Exact rewrite
Exact rewrite replaces the entire request path with a new path.
Example: Rewrite /app/test to /foo/bar
| Setting | Value |
|---|---|
| Route matching type | Exact Match |
| Route path | /app/test |
| Rewrite method | Exact Rewrite |
| Destination path | /foo/bar |
Exact rewrite only works with the Exact Match or Regex Match route matching types. It is not compatible with Prefix Match.
Prefix rewrite
Prefix rewrite replaces only the matched prefix portion of the request path. The remainder of the path stays unchanged.
Example 1: Strip the /app prefix -- rewrite /app/test to /test
| Setting | Value |
|---|---|
| Route matching type | Prefix Match |
| Route path | /app/ |
| Rewrite method | Prefix Rewrite |
| Destination path | / |
The trailing slash in /app/ is required. Prefix rewrite only replaces the matched prefix. If you set the route path to /app (without the trailing slash), the rewritten path becomes //test, which is invalid.
Example 2: Swap a version prefix -- rewrite /v1/test to /v2/test
| Setting | Value |
|---|---|
| Route matching type | Prefix Match |
| Route path | /v1 |
| Rewrite method | Prefix Rewrite |
| Destination path | /v2 |
Prefix rewrite only works with the Prefix Match route matching type. All requests whose path starts with the specified prefix are matched and rewritten, so confirm that broad rewriting is intended. To rewrite only specific paths, use exact rewrite instead.
Regex rewrite
Regex rewrite uses a regular expression to match and replace parts of the request path. A regex rewrite configuration has two parameters:
Mode -- The regex pattern that identifies the parts of the path to replace.
Replacement -- The substitution string that replaces the matched parts.
The gateway uses RE2 regular expression syntax. To test patterns before applying them, use an online tool such as Regex101 (select the Golang flavor, which uses RE2).
Example 1: Global substitution -- rewrite /aaa/one/bbb/one/ccc to /aaa/two/bbb/two/ccc
| Setting | Value |
|---|---|
| Route matching type | Exact Match |
| Route path | /aaa/one/bbb/one/ccc |
| Rewrite method | Regex Rewrite |
| Mode | one |
| Replacement | two |
Example 2: Capture group reordering -- for requests matching /httpbin/(.*)/(.*), remove the /httpbin prefix and swap the two captured segments
| Setting | Value |
|---|---|
| Route matching type | Regex Match |
| Route path | /httpbin/(.*)/(.*) |
| Rewrite method | Regex Rewrite |
| Mode | /httpbin/(.*)/(.*) |
| Replacement | /\2/\1 |
In the replacement string, \1 refers to the first capture group and \2 refers to the second. These are equivalent to $1 and $2 in NGINX Ingress.
Regex rewrite is the most complex rewrite method. When a simpler exact rewrite or prefix rewrite achieves the same result, prefer those methods.
Host rewrite
Host rewrite replaces the hostname in the request using the exact rewrite method.
Example: Rewrite the hostname from test.com to dev.com
Set Destination Host in the rewrite policy to dev.com.
Configure a rewrite policy
Prerequisites
Before you begin, make sure that you have:
A cloud-native gateway instance in MSE
At least one route configured on the gateway
Procedure
Log on to the MSE console. In the top navigation bar, select a region.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. On the Gateways page, click the name of your gateway.
In the left-side navigation pane, click Routes, and then click the Routes tab.
Find the target routing rule and click Policies in the Actions column.
On the Policies tab, click Rewrite in the left-side navigation pane. Configure the rewrite parameters and click Save. The available rewrite methods depend on the route matching type:
Original Path type Available Destination Path types Exact Match Exact Rewrite Prefix Match Prefix Rewrite, Regex Rewrite Regex Match Exact Rewrite, Regex Rewrite Turn on the Enable switch. In the confirmation dialog, click OK.
Enabled: The gateway rewrites paths and hostnames based on the configured policy before forwarding requests to backend services.
Disabled: The gateway forwards requests without modifying paths or hostnames.
Verify the result
This example uses a prefix rewrite to strip the /app1 routing prefix from external requests. The backend service expects paths without this prefix, so the rewrite policy maps /app1/ to /.
Original request (with the /app1 prefix):
curl -I http://121.196.XX.XX/app1/demo/item/listAfter the rewrite (the gateway forwards the request to the backend with the path /demo/item/list):
curl -I http://121.196.XX.XX/demo/item/list