Configuring per-route options

Page last updated:

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. Available from cf-deployment v48.1.0, together with cf CLI 8.10.0 and later.
  • 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. Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.
• 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. Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.

Configure Gorouter’s Load Balancing Algorithm

Available from cf-deployment v48.1.0, together with cf CLI 8.10.0 and later.

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 for details. Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.

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:

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

2. Push the app with the manifest:

   cf push -f manifest.yml
   

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:

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

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:

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

The command map-route supports the --option flag only for new routes. To update an existing route, use the command update-route described below.

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:

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

Remove the Specific Load Balancing Algorithm Using the CF CLI

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

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

Configure Hash-Based Routing

Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.

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.

For instructions on configuring hash-based routing using the app manifest or the CF CLI, see Configure Hash-Based Routing.

Retrieve Route Options

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

cf route EXAMPLE.COM --hostname MY-HOST

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

options: {loadbalancing=least-connection}

Or hash with its related options:

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