Working with HTTP Routes

Learn how to direct your requests dynamically, to a specific server cluster.

The OVHcloud Load Balancer service redirects the front-end’s incoming traffic to the servers that make up the front-end’s default server cluster, or its default redirection.

In some cases, you can go a step further and route, redirect, or block traffic according to a range of criteria. For example, in the case of an HTTP(S) service, you can filter traffic depending on the HTTP method, the URL, and even a cookie or header value! In the OVHcloud Load Balancer service, these are called routes. A route is a particular action to carry out if one or more conditions are met.

Since this feature is still very new, it is only available in the API. This guide will explain the general principles behind routing, and provide practical examples of routes being used.

Requirements

• an OVHcloud Load Balancer on a solution that lets you create routes
• access to the OVHcloud API

An introduction to routes

A route controls traffic according to different criteria. You can express these criteria as rules, conditions, or actions.

For example, IF the URL starts with '/wp-admin/' (1) AND the connection is in HTTP (2) THEN redirect to the HTTPS version of the page (3).

In this example, there are two rules:

• the connection must come from an HTTP front-end (2)
• its URL must begin with the WordPress admin pages (1)

There is an action associated with these rules: redirect to the HTTPS version of the page (3).

This is what is known as an ‘end action’. It means that if the rules are confirmed, the evaluation of routes stops, and the action is executed.

An introduction to the API

You can only manage routes via the OVHcloud API. It is only valid for http and tcp protocols, and the /ipLoadbalancing/{serviceName}/{protocol}/route/ pathway exposes the API dedicated to routes.

The API for routes to the OVHcloud Load Balancer is specially designed for flexibility, power, and scalability. It is organized around three main sections:

1. the APIs listing available rules and actions
2. the APIs listing the routes configured on the OVHcloud Load Balancer service
3. the APIs for configuring routes on the OVHcloud Load Balancer service

When you want to configure a route or rules, the first thing you need to do is look at the available actions and rules. This will give you the possible values for the API route and rule configuration fields.

• A route can have several rules.
• A route can only be attached to a single front-end.
• A front-end can have several routes. In this case, the order of evaluation depends on its type and weight.

When a request arrives at your OVHcloud Load Balancer service, the routes are evaluated successively following the principles below:

1. First, reject and rewrite routes, then the server cluster routes.
2. Within categories, the routes are evaluated in order of ascending weight.
3. If two routes are the same weight, the first route created is evaluated first.
4. Only the first action from all the validated rules is executed.

Available rules and actions

This first section of the API contains an updated list of actions and rules available for the OVHcloud Load Balancer service. It contains a call for actions and another for rules. These two calls return a list of objects. Each object has a name, and it applies to all TCP or HTTP routes as well as the values or value types expected for different fields of the API. If a field is “null”, this means that no value is expected. If an invalid value is entered, the API will return a validation error.

Actions

GET /ipLoadbalancing/{serviceName}/availableRouteActions

For more information on this call, please read the Available actions section at the bottom of this guide.

Rules

GET /ipLoadbalancing/{serviceName}/availableRouteRules

For more information on this call, please read the Available rules section at the bottom of this guide.

Configured routes

This section of the API only contains one call. It was mainly designed to help implement auto-complete systems. It returns the ID, name, and type of each defined route. You can get a route’s details with a GET /ipLoadbalancing/{serviceName}/<http or tcp>/route/{type}/{routeId} call, defined further below.

GET /ipLoadbalancing/{serviceName}/definedRoutes

For more information on this call, please read the Edit routes section at the bottom of this guide.

Route configuration

With these basic principles around the action and rules available and the order in which routes are evaluated, these routes can be edited the same way as the server clusters can. When you create a route, you can attach rules to it. The possible values for rules and actions are defined by the API calls.

For more information on these calls, please read the Edit routes section at the bottom of this guide.

Examples

If you still have doubts about the power of routes, this should change your mind. The purpose of this section is to offer some practical examples of how this technology has been used for OVHcloud’s internal requirements, without going into great detail about API calls.

You can read about API calls in more detail in the Edit routes section at the bottom of this guide, and the sections that follow it.

Force HTTPS for WordPress login pages

HTTPS protocol has become the norm. Its purpose is to make all websites available securely in HTTPS, with the SSL/TLS protocol. If you need an SSL/TLS certificate, you can use the OVHcloud Load Balancer service to order a new one, which will be automatically managed for you.

