You are browsing unreleased documentation. See the latest documentation here.

Load Balancing

Load balancing is a method of distributing API request traffic across multiple upstream services. Load balancing improves overall system responsiveness and reduces failures by preventing overloading of individual resources.

In the following example, you’ll use an application deployed across two different servers, or upstream targets. Kong Gateway needs to load balance across both servers, so that if one of the servers is unavailable, it automatically detects the problem and routes all traffic to the working server.

An upstream refers to the service applications sitting behind Kong Gateway, to which client requests are forwarded. In Kong Gateway, an upstream represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple target backend services.

In this section, you’ll re-configure the service created earlier, (example_service) to point to an upstream instead of a specific host. For the purposes of our example, the upstream will point to two different targets, httpbin.konghq.com and httpbun.com. More commonly, targets will be instances of the same backend service running on different host systems.

Here is a diagram illustrating the setup:

 
flowchart LR
  A("`Route 
  (/mock)`")
  B("`Service
  (example_service)`")
  C(Load balancer)
  D(httpbin.konghq.com)
  E(httpbun.com)
  
  subgraph id1 ["`**KONG GATEWAY**`"]
    A --> B --> C
  end

  subgraph id2 ["`Targets (example_upstream)`"]
    C --> D & E
  end

  style id1 rx:10,ry:10
  style id2 stroke:none

Enable load balancing

In this section, you will create an upstream named example_upstream and add two targets to it.

Prerequisites

This chapter is part of the Get Started with Kong series. For the best experience, it is recommended that you follow the series from the beginning.

Start with the introduction, Get Kong, which includes a list of prerequisites and instructions for running a local Kong Gateway.

Step two of the guide, Services and Routes, includes instructions for installing a mock service used throughout this series.

If you haven’t completed these steps already, complete them before proceeding.

Steps to enable load balancing

Create an upstream

Use the Admin API to create an upstream named example_upstream:

curl -X POST http://localhost:8001/upstreams \
  --data name=example_upstream

Create upstream targets

Create two targets for example_upstream. Each request creates a new target, and sets the backend service connection endpoint:

curl -X POST http://localhost:8001/upstreams/example_upstream/targets \
  --data target='httpbun.com:80'
curl -X POST http://localhost:8001/upstreams/example_upstream/targets \
  --data target='httpbin.konghq.com:80'

Update the service

In the services and routes section of this guide, you created example_service which pointed to an explicit host, http://httpbun.com. Now you’ll modify that service to point to the upstream instead:
```
curl -X PATCH http://localhost:8001/services/example_service \
  --data host='example_upstream'
```
You now have an upstream with two targets, httpbin.konghq.com and httpbun.com, and a service pointing to that upstream.
Validate

Validate that the upstream you configured is working by visiting the route http://localhost:8000/mock using a web browser or CLI.
- Web browser: Visit http://localhost:8000/mock and refresh the page several times to see the site change from httpbin to httpbun.
- CLI: Execute the command curl -s http://localhost:8000/mock/headers |grep -i -A1 '"host"' several times. You will see the hostname change between httpbin and httpbun.

What’s next

You’ve completed the Get Started with Kong guide, but a lot more is possible with Kong Gateway. The following are guides to advanced features of Kong Gateway:

Previous Key Authentication