weighted-routing.html.md.erb

---
title: Using Weighted Routing (Beta)
owner: Routing
---

<style>
.app-a {
	color: #0065d5;
}

.app-b {
	color: #971922;
}
.guid {
  color: #5FABFF;
}
</style>

This topic provides information about weighted routing and how to configure weighted routing for your apps.  

## <a id="overview"></a> Overview

<% if vars.product_name.include? "CF" %>

The weighted routing feature is available for <%= vars.product_full %> deployments that use service mesh. For more information, see [Service Mesh (Beta)](../adminguide/service-mesh.html).

<% else %>
<% end %>

Weighted routing allows you to map multiple apps to the same route and control the amount of traffic sent to each of them. Some use cases include blue-green deployments, A/B testing, canary releases, or rolling out features over time to incremental user-bases. 

### <a id="calculation"></a> How Weights are Calculated

<%= vars.product_short %> uses numeric weight values to calculate the percentage of requests that each app receives. For a route with multiple apps mapped, the percentage of requests for a given app is calculated as follows:

 _weight of app_ / _sum of the weights of all apps mapped to route_

Consider an example in which two apps are mapped to the same route: <code class="app-a">app-a</code> and <code class="app-b">app-b</code>. The percentage of requests for <code class="app-b">app-b</code> is calculated as follows:

<span class="app-b">weight of <code>app-b</code></span> / ( <span class="app-a">weight of <code>app-a</code></span> + <span class="app-b">weight of <code>app-b</code></span> )

The following table uses example values to show how the percentage of requests is calculated for the two apps: 

<table>
	<tr>
		<th>App</th>
		<th>Weight</th>
		<th>Formula</th>
		<th>Percentage of Requests</th>
	</tr>
	<tr>
		<td><code class="app-a">app-a</code></td>
		<td><code class="app-a">1</code></td>
		<td><code class="app-a">1</code> / ( <code class="app-a">1</code> + <code class="app-b">3</code> )</td>
		<td><code class="app-a">25%</code></td>
	</tr>
	<tr>
		<td><code class="app-b">app-b</code></td>
		<td><code class="app-b">3</code></td>
		<td><code class="app-b">3</code> / ( <code class="app-a">1</code> + <code class="app-b">3</code> )</td>
		<td><code class="app-b">75%</code></td>
	</tr>
</table>

In this example, you can also unmap the route from one of the apps and observe <code>100%</code> of the requests going to just one app, which simulates a migration.

### <a id="considerations"></a> Considerations for Working with Routing Weights

Consider the following when working with routing weights:

* The default weight is <code>1</code>. This means that if multiple apps are mapped to the same route and their weights are not updated, traffic is equally distributed between them.  
* The percentage of requests described above is not applied exactly, but over time the requests reflect the percentage.
* You cannot set a weight to <code>0</code>. You can stop weighting traffic by deleting apps or unmapping apps from the route. 
* You cannot exceed <code>100</code> routes mappings for a particular route. This could result in some apps not receiving any requests.


## <a id="procedure"></a> Configure Routing Weights

<p class="note"><strong>Note</strong>: This feature does not yet have cf CLI integration. The steps for updating a routing weight require you to <code>curl</code> the Cloud Controller v3 API.</p>

You can configure routing weights when creating or updating a route mapping. Follow the procedure below that corresponds to your use case. 

You can repeat the steps for each app that you want to receive a portion of requests at the same route.  

### <a id="new"></a> Create a New Route Mapping

This procedure describes how to use `cf curl` to map a route to an app and assign a weight.  

<% if vars.product_short == "CF" %>

1. If you do not already have one, create a route. The route must use the shared domain created for service mesh:

	```
	cf create-route SPACE-NAME SHARED-ISTIO-DOMAIN -n HOSTNAME
	```
	Where:
	* `SPACE-NAME` is the space in which you want to create the route. 
	* `SHARED-ISTIO-DOMAIN` is the shared Istio domain configured by your operator. 
	* `HOSTNAME` is the hostname to use for creating the route. The format of the route is `HOSTNAME.SHARED-ISTIO-DOMAIN`. 

<% else %>

1. If you do not already have one, create a route. The route must use the domain created for service mesh:

	```
	cf create-route SPACE-NAME mesh.YOUR-APPS-DOMAIN -n HOSTNAME
	```
	Where:
	* `SPACE-NAME` is the space in which you want to create the route. 
	* `YOUR-APPS-DOMAIN` is the shared domain for apps configured by your operator. 
	* `HOSTNAME` is the hostname to use for creating the route. The format of the route is `HOSTNAME.mesh.YOUR-APPS-DOMAIN`. 

<% end %>