Migrating a website to HTTPS involves a lot of work, especially to avoid mixed content. It may be worth migrating your website section by section and starting by securing pages that send login credentials.

One approach could be to base it on the beginning of WordPress URLs. By default, the URLs of login pages for WordPress start with "/wp-login". So we would need:

• a route with a redirect action
• a rule in this route that detects URLs starting with "/wp-login"

In practice, this gives a route like this:

On this route, we will attach a rule:

Next, apply the configuration to the zone concerned, and the rule will begin to work.

Route according to a domain (vhost)

This feature helped propel the expansion of the web at its very early stages, by exposing several websites behind a single IP address using the “host” field of HTTP headers.

For example, if your infrastructure is made up of a VPS for your website, an OVHcloud Load Balancer to ensure SSL/TLS termination, and redirection to a maintenance page with a backup server in the server clusters, you would originally have needed one Additional IP per website, routed to your OVHcloud Load Balancer, and one front-end per IP.

With routes, you can share the same front-end, and choose the server cluster dynamically, with the “host” field.

To do this, you will need:

• one route per vhost
• one rule per route detecting a specific domain

In practice, to route the domain www.example.com, this would give the following route:

And on this route, we will attach a rule:

Finally, apply the configuration.

Reserve an Additional IP for a particular website

If you are hosting a website on a VPS, you may want to dedicate an IP address to a specific customer. You can easily make the IP available by routing it to your OVHcloud Load Balancer service, then configuring a dedicated front-end attached to this Additional IP address, and having the customer’s target VPS set as a defaultFarmId.

But what will happen if another customer detects this, and configures their domain to point to the premium customer’s IP address? By default, this will work, and its website will be routed to the other VPS. If there is an SSL/TLS certificate, it will still work as all of the certificates are automatically available for all of the front-ends.

In such scenarios, the solution is to add a rule that will reject requests if the domain is not a premium one. You can do this with a rejection route and a rule.

In practice, reserving a front-end with an IP dedicated to the domain www.example.com will give the following route:

And on this route, we will attach a rule:

Finally, apply the configuration.

Route depending on a URL and HTTP method

On some specific infrastructures, certain requests need to be routed to a specific server cluster. For example, to manage rare but data-intensive requests without impacting production, such as analytical requests that would work from a read-only duplicate of the data with a server that has a higher volume of memory.

If, for example, the request is sent:

• with the POST method
• on a URL corresponding to "^/.*/batch-analytics$"

... you would need a route with two rules, with one rule using a regular expression.

In practice, this gives a route like this:

And on this route, we will attach two rules:

Here, the first rule applies to a list. Only standard HTTP methods are available. However, the second rule uses all the power of routes using a regular expression. Although it is possible to use expressions like this, if you can go without using them, your performance will be even higher.

Next, apply the configuration to the zone concerned.

Route certain IPs and voluntary clients to a pre-production environment

When your website gains momentum, you may want to set up a pre-production environment, which you can use to check ongoing developments without affecting the majority of your users. Generally, when you configure an environment like this, it is best to minimize the differences between production and pre-production as much as possible, so that any issues can be detected as accurately as possible. A common but often forgotten issue is the domain name, as it is sometimes hard-coded into a file or item. If this is the case, the link may work in pre-production, but not in production.

Instead of setting up rules based on the domain name, you can set up rules based on the source IP (e.g. an enterprise proxy), and possibly a cookie for voluntary clients. These configurations can be detected with two routes on the OVHcloud Load Balancer service.

For this example, we will consider that:

• the enterprise proxy can use the addresses 42.42.42.0/24, and that the VPN uses 1.2.3.4/32
• the voluntary users have a "PreprodOptIn" cookie — it doesn’t matter what the value is

In practice, we would need two identical routes:

Then we will attach the following two rules to each of the routes (one rule per route):

The first rule tests whether the source IP is in the address range list. In this case, the various address ranges are separated by commas and can have spaces in between one another to make them easier to read. If the range only contains one address, the "/32" is implicit, but can be added explicitly. Either way, this field is limited to 255 characters.

The second rule simply tests to see if a cookie exists. It is also possible to test if the value corresponds to a regular expression, or is found in a possibility list, but this offers a simple example of what you can do with cookies. Rules based on HTTP headers work using a similar approach.

Next, apply the configuration to the zone concerned.

Route WebSockets to a dedicated server cluster

