Using Weighted Routing (Beta)

Page last updated:

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

Overview

The weighted routing feature is available for Pivotal Application Service deployments that use service mesh. For more information, see Service Mesh (Beta).

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.

How Weights are Used to Calculate Percentage of Requests

PAS 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: app-a and app-b. The percentage of requests for app-b is calculated as follows:

weight of app-b / ( weight of app-a + weight of app-b )

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

App Weight Formula Percentage of Requests
app-a 1 1 / ( 1 + 3 ) 25%
app-b 3 3 / ( 1 + 3 ) 75%

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

Considerations for Working with Routing Weights

Consider the following when working with routing weights:

  • The default weight is 1. 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 0. You can stop weighting traffic by deleting apps or unmapping apps from the route.
  • You cannot exceed 100 route mappings for a particular route. This could result in some apps not receiving any requests.

Configure Routing Weights

Note: This feature does not yet have cf CLI integration. The steps for updating a routing weight require you to curl the Cloud Controller v3 API.

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.

Create a New Route Mapping

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

  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.

  2. 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.

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

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

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

    cf app APP-NAME --guid

  4. 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 Used to Calculate Percentage of Requests above.

Update an Existing Route Mapping

This procedure requires that you have mapped an app to a route in *.mesh.YOUR-APPS-DOMAIN either using cf map-route, or cf curl as described in Create a New Route Mapping 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

  2. 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.

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

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

  3. 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.

  4. 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: 

    $ 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": {
        "guid": "9feb9667-9249-44b7-9e4e-92157a2aaefb",
        "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,
        "app_guid": "bf65b03d-5416-4603-9de2-ef74491d29b6",
        "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"
      }
    }
  ]
}

  5. Update the route mapping with a new weight:

    cf curl /v3/route_mappings/ROUTE-MAPPING-GUID -X PATCH -d '{"weight": WEIGHT}'

    Where:

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

  2. 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.

  3. 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.

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