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 through the 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 options, described in the sections below:

- `loadbalancing`: Configures the load balancing algorithm used by Gorouter for this particular route. <%= vars.per_route_lb_version %>
   - Settings: `round-robin`, `least-connection`, `hash`.
- `hash_header`: Defines the HTTP header used for hash-based routing decisions. Required when `loadbalancing` is set to `hash`. Cannot be used with other load balancing algorithms. <%= vars.hash_routing_version %>
- `hash_balance`: Sets the float number for the balance factor used by Gorouter to manage load imbalance applying the hash-based routing for this route. Optional when `loadbalancing` is `hash`. Cannot be used with other algorithms. <%= vars.hash_routing_version %>

<p class="note">
<span class="note__title"><strong>Note</strong></span>
Identity-aware routing is configured with the dedicated <code>cf add-route-policy</code> / <code>cf route-policies</code> / <code>cf remove-route-policy</code> commands rather than the <code>--option</code> flag described here. The Gorouter applies route policies through internal route options (<code>route_policy_scope</code>, <code>route_policy_sources</code>) that are managed by the platform and are not returned in route API responses. See <a href="deploy-apps/identity-aware-routing.html">Configuring identity-aware routing</a>.
</p>

## <a id="loadbalancing"></a> 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 the following settings for load balancing:

- `round-robin` distributes the load evenly across all available backends
- `least-connection` directs traffic to the backend with the fewest active connections at any given time, optimizing resource utilization
- `hash` distributes requests based on a specific HTTP header value, ensuring requests with the same header value are consistently directed to the same backend. See [Hash-Based Routing](hash-based-routing.html) for details. <%= vars.hash_routing_version %>

### <a id="lb-set-manifest"></a> Configure Load Balancing using 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-connection`. For example:

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

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

1. Push the app with the manifest:

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

### <a id="lb-create-route"></a> Create a Route with a Specific Load Balancing Algorithm Using the CF CLI

To create a route with a per-route `loadbalancing` option, you can use the CLI command `create-route`.
For example:

```console
cf create-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
```

### <a id="lb-map-route"></a> Map a Route to an Existing App with a Specific Load Balancing Algorithm Using the CF CLI

To create and map a new route to an existing application with the per-route `loadbalancing` option, you can use the CLI command `map-route`.

For example:

```console
cf map-route MY-APP EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
```

<p class="note">
<span class="note__title"><strong>Note</strong></span>
The command <code>map-route</code> supports the <code>--option</code> flag only for new routes.
To update an existing route, use the command <code>update-route</code> described below.
</p>


### <a id="lb-update-route"></a> Update the Load Balancing Algorithm of an Existing Route Using the CF CLI

To change the per-route `loadbalancing` option of an existing route, you can use the CLI command `update-route`.

For example, to change an app route's algorithm from `least-connection` to `round-robin`, you can run the `update-route` command:

```console
cf update-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
```

### <a id="lb-remove-route-option"></a> Remove the Specific Load Balancing Algorithm Using the CF CLI

To remove the `loadbalancing` option from an existing route, run:

```console
cf update-route EXAMPLE.COM --hostname MY-HOST -r loadbalancing
```

## <a id="hash-based-routing"></a> Configure Hash-Based Routing

<%= vars.hash_routing_version %>

Hash-Based Routing is a load-balancing method that routes incoming requests to application instances based on a specific HTTP header value. This ensures consistent routing, so requests with the same header value are always routed to the same instance.

For details on Hash-Based Routing concepts, features, and how it compares to Session Affinity, see [Hash-Based Routing](hash-based-routing.html).

For instructions on configuring hash-based routing using the app manifest or the CF CLI, see [Configure Hash-Based Routing](hash-based-routing.html#configure).

## <a id="lb-retrieve-route-options"></a> Retrieve Route Options

To view route options, you can query the route using the `route` command:

```console
cf route EXAMPLE.COM --hostname MY-HOST
```

The response lists the chosen `loadbalancing` algorithm option, e.g. `least-connection`:

```console
options: {loadbalancing=least-connection}
```

Or `hash` with its related options:

```console
options:    {hash_balance=1.2, hash_header=HASH-HEADER-NAME, loadbalancing=hash}
```