1. Run the following command and record the GUID of your route:

	```
	cf curl /v2/routes?q=host:HOSTNAME
	```
	Where `HOSTNAME` is the hostname you specified when creating the route.<br><br>

	The GUID of the route is located after `"metadata": {"guid":`. See the following example in which the GUID is highlighted in blue:

	<pre class="terminal">
	$ cf curl /v2/routes?q=host:my-hostname
	{
	  "total_results": 1,
	  "total_pages": 1,
	  "prev_url": null,
	  "next_url": null,
	  "resources": [
	    {
	      "metadata": {
	        <span class="guid">"guid": "311d34d1-c045-4853-845f-05132377ad7d"</span>,
	        "url": "/v2/routes/311d34d1-c045-4853-845f-05132377ad7d",
	        "created_at": "2016-06-08T16:41:44Z",
	        "updated_at": "2016-06-08T16:41:26Z"
	      },
	      . . . 
	</pre>

1. Run the following command and record the GUID of the app that you want to map the route to:

	```
	cf app APP-NAME --guid
	```

1. Create a route mapping and assign a weight:

	```
	cf curl /v3/route_mappings -X POST -d \
	'{
      "relationships": {
        "app": {
          "guid": "APP-GUID"
        },
        "route": {
          "guid": "ROUTE-GUID"
        }
      },
      "weight": WEIGHT
    }'
	```
	Where:
	* `APP-GUID` is the app GUID you recorded previously
	* `ROUTE-GUID` is the route GUID you recorded previously
	* `WEIGHT` is an integer used to calculate the percentage of requests the app receives. You can enter a value from `1` to `128`. See [How Weights are Calculated](#calculation) above. 

### <a id="existing"></a> Update an Existing Route Mapping

This procedure requires that you have mapped an app to a route in <% if vars.product_name == "CF" %> shared Istio domain <%else%> `*.mesh.YOUR-APPS-DOMAIN` <%end%>  either using `cf map-route`, or `cf curl` as described in [Create a New Route Mapping](#new) above. 

To update an existing route mapping with a new weight, do the following:

1. Run the following command and record the GUID of the app:

	```
	cf app APP-NAME --guid
	```


1. Run the following command and record the GUID of the route:
	
	```
	cf curl /v2/routes?q=host:HOSTNAME
	``` 
	Where `HOSTNAME` is the hostname you specified when creating the route. This is generally the same as the app name.<br><br>
	
	The GUID of the route is located after `"metadata": {"guid":`. See the following example in which the GUID is highlighted in blue:

	<pre class="terminal">
	$ cf curl /v2/routes?q=host:my-hostname
	{
	  "total_results": 1,
	  "total_pages": 1,
	  "prev_url": null,
	  "next_url": null,
	  "resources": [
	    {
	      "metadata": {
	        <span class="guid">"guid": "311d34d1-c045-4853-845f-05132377ad7d"</span>,
	        "url": "/v2/routes/311d34d1-c045-4853-845f-05132377ad7d",
	        "created_at": "2016-06-08T16:41:44Z",
	        "updated_at": "2016-06-08T16:41:26Z"
	      },
	      . . . 
	</pre> 

1. List the route mappings associated with the route:
	
	```
	cf curl /v2/routes/ROUTE_GUID/route_mappings
	``` 
	Where `ROUTE_GUID` is the route GUID you got from the previous step. 
	
1. In the output from the previous step, find the route mapping that contains the `app_guid` from when you ran `cf app --guid`. Record the GUID of the route mapping. See the following example output in which both the route mapping and app guids are highlighted in blue:
	<pre class="terminal">
	$ cf curl /v2/routes/521c375d-a7e2-4f87-9527-7fd1db1b2010/route_mappings
	{
	  "total_results": 1,
	  "total_pages": 1,
	  "prev_url": null,
	  "next_url": null,
	  "resources": [
	    {
	      "metadata": {
	        <span class="guid">"guid": "9feb9667-9249-44b7-9e4e-92157a2aaefb"</span>,
	        "url": "/v2/route_mappings/9feb9667-9249-44b7-9e4e-92157a2aaefb",
	        "created_at": "2016-06-08T16:41:28Z",
	        "updated_at": "2016-06-08T16:41:26Z"
	      },
	      "entity": {
	        "app_port": null,
	        <span class="guid">"app_guid": "bf65b03d-5416-4603-9de2-ef74491d29b6"</span>,
	        "route_guid": "521c375d-a7e2-4f87-9527-7fd1db1b2010",
	        "app_url": "/v2/apps/bf65b03d-5416-4603-9de2-ef74491d29b6",
	        "route_url": "/v2/routes/521c375d-a7e2-4f87-9527-7fd1db1b2010"
	      }
	    }
	  ]
	}	
	</pre>

1. Update the route mapping with a new weight:

	```
	cf curl /v3/route_mappings/ROUTE-MAPPING-GUID -X PATCH -d '{"weight": WEIGHT}'
	```
	Where:
	* `ROUTE_MAPPING_GUID` is the route mapping GUID you got from the previous step.
	* `WEIGHT` is an integer used to calculate the percentage of requests the app receives. You can enter a value from `1` to `128`. See [How Weights are Calculated](#calculation) above.  

## <a id="observe"></a> Confirm Routing Weights

If you have two or more apps mapped to the same route, one way you can confirm routing weights is to use `curl` to view the amount of requests to each app. 

To view the amount of requests to each app, do the following:

1. For each app mapped to the route, open a terminal window and run the following command. This allows you to see streaming logs for the apps. 

	```
	cf logs APP-NAME
	```

1. In another terminal window, run the following command to send a `curl` request to the route every `N` seconds. 

	```
	while sleep N; do curl ROUTE; done
	```
	Where:
	* `N` is the frequency, in seconds, with which you want to `curl` the route. 
	* `ROUTE` is the route that you have multiple apps mapped to. 

1. Observe each window in which you are running `cf logs APP-NAME`. The output displays a log message each time there is a request. The amount of requests each app receives corresponds to its configured routing weight. 

1. When finished, enter `Ctrl + C` to stop sending requests with the `while` loop.