Skip to main content
Version: 3.2

Upstream

描述#

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

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

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

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

配置参数#

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

  1. 创建上游对象用例。

    curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "type": "chash",
    "key": "remote_addr",
    "nodes": {
    "127.0.0.1:80": 1,
    "httpbin.org:80": 2
    }
    }'

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

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

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

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

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
"limit-count": {
"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'
```

使用示例#

  • 配置健康检查的示例。

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "uri": "/index.html",
    "plugins": {
    "limit-count": {
    "count": 2,
    "time_window": 60,
    "rejected_code": 503,
    "key": "remote_addr"
    }
    },
    "upstream": {
    "nodes": {
    "127.0.0.1:1980": 1
    }
    "type": "roundrobin",
    "retries": 2,
    "checks": {
    "active": {
    "http_path": "/status",
    "host": "foo.com",
    "healthy": {
    "interval": 2,
    "successes": 1
    },
    "unhealthy": {
    "interval": 1,
    "http_failures": 2
    }
    }
    }
    }
    }'

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

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

Consumer#

  1. 创建一个 Consumer 对象。

    curl http://127.0.0.1:9180/apisix/admin/consumers \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "username": "jack",
    "plugins": {
    "key-auth": {
    "key": "auth-jack"
    }
    }
    }'
  2. 创建路由,启用 key-auth 插件,配置 upstream.hash_on 的类型为 consumer

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "plugins": {
    "key-auth": {}
    },
    "upstream": {
    "nodes": {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
    },
    "type": "chash",
    "hash_on": "consumer"
    },
    "uri": "/server_port"
    }'
  3. 测试请求,认证通过后的 consumer_name 将作为负载均衡哈希算法的哈希值。

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

Cookie#

  1. 创建路由并配置 upstream.hash_on 的类型为 cookie

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "uri": "/hash_on_cookie",
    "upstream": {
    "key": "sid",
    "type": "chash",
    "hash_on": "cookie",
    "nodes": {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
    }
    }
    }'
  2. 客户端请求携带 Cookie

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

Header#

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

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "uri": "/hash_on_header",
    "upstream": {
    "key": "content-type",
    "type": "chash",
    "hash_on": "header",
    "nodes": {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
    }
    }
    }'
  2. 客户端请求携带 content-typeheader

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