custom-per-route-options.html.md.erb

---
title: Configuring per-route options
owner: CF for VMs Networking
---

By default, communication between Gorouter and backends is configured via general settings at the platform level.

This topic describes how to specify per-route Gorouter options scoped at the application level.
This greater granularity lets developers tailor optimal routing behavior for applications' unique load profiles or other requirements.

Gorouter supports the following per-route option, described in the section below:

- `loadbalancing`: Configures the load balancing algorithm used by Gorouter for this particular route. <%= vars.per_route_lb_version %>
   - Settings: `round-robin`, `least-connections`.

## <a id="loadbalancing"></a> loadbalancing: Configure Gorouter's Load Balancing Algorithm

<%= vars.per_route_lb_version %>

The per-route option `loadbalancing` allows configuring the load balancing algorithm, which defines how the load is distributed between Gorouters and backends.

This option supports two settings for load balancing:

- `round-robin` distributes the load evenly across all available backends
- `least-connections` directs traffic to the backend with the fewest active connections at any given time, optimizing resource utilization


### <a id="lb-set-manifest"></a> Configure Load Balancing in an App Manifest

To configure per-route load balancing for an application that has not yet been pushed:

1. In the application manifest, include a `route` definition with an `options: loadbalancing` attribute set to `round-robin` or `least-connections`. For example:

   	```yaml
   	---
   	applications:
   	- name: MY-APP
   	  routes:
   	    - route: MY-APP.EXAMPLE.COM
           options:
             loadbalancing: least-connections
   	```

    Where `MY-APP` is the name of your app and `MY-APP.EXAMPLE.COM` is the route you want to map to your app.

1. Push the app with the manifest:

    ```
    cf push -f manifest.yml
    ```

1. To confirm the setting, query the `routes` API endpoint for the app's route:

    ```
    cf curl /v3/routes/?hosts=MY-APP
    ```

    Where `MY-APP` is the host attribute of the route. The response lists the chosen `loadbalancing` algorithm setting:


    ```
       "options": {
         "loadbalancing": "least-connections"
       }
    ```

### <a id="lb-update-curl"></a> Change Load Balancing of an Existing App

To change the per-route `loadbalancing` setting of an app that has already been pushed, `cf curl` the `/v3/routes` API.
For example, to change an app route's algorithm from `least-connections` to `round-robin`:

1. Execute a `PATCH` request to the targeted API endpoint:


    ```
    cf curl /v3/routes/GUID -X PATCH -H "Content-type: application/json" \
      -d '{
        "options": {
          "loadbalancing": "round-robin"
        }
      }'
    ```

    Where `GUID` is the unique identifier for the route.

1. To confirm the setting, query the `routes` API endpoint for the route:

    ```
    cf curl /v3/routes/GUID
    ```

    Where `GUID` is the unique identifier for the route. The response lists the new `round-robin` setting:

    ```
    "options": {
      "loadbalancing": "round-robin"
    }
    ```