Skip to main content

Share a backend between routes

When several routes send to the same backend nodes, list the backend nodes once as an upstream and let each route pick it. An upstream can also probe its backend nodes and stop sending to one that fails. This guide creates the upstream orders with the two backend nodes of the orders backend and a health check, and points orders-api at it. At the end, a restarted backend node receives no requests until it answers its health probe again.

Before you start​

  • The address and port of each backend node, reachable from the gateway nodes. This guide uses 10.0.1.10:8080 and 10.0.1.11:8080.
  • A path each backend node answers with 200 while it is well. This guide uses /health. Ask the team that runs the backend which path that is. The default, /, serves as a probe only when the backend answers 200 or 302 there.
  • Access to each backend node's own log, where the probes and the requests below show up.
  • The requests below call /orders/42.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • This guide starts from orders-api as Route requests to a backend leaves it, with no other plugin. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Open a new upstream and name it​

In the menu, select Upstreams, then New upstream. Under General, set Name to orders. This is the name you will pick on the route.

2. Add the two backend nodes​

Under Targets, Nodes is already chosen. Select Add entry for each row.

HostPortWeight
10.0.1.1080801
10.0.1.1180801

Leave Priority empty in both rows. These are the same rows a route fills under Nodes on this route. There they belong to one route; here every route that picks the upstream shares them.

3. Leave the balancing as it is​

Under Balancing, leave Type at roundrobin, Host passing at pass and Retries empty. The backend nodes take requests in turn, each receives the host name the client used, and a request one backend node refuses is tried on the other.

4. Turn on the health check​

Under Health checks, turn on Active health check. Fill in these fields and leave the rest as they are.

FieldValueWhy
Path/healthThe path the gateway probes on every backend node.
Healthy › Interval1How often a backend node in rotation is probed, in seconds.
Healthy › Successes2Probes in a row that bring a backend node back.
Unhealthy › Interval1How often a backend node taken out is probed, in seconds.
Unhealthy › HTTP failures2Failed probes in a row that take a backend node out.

Type every value, also where a field already shows it in grey. The grey text is the field's default, shown as a hint, and the form does not save it. Typed out, the values are part of the upstream below.

5. Create the upstream​

Select Create upstream. The upstream is saved like this:

upstream · as the console saves it
{
  "name": "orders",
  "type": "roundrobin",
  "nodes": {
    "10.0.1.10:8080": 1,
    "10.0.1.11:8080": 1
  },
  "checks": {
    "active": {
      "http_path": "/health",
      "healthy": {
        "interval": 1,
        "successes": 2
      },
      "unhealthy": {
        "interval": 1,
        "http_failures": 2
      }
    }
  }
}

6. Point the route at the upstream​

Open Routes, open orders-api and select Edit route. Under Target, choose Upstream instead of Nodes on this route and pick orders in Upstream. Select Save route.

The Target section of the route form, with Upstream chosen and orders picked.

Every route that should reach these backend nodes picks orders the same way. The guides that follow assume orders-api as this guide leaves it, sending to the upstream orders.

Check it​

Send the request several times and read both logs. Then stop the second backend node, 10.0.1.11:8080, or restart it, and send the request again. Once the second backend node answers /health again, send it once more.

curl
curl -i -L 'https://<gateway host>/orders/42'
Both backend nodes well
While both backend nodes pass their probes, repeated requests are shared by the two, each answered 200.
In each backend node’s own log
Each backend node receives GET /health from the gateway: the probe that decides whether it stays in rotation.
The second one out
Once the second backend node has failed its probe twice in a row, every request is answered 200 by the first: the second is out of rotation.
Back in rotation
Once the second backend node answers GET /health with 200 again, it is back in rotation and the two share the requests again.

What to know​

  • Point the probe at a path every backend node answers with 200 while it is well. A probe answered with 404, as many APIs answer at the default /, counts as a failure. After as many failures in a row as HTTP failures says, the backend node is treated as stopped.
  • Without a health check, every backend node stays in rotation whatever its state. Clients are still answered, because a request a stopped backend node refuses is tried on the other, a GET and a POST alike.
  • Host passing at rewrite sends every backend node the name in Upstream host, also from a route that sets another host with proxy-rewrite. At pass, the default, the route's setting wins.
G8 dev