When a website has interactive features based on WebSockets — a chatbot, for example — you may want to direct these connections to a server cluster dedicated to this task. This is quite simple. When a browser attempts to open a WebSockets connection, it sends a standard HTTP request with these headers:

Upgrade: websocket
Connection: Upgrade

In this case, only the first header needs to be detected. This can be done very easily with a route and a rule:

And on this route, we will attach a rule:

Next, apply the configuration to the zone concerned.

Reference

Here, you will find more details on the API calls linked to the routes. To get a general idea of how routes work, we recommend starting by reading the introduction to the API section further up.

Edit routes

TCP and HTTP routes are configured the same way. Since the routes are more powerful in HTTP, this section focuses on HTTP rules and routes. TCP routes can be extrapolated from the information below by replacing “http” with “tcp” in each route. Some fields only apply to HTTP routes and are not available in TCP.

List the routes

This call returns the list of ID numbers of routes defined for HTTP protocol. You can filter this list by frontendId. This call returns the routes in the order in which they will be evaluated. The evaluation order can be partially controlled by the weight of the route.

GET /ipLoadbalancing/{serviceName}/http/route

Create a route

With this call, you can create a route. Only the action is mandatory. A route can be attached to and detached from a front-end. You can create up to 50 routes on an OVHcloud Load Balancer. This call returns the route created, if it is successful. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

POST /ipLoadbalancing/{serviceName}/http/route

For further information on the actions managed and the format of parameters, please read the Available actions section further down.

View details on a route

With this call, you can view details on an HTTP route if you know its ID.

GET /ipLoadbalancing/{serviceName}/http/route/{routeId}

For further information on the actions managed and the format of parameters, please read the Available actions section further down.

Modify a route

With this call, you can modify an HTTP route if you know its ID. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

PUT /ipLoadbalancing/{serviceName}/http/route/{routeId}

For further information on the actions managed and the format of parameters, please read the Available actions section further down.

Delete a route

With this call, you can delete an HTTP route if you know its ID. When a route is deleted, all of the rules associated with the route are deleted, too. You do not need to delete them individually. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

DELETE /ipLoadbalancing/{serviceName}/http/route/{routeId}

Edit rules

List the rules

This call returns the list of ID numbers of rules defined for a particular route.

GET /ipLoadbalancing/{serviceName}/http/route/{routeId}/rule

Attach a rule

With this call, you can attach a rule to a route. You can attach up to 5 rules per route on an OVHcloud Load Balancer. This call returns the route created, if it is successful. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

POST /ipLoadbalancing/{serviceName}/http/route/{routeId}/rule

For further information on the rules managed and the format of parameters, please read the Available rules section further down.

View details on a rule

With this call instruction, you can view the details on a rule attached to an HTTP route if you know its ID.

GET /ipLoadbalancing/{serviceName}/http/route/{routeId}/rule/{ruleId}

For further information on the rules managed and the format of parameters, please read the Available rules section further down.

Modify a rule

With this call, you can modify a rule attached to an HTTP route if you know its ID. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

PUT /ipLoadbalancing/{serviceName}/http/route/{routeId}/rule/{ruleId}

For further information on the rules managed and the format of parameters, please read the Available rules section further down.

Delete a rule

With this call, you can delete a rule attached to an HTTP route if you know its ID. You will need to redeploy your OVHcloud Load Balancer to apply the changes.

DELETE /ipLoadbalancing/{serviceName}/http/route/{routeId}/rule/{ruleId}

List all of the TCP and HTTP routes

With this call, you can get a list of all the IDs, display names, and types ("http"/"tcp") of routes defined on an OVHcloud Load Balancer service. It is designed to simplify the implementation of auto-completion.

GET /ipLoadbalancing/{serviceName}/definedRoutes

Actions available

This call returns the list of actions available for TCP and HTTP routes, as well as the values expected for each of the fields.

If a field is “null”, this means that no value is expected. If an invalid value is entered, the API will return a validation error.

All of the actions managed by the OVHcloud Load Balancer service are final. This means that executing an action also triggers the end of route evaluation.

GET /ipLoadbalancing/{serviceName}/availableRouteActions

Available rules

This call returns the list of rules available for TCP and HTTP routes, as well as the values expected for each of the fields.

If a field is “null”, this means that no value is expected. If an invalid value is entered, the API will return a validation error.

GET /ipLoadbalancing/{serviceName}/availableRouteRules

Go further

For more information and tutorials, please see our other OVHcloud Load Balancer guides or explore the guides for other OVHcloud products and services.