Upstream

Upstream 是虚拟主机抽象,对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 Route(或 Service) 上,当 Upstream 有重复时,就需要用“引用”方式避免重复了。

Upstream 示例

如上图所示,通过创建 Upstream 对象,在 Route 用 ID 方式引用,就可以确保只维护一个对象的值了。

Upstream 的配置可以被直接绑定在指定 Route 中,也可以被绑定在 Service 中,不过 Route 中的配置优先级更高。这里的优先级行为与 Plugin 非常相似。

配置参数

APISIX 的 Upstream 除了基本的负载均衡算法选择外,还支持对上游做主被动健康检查、重试等逻辑,具体看这个 链接

创建上游对象用例:

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

上游对象创建后,均可以被具体 RouteService 引用,例如:

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

为了方便使用,也可以直接把上游地址直接绑到某个 RouteService ,例如:

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

下面是一个配置了健康检查的示例:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/index.html",
  4. "plugins": {
  5. "limit-count": {
  6. "count": 2,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr"
  10. }
  11. },
  12. "upstream": {
  13. "nodes": {
  14. "127.0.0.1:1980": 1
  15. }
  16. "type": "roundrobin",
  17. "retries": 2,
  18. "checks": {
  19. "active": {
  20. "http_path": "/status",
  21. "host": "foo.com",
  22. "healthy": {
  23. "interval": 2,
  24. "successes": 1
  25. },
  26. "unhealthy": {
  27. "interval": 1,
  28. "http_failures": 2
  29. }
  30. }
  31. }
  32. }
  33. }'

更多细节可以参考 健康检查的文档

下面是几个使用不同 hash_on 类型的配置示例:

Consumer

创建一个 consumer 对象:

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

新建路由,打开 key-auth 插件认证,upstreamhash_on 类型为 consumer

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

测试请求,认证通过后的 consumer_name 将作为负载均衡哈希算法的哈希值:

  1. curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"

新建路由和 Upstreamhash_on 类型为 cookie

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

客户端请求携带 Cookie

  1. curl http://127.0.0.1:9080/hash_on_cookie -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
Header

新建路由和 Upstreamhash_on 类型为 headerkeycontent-type

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

客户端请求携带 content-typeheader

  1. curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"