This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 25301d6 docs: admin-api.md document adds configuration https example
(#3871)
25301d6 is described below
commit 25301d60dfa57f14a4dfed295c8cc7d104e37e38
Author: Yuelin Zheng <2226815...@qq.com>
AuthorDate: Sat Apr 3 16:13:54 2021 +0800
docs: admin-api.md document adds configuration https example (#3871)
---
docs/en/latest/admin-api.md | 54 +++++++++++++++++++++++++++++++++++++++----
docs/zh/latest/admin-api.md | 56 ++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 99 insertions(+), 11 deletions(-)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index 89ec8dc..8878817 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -560,7 +560,7 @@ In addition to the basic complex equalization algorithm
selection, APISIX's Upst
1. when it is `vars_combinations`, the `key` is required. The `key` can be any
[Nginx builtin variables](http://nginx.org/en/docs/varindex.html) combinations,
such as `$request_uri$remote_addr`.
1. If there is no value for either `hash_on` or `key`, `remote_addr` will be
used as key.
-Config Example:
+**Config Example:**
```shell
{
@@ -579,12 +579,16 @@ Config Example:
"key": "",
"name": "upstream-for-test",
"desc": "hello world",
+ "scheme": "http", # The scheme used when communicating with
upstream, the default is `http`
}
```
-Example：
+**Example:**
+
+Example 1: Create an upstream and modify the data of `nodes`
```shell
+# Create upstream
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
"type":"roundrobin",
@@ -595,8 +599,6 @@ $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H
'X-API-KEY: edd1c9f0
}
}'
HTTP/1.1 201 Created
-Date: Thu, 26 Dec 2019 04:19:34 GMT
-Content-Type: text/plain
...
@@ -665,12 +667,54 @@ After the execution is successful, nodes will not retain
the original data, and
```
+Example 2: How to proxy client request to `https` upstream service
+
+1. Create a route and configure the upstream scheme as `https`.
+
+```shell
+$ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "nodes": {
+ "httpbin.org:443": 1
+ }
+ }
+}'
+```
+
+After the execution is successful, the scheme when requesting to communicate
with the upstream will be `https`.
+
+2. Send a request for testing.
+
+```shell
+$ curl http://127.0.0.1:9080/get
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1",
+ "url": "https://127.0.0.1/get";
+}
+```
+
+The request is successful, which means that the proxy upstream `https` is
valid.
+
+**Note:**
+
Each node can be configured with a priority. A node with low priority will
only be
used when all the nodes with higher priority are unavailable or tried.
As the default priority is 0, we can configure nodes with negative priority as
the backup.
-For example,
+For example:
```json
{
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index f488452..452b0f7 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -562,7 +562,7 @@ APISIX 的 Upstream 除了基本的复杂均衡算法选择外，还支持对上
4. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。
5. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。
-upstream 对象 json 配置内容：
+**upstream 对象 json 配置内容：**
```shell
{
@@ -579,15 +579,18 @@ upstream 对象 json 配置内容：
"checks": {}, # 配置健康检查的参数
"hash_on": "",
"key": "",
- "name": "upstream-xxx", # upstream 名称
+ "name": "upstream-xxx", # upstream 名称
"desc": "hello world", # upstream 描述
+ "scheme": "http" # 跟上游通信时使用的 scheme，默认是 `http`
}
```
-具体示例：
+**具体示例：**
+
+示例一：创建一个 upstream 并对 `nodes` 的数据做修改
```shell
-# 创建一个upstream
+# 创建一个 upstream
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
"type":"roundrobin",
@@ -666,11 +669,52 @@ HTTP/1.1 200 OK
```
+示例二：将客户端请求代理到上游 `https` 服务
+
+1、创建 route 并配置 upstream 的 scheme 为 `https`。
+
+```shell
+$ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "nodes": {
+ "httpbin.org:443": 1
+ }
+ }
+}'
+```
+
+执行成功后，请求与上游通信时的 scheme 将为 `https`。
+
+2、 发送请求进行测试。
+
+```shell
+$ curl http://127.0.0.1:9080/get
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1",
+ "url": "https://127.0.0.1/get";
+}
+```
+
+请求成功，表示代理上游 `https` 生效了。
+
+**注意：**
+
节点可以配置自己的优先级。只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。
由于默认的优先级是 0，我们可以给一些节点配置负数的优先级来作为备份。
-
-举个例子，
+举个例子:
```json
{
