Upstream

    Although Upstream can be directly configured to the or Service, using an Upstream object is recommended when there is duplication as shown below.

    By creating an Upstream object and referencing it by in the Route, you can ensure that there is only a single value of the object that needs to be maintained.

    An Upstream configuration can be directly bound to a Route or a Service, but the configuration in Route has a higher priority. This behavior is consistent with priority followed by the object.

    In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. You can learn more about this .

    After creating an Upstream object, it can be referenced by a specific Route or Service as shown below.

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    3. {
    4.     "uri": "/index.html",
    5.     "upstream_id": 1
    6. }'

    For convenience, you can directly bind the upstream address to a Route or Service.

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    3. {
    4.     "uri": "/index.html",
    5.     "plugins": {
    6.         "limit-count": {
    7.             "count": 2,
    8.             "time_window": 60,
    9.             "rejected_code": 503,
    10.             "key": "remote_addr"
    11.         }
    12.     },
    13.         "type": "roundrobin",
    14.         "nodes": {
    15.             "127.0.0.1:1980": 1
    16.         }
    17.     }

    The example below shows how you can configure a health check.

    You can learn more about health checks .

    The examples below show configurations that use different hash_on types.

    1. curl http://127.0.0.1:9180/apisix/admin/consumers \
    2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    3. {
    4.     "username": "jack",
    5.     "plugins": {
    6.        "key-auth": {
    7.             "key": "auth-jack"
    8.         }
    9.     }
    10. }'

    Creating a Route object and enabling the key-auth authentication Plugin.

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    3. {
    4.     "plugins": {
    5.         "key-auth": {}
    6.     },
    7.     "upstream": {
    8.         "nodes": {
    9.             "127.0.0.1:1981": 1
    10.         },
    11.         "type": "chash",
    13.     },
    14.     "uri": "/server_port"
    15. }'

    To test the request, the consumer_name passed for authentication will be used as the hash value of the load balancing hash algorithm.

    Creating a Route and an upstream object.

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    3. {
    4.     "uri": "/hash_on_cookie",
    5.     "upstream": {
    6.         "key": "sid",
    7.         "type": "chash",
    8.         "hash_on": "cookie",
    9.         "nodes": {
    10.             "127.0.0.1:1980": 1,
    11.             "127.0.0.1:1981": 1
    12.         }
    13.     }
    14. }'

    The client can then send a request with a cookie.

    1.  curl http://127.0.0.1:9080/hash_on_cookie \
    2.  -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"

    Creating a Route and an upstream object.

    1.  curl http://127.0.0.1:9080/hash_on_header \
    2.  -H "Content-Type: application/json"