## 11\. Upstreams
*地址*：/upstreams
*说明*：Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到`Route`（或`Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。
### 11.1 请求方法
| NAME | 请求URI | 请求body | 说明 |
| --- | --- | --- | --- |
| POST | /upstreams | {...} | 新增upstreams |
| GET | /upstreams | | 查询upstreams列表 |
| GET | /upstreams/{name or id} | | 查询单个upstream |
| GET | /targets/{target host:port or id}/upstream | | 同上 |
| PATCH | /upstreams/{name or id} | {...} | 更新upstream |
| ~ | /targets/{target host:port or id}/upstream | {...} | 同上 |
| PUT | /upstreams/{name or id} | | 新增/更新upstream |
| ~ | /targets/{target host:port or id}/upstream | | 同上 |
| DELETE | /upstreams/{name or id} | | 删除upstream |
| ~ | /targets/{target host:port or id}/upstream | | 同上 |
| GET | /upstreams/{name or id}/health | | 获取upstream健康状态 |
### 11.2 body 请求参数
| 参数名 | 可选 | 默认值 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| name | 可选 | | 标识upsream名称 | examples.v1.upstream |
| hash\_on | 可选 | none | | |
| hash\_fallback | 可选 | | One of:`none`,`consumer`,`ip`,`header`, or`cookie` | |
| hash\_on\_header | 可选 | | The header name to take the value from as hash input. Only required when`hash_on`is set to`header`. | |
| hash\_fallback\_header | 可选 | | The header name to take the value from as hash input. Only required when`hash_fallback`is set to`header`. | |
| hash\_on\_cookie | 可选 | | The cookie name to take the value from as hash input. Only required when`hash_on`or`hash_fallback`is set to`cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response. | |
| hash\_on\_cookie\_path | 可选 | / | The cookie path to set in the response headers. Only required when`hash_on`or`hash_fallback`is set to`cookie`. Defaults to`"/"`. | |
| slots | 可选 | 10000 | `10`\-`65536` | |
| healthchecks | 参见active和passive | | | |
| tags | 可选 | | 标签 | |
healthchecks(ACTIVE)
| https\_verify\_certificate | 可选 | true | | |
| --- | --- | --- | --- | --- |
| unhealthy.http\_statuses | 可选 | \[429, 404, 500, 501, 502, 503, 504, 505\] | 非健康的http状态码 | |
| unhealthy.tcp\_failures | 可选 | 0 | 非健康tcp失败次数 | |
| unhealthy.timeouts | 可选 | 0 | 超时次数，超过该值就设置为unhealthy | |
| unhealthy.http\_failures | 可选 | 0 | http访问失败次数,超过该值设置为unhealthy，为0不探测 | |
| unhealthy.interval | 可选 | 0 | 为0 不探测，两次探测非健康检查的间隔时长 | |
| http\_path | 可选 | / | 健康检查的访问路径 | |
| timeout | 可选 | 1 | socket超时时长 | |
| healthy.http\_statuses | 可选 | \[200, 302\] | http状态为设置值其中 个，则对成功指标进行+1 | |
| healthy.interval | 可选 | 0 | 两次健康检查探测的间隔时长（单位为秒） | |
| healthy.successes | 可选 | 0 | 健康的成功计数指标 | |
| https\_sni | 可选 | | | |
| concurrency | 可选 | 10 | 并发数 | |
| type | 可选 | http | `tcp`,`http`or`https` | |
healthchecks(passive)
| unhealthy.http\_failures | 可选 | 0 | 代理流量中的HTTP失败数（由定义健康检查。被动。不健康.http\_status）将目标视为不健康，如被动运行状况检查所观察到的 | 1 |
| --- | --- | --- | --- | --- |
| unhealthy.http\_statuses | 可选 | \[429, 500, 503\] | 访问http的状态码为其中之一的 | \[429,500,503\] |
| unhealthy.tcp\_failures | 可选 | 0 | 被动运行状况检查观察到的被代理流量中认为目标不正常的TCP故障数 | 1 |
| unhealthy.timeouts | 可选 | 0 | 被动运行状况检查所观察到的代理流量中认为目标不正常的超时数 | 1 |
| type | 可选 | http | `tcp`,`http`or`https` | http |
| healthy.successes | 可选 | 0 | 成功的次数 | 0 |
| healthy.http\_statuses | 可选 | \[200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308\] | http成功的状态 | |
### 11.3 数据样例
body请求参数
```
{
"id": "91020192-062d-416f-a275-9addeeaffaf2",
"created_at": 1422386534,
"name": "my-upstream",
"hash_on": "none",
"hash_fallback": "none",
"hash_on_cookie_path": "/",
"slots": 10000,
"healthchecks": {
"active": {
"https_verify_certificate": true,
"unhealthy": {
"http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
"tcp_failures": 0,
"timeouts": 0,
"http_failures": 0,
"interval": 0
},
"http_path": "/",
"timeout": 1,
"healthy": {
"http_statuses": [200, 302],
"interval": 0,
"successes": 0
},
"https_sni": "example.com",
"concurrency": 10,
"type": "http"
},
"passive": {
"unhealthy": {
"http_failures": 0,
"http_statuses": [429, 500, 503],
"tcp_failures": 0,
"timeouts": 0
},
"type": "http",
"healthy": {
"successes": 0,
"http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
}
}
},
"tags": ["user-level", "low-priority"]
}
```
upstream列表
```
{
"data": [{
"id": "a2e013e8-7623-4494-a347-6d29108ff68b",
"created_at": 1422386534,
"name": "my-upstream",
"hash_on": "none",
"hash_fallback": "none",
"hash_on_cookie_path": "/",
"slots": 10000,
"healthchecks": {
"active": {
"https_verify_certificate": true,
"unhealthy": {
"http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
"tcp_failures": 0,
"timeouts": 0,
"http_failures": 0,
"interval": 0
},
"http_path": "/",
"timeout": 1,
"healthy": {
"http_statuses": [200, 302],
"interval": 0,
"successes": 0
},
"https_sni": "example.com",
"concurrency": 10,
"type": "http"
},
"passive": {
"unhealthy": {
"http_failures": 0,
"http_statuses": [429, 500, 503],
"tcp_failures": 0,
"timeouts": 0
},
"type": "http",
"healthy": {
"successes": 0,
"http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
}
}
},
"tags": ["user-level", "low-priority"]
}, {
"id": "147f5ef0-1ed6-4711-b77f-489262f8bff7",
"created_at": 1422386534,
"name": "my-upstream",
"hash_on": "none",
"hash_fallback": "none",
"hash_on_cookie_path": "/",
"slots": 10000,
"healthchecks": {
"active": {
"https_verify_certificate": true,
"unhealthy": {
"http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
"tcp_failures": 0,
"timeouts": 0,
"http_failures": 0,
"interval": 0
},
"http_path": "/",
"timeout": 1,
"healthy": {
"http_statuses": [200, 302],
"interval": 0,
"successes": 0
},
"https_sni": "example.com",
"concurrency": 10,
"type": "http"
},
"passive": {
"unhealthy": {
"http_failures": 0,
"http_statuses": [429, 500, 503],
"tcp_failures": 0,
"timeouts": 0
},
"type": "http",
"healthy": {
"successes": 0,
"http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
}
}
},
"tags": ["admin", "high-priority", "critical"]
}],
"next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}
```
- 1. 概述
- 2. 快速安装
- 2.1 环境准备
- 2.2 开始安装
- 2.3 启动/关闭kongx
- 2.4 使用kongx
- 3. 使用指南
- 3.0 mockbin配置示例
- 3.0.1 不含upstream的配置
- 3.0.2 含upstream的配置
- 3.1 Gateway
- 3.1.1 Upstreams
- 3.1.1.1 新增/修改upstreams
- 3.1.1.2 管理targets
- 3.1.1.3 设置健康检查
- 3.1.1.4 upstream视图
- 3.1.2 Services
- 3.1.2.1 新建/修改service
- 3.1.2.2 添加服务路由
- 3.1.2.3 添加服务插件
- 3.1.2.4 同步services
- 3.1.2.5 services视图
- 3.1.3 Routes
- 3.1.3.1 路由列表
- 3.1.3.2 修改路由
- 3.1.3.3 批量修改HOSTS
- 3.1.4 Plugins
- 3.1.4.1 新增插件
- 3.1.4.2 插件列表
- 3.1.5 Consumers
- 3.1.5.1 新建/修改consumers
- 3.1.6 Kong Shell
- 3.1.6.1 shell安装
- 3.1.6.2 使用Shell
- 3.2 系统管理
- 3.2.1 用户管理
- 3.2.2 角色管理
- 3.2.3 用户组管理
- 3.2.4 菜单管理
- 3.3 参数管理
- 3.3.1 环境管理
- 3.3.2 系统参数
- 3.3.3 如何增加多个环境?
- 3.4 日志管理
- 3.4.1 操作日志
- 3.4.2 同步日志
- 3.5 工具箱
- 3.5.1 Kong Shell
- 3.5.2 切换工作台
- 3.6 网关流水线
- 3.6.1 Pipeline
- 4. 最佳实践
- 4.1 灰度插件canary使用
- 4.2 kong与consul集成
- 4.2.1 使用kong提供dns服务
- 4.2.2 使用dnsmasq提供dns服务
- 4.2.3 使用consul自主发现服务
- 4.3 kong健康检查
- 4.3.1 简介
- 4.3.2 健康检查(主动检查)
- 4.3.3 断路器(被动检查)
- 4.3.4 总结
- 4.4 认证插件之key-auth
- 4.5 认证插件之basic-auth
- 4.6 认证插件之oauth2-auth
- 4.7 认证插件之jwt
- 4.8 kong自定义access_log格式
- 4.8.1 前言
- 4.8.2 配置文本格式
- 4.8.3 配置JSON格式
- 4.9 kong的访问监控
- 4.9.1 解决方案
- 4.9.2 方案实施
- 4.9.3 接入grafana报表
- 5. 常见问题
- 5.1 默认账号及密码
- 5.2 新增用户默认密码为123456
- 5.3 如何设置超级管理员
- 5.4 密码忘记了咋办
- 6. Kong
- 6.1 Kong简介
- 6.2 kong安装指南
- 6.2.1 kong安装-RPM
- 6.2.2 kong安装-源码
- 6.2.3 kong基于yum源安装
- 6.3 Admin API
- 6.3.1 API支持两种内容类型
- 6.3.2 声明式配置(Declarative Configuration)
- 6.3.3 获取实体schema
- 6.3.4 services
- 6.3.5 Routes
- 6.3.6 Consumers
- 6.3.7 Plugins
- 6.3.8 Certficate
- 6.3.9 CA certficate(1.3.x+以上版本)
- 6.3.10 SNI
- 6.3.11 Upstreams
- 6.3.12 Targets
- 6.4 Kong使用
- 6.4.1 DB-LESS模式
- 6.4.2 DB模式