Set Up Intelligent Load Balancing

    If you are following the getting started workflow, make sure you have completed Secure Services Using Authentication before moving on.

    An Upstream Object refers to your upstream API/service sitting behind Kong Gateway, to which client requests are forwarded. In Kong Gateway, an Upstream Object represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple services (targets).

    In this topic, you’ll configure the service created earlier () to point to an upstream instead of the host. For the purposes of our example, the upstream will point to two different targets, httpbin.org and mockbin.org. In a real environment, the upstream will point to the same service running on multiple systems.

    Here is a diagram illustrating the setup:

    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.

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

    Using Kong Manager

    Using decK (YAML)

    1. Access your Kong Manager instance and your default workspace.
    2. Go to API Gateway > Upstreams.
    3. Click New Upstream.
    4. For this example, enter example_upstream in the Name field.
    5. Scroll down and click Create.
    6. On the Upstreams page, find the new upstream service and click View.
    7. Scroll down and click New Target.
    8. In the target field, specify httpbin.org with port 80, and click Create.
    9. Create another target, this time for mockbin.org with port 80. Click Create.
    10. Open the Services page.
    11. Find your example_service and click Edit.
    12. Change the Host field to upstream, then click Update.

    Call the Admin API on port 8001 and create an Upstream named example_upstream:

    cURL

    HTTPie

    1. http POST :8001/upstreams \
    2.   name=example_upstream

    Update the service you created previously to point to this upstream:

    cURL

    HTTPie

    1. curl -X PATCH http://<admin-hostname>:8001/services/example_service \
    2.   --data host='example_upstream'

    Add two targets to the upstream, each with port 80: mockbin.org:80 and httpbin.org:80:

    HTTPie

    1. curl -X POST http://<admin-hostname>:8001/upstreams/example_upstream/targets \
    2.   --data target='mockbin.org:80'
    4. curl -X POST http://<admin-hostname>:8001/upstreams/example_upstream/targets \
    1. http POST :8001/upstreams/example_upstream/targets \
    2.   target=mockbin.org:80
    3. http POST :8001/upstreams/example_upstream/targets \

    1. In your kong.yaml file, create an Upstream with two targets, each with port 80: mockbin.org:80 and httpbin.org:80.

    2. Update the service you created previously, pointing the host to this Upstream:

      1.  services:
      2.    host: example_upstream
      3.    name: example_service
      4.    port: 80
      5.    protocol: http

      After these updates, your file should now look like this:

      1.  _format_version: "1.1"
      2.  services:
      3.  - host: example_upstream
      4.    name: example_service
      5.    port: 80
      6.    protocol: http
      7.    routes:
      8.    - name: mocking
      9.      paths:
      10.      - /mock
      11.      strip_path: true
      12.      plugins:
      13.      - name: key-auth
      14.        enabled: false
      15.  - custom_id: consumer
      16.    username: consumer
      18.    - key: apikey
      19.  upstreams:
      20.  - name: example_upstream
      21.    targets:
      22.      - target: httpbin.org:80
      23.        weight: 100
      24.      - target: mockbin.org:80
      25.        weight: 100
      26.  plugins:
      27.  - name: rate-limiting
      28.    config:
      29.      minute: 5
      30.      policy: local
      31.  - name: proxy-cache
      32.    config:
      33.      content_type:
      34.      - "application/json; charset=utf-8"
      35.      cache_ttl: 30
      36.      strategy: memory

    3. Sync the configuration:

    You now have an Upstream with two targets, httpbin.org and mockbin.org, and a service pointing to that Upstream.

    1. With the Upstream configured, validate that it’s working by visiting the route http://<admin-hostname>:8000/mock using a web browser or CLI.
    2. Continue hitting the endpoint and the site should change from httpbin to mockbin.

    In this topic, you:

    • Added two targets, and mockbin.org, with equal weight to the Upstream.

    If you have a Kong Konnect subscription, go on to .