---
schema_version: "1"
id: f0f4f118c5f9aec6d6880ea5cd03c5cee23ecea7a7aa3cba5cc92ca7e96c4e0d
title: Traffic Management for Multiple Upstream Services
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-traffic-management-route.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management-route
source_site: docs.mulesoft.com
content_type: documentation
content_hash: b1e263d11c1ac08a117a5e6c47c1f239d3881de13ce520749369ffba5a7bab4b
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: route, traffic management, upstream service
---

# Traffic Management for Multiple Upstream Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Omni Gateway running in Local Mode. To configure
> multiple upstream services for Omni Gateway running in Connected Mode, see
> [Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Omni Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Omni Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about adding weight percentages, refer to
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management).

To allow routing requests to a `Service` when an `ApiInstance` does not include `spec.services`, you
must define a `PolicyBinding` configuration with the Traffic Management for Multiple Upstream
Services (`route`) policy. You don’t need to configure a `route` policy if a custom policy is
managing requests.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route config: destinationPath: <string> // OPTIONAL, default: "/" destinationRef:
name: <string> // REQUIRED kind: <string> // OPTIONAL, default: "Service" namespace: <string> //
OPTIONAL, default: "" rules:

- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>destinationPath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"/"</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.kind</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"Service"</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>destinationRef.namespace</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

You can define an `ApiInstance` configuration that does not include the `spec.services` parameter:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080/api
```

Given the absence of the `spec.services` parameter, you must define the `route` policy in a
`PolicyBinding` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-httpbin-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationPath: /orders
    destinationRef:
      name: orders-svc
  rules:
    - path: /v1(/.*)
```

The related `Service` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: orders-svc
spec:
  address: https://orders.svc.local:443/
```

## Determining a Request Path

The following table describes all the possible parameter combinations, with examples of the
attributes that determine routing and the expected transformation of a request’s path. The columns
refer to data values of the attributes in the previous configuration examples.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>ApiInstance .address .path</th><th>PolicyBinding(route) .rules .path</th><th>PolicyBinding(route) .config .destinationPath</th><th>Input Path</th><th>Output Path</th></tr></thead><tbody><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/items</p></td></tr><tr><td><p>/api</p></td><td><p>/checkout()</p></td><td><p>/orders</p></td><td><p>/api/checkout</p></td><td><p>/orders</p></td></tr><tr><td><p>/api</p></td><td><p>/api/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>&lt;no match&gt; (expected a path like /api/api/v1/items)</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/us/42</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>/orders</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/orders/us/42</p></td></tr></tbody></table>

## Route Requests to an Unrelated Upstream Path

To route requests to an upstream path unrelated to the request path, add an empty capture group,
`()`, to `rules.path`. Omni Gateway appends only captured text to `destinationPath`, so with an
empty group it sends the request to `destinationPath` unchanged.

This is useful for SOAP services, where clients call a fixed WSDL URL and the `SOAPAction` header
determines the operation.

For example, this configuration routes `/api/masterdata/CustomerService` to
`[https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service](https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service)`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-soap
spec:
  address: http://0.0.0.0:8080/api/masterdata
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-soap-route
spec:
  targetRef:
    name: ingress-soap
  policyRef:
    name: route
  config:
    destinationPath: /sap/bc/srt/scs/sap/customer_service
    destinationRef:
      name: soap-svc
  rules:
    - path: /CustomerService()
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: soap-svc
spec:
  address: https://soap.svc.local:443/
```

## See Also

- [Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-api-multiple-services)