Working with HTTP routes

Last updated 09th April 2018

Objective

The OVH Load Balancer service redirects the front-end’s incoming traffic to the servers that make up the front-end’s default farm, 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 a HTTP(S) service, you can filter traffic depending on the HTTP method, the URL, and even a cookie or header value! In the OVH Load Balancer service, these are called routes. A route is a particular action to carry out if one or more conditions are met.

This guide will show you how to direct your requests dynamically, to a specific farm.

Requirements

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

Instructions

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.

• 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 a 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 OVH 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 OVH Load Balancer is specially designed for flexibility, power and scalability. It is organised around three main sections:

1. the APIs listing available rules and actions
2. the APIs listing the routes configured on the OVH Load Balancer service
3. the APIs for configuring routes on the OVH 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 OVH Load Balancer service, the routes are evaluated successively following the principles below:

1. firstly, reject and rewrite routes, then the farm 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 OVH 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 if 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

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

Rules:

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}/route/{type}/{routeId} call, defined further below.

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 farms 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 OVH’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 OVH 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 URL the 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 OVH Load Balancer to ensure SSL/TLS termination, and redirection to a maintenance page with a backup server in the farms, you would originally have needed one Additional IP per website, routed to your OVH Load Balancer, and one front-end per IP.

With routes, you can share the same front-end, and choose the server farm 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 to 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 OVH 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, to reserve a front-end with an IP dedicated to the domain www.example.com, this 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 farm. 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 on 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 minimise 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 OVH 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 farm.

When a website has interactive features based on WebSockets — a chatbot, for example — you may want to direct these connections to a server farm dedicated to this task. This is actually 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 off 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.

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 OVH Load Balancer. This call returns the route created, if it is successful. You will need to re-deploy your OVH Load Balancer to apply the changes.

The possible action types are listed below:

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.

Query

Answer

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 re-deploy your OVH Load Balancer to apply the changes.

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 re-deploy your OVH Load Balancer to apply the changes.

Edit rules.

List the rules.

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

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 OVH Load Balancer. This call returns the route created, if it is successful. You will need to re-deploy your OVH Load Balancer to apply the changes.

field

match

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.

Query

Answer

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 re-deploy your OVH Load Balancer to apply the changes.

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 re-deploy your OVH Load Balancer to apply the changes.

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 OVH Load Balancer service. It is designed to simplify the implementation of auto-completion.

Query

Answer

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 OVH Load Balancer service are final. This means that executing an action also triggers the end of route evaluation.

Query

Answer

Redirection

This action sends a redirection to the visitor. This redirection type can be configured with the status field. When this action is selected, no farms will receive the request.

Only the HTTP redirection status codes can be specified. The most common codes are 301 and 302. If you have any doubts, you can set up a 302 (temporary redirection). The HTTP status codes for redirections are:

The target URL may contain simple variables. This helps users redirect to another domain, another protocol or add a suffix/prefix to a URL. The recognised variables are:

For example, for:

• redirect to https: https://${host}${path}${arguments}
• redirect to a new domain: ${protocol}://new.example.com${path}${arguments}
• prefix the URL: ${protocol}://${host}/staging${path}${arguments}

Reject.

This action returns an HTTP error status code to the visitor. The HTTP error code can be configured with the status field. When this action is selected, no farms will receive the request.

Only the HTTP error codes listed in the API can be specified. The most common ones are 400 ("Bad request") errors, and 403 ("Forbidden") errors. A 200 code can be used to block a request type while simulating a success, and a 503 code can be used to simulate a server outage.

Routing.

This action redirects requests to a specific farm, other than the default farm configured on the front-end. The destination farm must be the same type as the front-end ("http" or "tcp").

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.

Query

Answer

The different pattern types are:

Protocol.

With this rule, you can filter requests depending on their protocol. In practice, the uses for this rule are quite limited, as the protocol depends on the front-end that the route is attached to, or a front-end that only manages a single protocol recognised the moment the route is defined.

Source address.

With this rule, you can filter requests depending on their source address. By combining it with a rule based on the URI or the domain name, you can restrict certain resources to an enterprise proxy while exposing all of your other resources without restrictions, via your OVH Load Balancer.

To block a particular network and address, for example, you can use a pattern like "4.4.0.0/16, 8.8.8.8".

Domain name.

With this rule, you can filter requests depending on their domain name. In doing so, you can reproduce the Apache "vhost" feature, or route all of the domains that start with "mail." to a server dedicated to webmail.

HTTP method.

With this rule, you can filter requests depending on their HTTP method. It is commonly used alongside a rule based the request URI or path, to make the rule more selective.

Request path.

With this rule, you can filter requests depending on their path, or URI. The request path is between the first '/' (inclusive) and the first '?' (excluded).

Request parameter.

This rule filters requests depending on their existence, or the value of a specific HTTP request parameter. This is the part after the first '?'. If a parameter is specified several times in a request, only the first instance is taken into account.

HTTP header.

This rule filters requests depending on their existence, or the value of a specific HTTP header value. You can use it to detect the opening of a WebSocket connection, and direct it to a dedicated server farm.

Cookie.

With this rule, you can filter requests depending on the existence or value of a specific HTTP cookie. You can use it to direct voluntary visitors to a pre-production farm.

Go further

Join our community of users on https://community.ovh.com/en/.

These guides might also interest you...