Upstream

描述

Upstream(也称之为上游)是对虚拟主机抽象,即应用层服务或节点的抽象。你可以通过 Upstream 对象对多个服务节点按照配置规则进行负载均衡。

上游的地址信息可以直接配置到路由(或服务)中。

Upstream 示例

如上图所示,当多个路由(或服务)使用该上游时,你可以单独创建上游对象,在路由中通过使用 upstream_id 的方式引用资源,减轻维护压力。

你也可以将上游的信息直接配置在指定路由或服务中,不过路由中的配置优先级更高,优先级行为与插件 非常相似。

配置参数

APISIX 的 Upstream 对象除了基本的负载均衡算法外,还支持对上游做主被动健康检查、重试等逻辑。更多信息,请参考 Admin API 中的 Upstream 资源

Upstream - 图2note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量:

  1. admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
  1. 创建上游对象用例。

    1. curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
    2. -H "X-API-KEY: $admin_key" -X PUT -d '
    3. {
    4. "type": "chash",
    5. "key": "remote_addr",
    6. "nodes": {
    7. "127.0.0.1:80": 1,
    8. "httpbin.org:80": 2
    9. }
    10. }'

    上游对象创建后,可以被路由或服务引用。

  2. 在路由中使用创建的上游对象。

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H "X-API-KEY: $admin_key" -X PUT -d '
    3. {
    4. "uri": "/index.html",
    5. "upstream_id": 1
    6. }'
  3. 为方便使用,你也可以直接把上游信息直接配置在某个路由或服务。

以下示例是将上游信息直接配置在路由中:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H "X-API-KEY: $admin_key" -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. "upstream": {
  14. "type": "roundrobin",
  15. "nodes": {
  16. "127.0.0.1:1980": 1
  17. }
  18. }
  19. }'

使用示例

  • 配置健康检查的示例。

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H "X-API-KEY: $admin_key" -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. "upstream": {
    14. "nodes": {
    15. "127.0.0.1:1980": 1
    16. }
    17. "type": "roundrobin",
    18. "retries": 2,
    19. "checks": {
    20. "active": {
    21. "http_path": "/status",
    22. "host": "foo.com",
    23. "healthy": {
    24. "interval": 2,
    25. "successes": 1
    26. },
    27. "unhealthy": {
    28. "interval": 1,
    29. "http_failures": 2
    30. }
    31. }
    32. }
    33. }
    34. }'

    更多信息,请参考健康检查的文档

以下是使用不同 hash_on 类型的配置示例:

Consumer

  1. 创建一个 Consumer 对象。

    1. curl http://127.0.0.1:9180/apisix/admin/consumers \
    2. -H "X-API-KEY: $admin_key" -X PUT -d '
    3. {
    4. "username": "jack",
    5. "plugins": {
    6. "key-auth": {
    7. "key": "auth-jack"
    8. }
    9. }
    10. }'
  2. 创建路由,启用 key-auth 插件,配置 upstream.hash_on 的类型为 consumer

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H "X-API-KEY: $admin_key" -X PUT -d '
    3. {
    4. "plugins": {
    5. "key-auth": {}
    6. },
    7. "upstream": {
    8. "nodes": {
    9. "127.0.0.1:1980": 1,
    10. "127.0.0.1:1981": 1
    11. },
    12. "type": "chash",
    13. "hash_on": "consumer"
    14. },
    15. "uri": "/server_port"
    16. }'
  3. 测试请求,认证通过后的 consumer_name 将作为负载均衡哈希算法的哈希值。

    1. curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
  1. 创建路由并配置 upstream.hash_on 的类型为 cookie

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H "X-API-KEY: $admin_key" -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. }'
  2. 客户端请求携带 Cookie

    1. curl http://127.0.0.1:9080/hash_on_cookie \
    2. -H "X-API-KEY: $admin_key" \
    3. -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"

Header

  1. 创建路由并配置 upstream.hash_on 的类型为 headerkeycontent-type

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    2. -H "X-API-KEY: $admin_key" -X PUT -d '
    3. {
    4. "uri": "/hash_on_header",
    5. "upstream": {
    6. "key": "content-type",
    7. "type": "chash",
    8. "hash_on": "header",
    9. "nodes": {
    10. "127.0.0.1:1980": 1,
    11. "127.0.0.1:1981": 1
    12. }
    13. }
    14. }'
  2. 客户端请求携带 content-typeheader

  1. curl http://127.0.0.1:9080/hash_on_header \
  2. -H "X-API-KEY: $admin_key" \
  3. -H "Content-Type: application/json"