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 75c471bd9 docs: update control plane service discovery doc. (#7289)
75c471bd9 is described below
commit 75c471bd9380b959796a1eff32def9414edd5cd8
Author: feihan <[email protected]>
AuthorDate: Mon Jun 27 09:32:14 2022 +0800
docs: update control plane service discovery doc. (#7289)
---
.../images/control-plane-service-discovery.png | Bin 0 -> 94513 bytes
docs/en/latest/config.json | 2 +-
.../discovery/control-plane-service-discovery.md | 72 +++++++++++
docs/en/latest/discovery/zookeeper.md | 144 ---------------------
docs/zh/latest/config.json | 2 +-
.../discovery/control-plane-service-discovery.md | 72 +++++++++++
docs/zh/latest/discovery/zookeeper.md | 142 --------------------
7 files changed, 146 insertions(+), 288 deletions(-)
diff --git a/docs/assets/images/control-plane-service-discovery.png
b/docs/assets/images/control-plane-service-discovery.png
new file mode 100644
index 000000000..034f81c76
Binary files /dev/null and
b/docs/assets/images/control-plane-service-discovery.png differ
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 0e853b539..7fe61986b 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -221,7 +221,7 @@
"discovery/consul_kv",
"discovery/nacos",
"discovery/eureka",
- "discovery/zookeeper",
+ "discovery/control-plane-service-discovery",
"discovery/kubernetes"
]
},
diff --git a/docs/en/latest/discovery/control-plane-service-discovery.md
b/docs/en/latest/discovery/control-plane-service-discovery.md
new file mode 100644
index 000000000..a18bdc63d
--- /dev/null
+++ b/docs/en/latest/discovery/control-plane-service-discovery.md
@@ -0,0 +1,72 @@
+---
+title: Control Plane Service Discovery
+keywords:
+ - API Geteway
+ - APISIX
+ - ZooKeeper
+ - Nacos
+ - APISIX-Seed
+description: This documentation describes implement service discovery through
Nacos and ZooKeeper on the API Gateway APISIX Control Plane.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+This document describes how to implement service discovery with Nacos and
Zookeeper on the APISIX Control Plane.
+
+## APISIX-Seed Architecture
+
+Apache APISIX has supported Data Plane service discovery in the early days,
and now APISIX also supports Control Plane service discovery through the
[APISIX-Seed](https://github.com/api7/apisix-seed) project. The following
figure shows the APISIX-Seed architecture diagram.
+
+
+
+The specific information represented by the figures in the figure is as
follows:
+
+1. Register an upstream with APISIX and specify the service discovery type.
APISIX-Seed will watch APISIX resource changes in etcd, filter discovery types,
and obtain service names.
+2. APISIX-Seed subscribes the specified service name to the service registry
to obtain changes to the corresponding service.
+3. After the client registers the service with the service registry,
APISIX-Seed will obtain the new service information and write the updated
service node into etcd;
+4. When the corresponding resources in etcd change, APISIX worker will refresh
the latest service node information to memory.
+
+:::note
+
+It should be noted that after the introduction of APISIX-Seed, if the service
of the registry changes frequently, the data in etcd will also change
frequently. So, it is best to set the `--auto-compaction` option when starting
etcd to compress the history periodically to avoid etcd eventually exhaust its
storage space. Please refer to
[revisions](https://etcd.io/docs/v3.5/learning/api/#revisions).
+
+:::
+
+## Why APISIX-Seed
+
+- Network topology becomes simpler
+
+ APISIX does not need to maintain a network connection with each registry,
and only needs to pay attention to the configuration information in etcd. This
will greatly simplify the network topology.
+
+- Total data volume about upstream service becomes smaller
+
+ Due to the characteristics of the registry, APISIX may store the full amount
of registry service data in the worker, such as consul_kv. By introducing
APISIX-Seed, each process of APISIX will not need to additionally cache
upstream service-related information.
+
+- Easier to manage
+
+ Service discovery configuration needs to be configured once per APISIX
instance. By introducing APISIX-Seed, Apache APISIX will be in different to the
configuration changes of the service registry.
+
+## Supported service registry
+
+ZooKeeper and Nacos are currently supported, and more service registries will
be supported in the future. For more information, please refer to: [APISIX
Seed](https://github.com/api7/apisix-seed#apisix-seed-for-apache-apisix).
+
+- If you want to enable control plane ZooKeeper service discovery, please
refer to: [ZooKeeper Deployment
Tutorial](https://github.com/api7/apisix-seed/blob/main/docs/en/latest/zookeeper.md).
+
+- If you want to enable control plane Nacos service discovery, please refer
to: [Nacos Deployment
Tutorial](https://github.com/api7/apisix-seed/blob/main/docs/en/latest/zookeeper.md).
diff --git a/docs/en/latest/discovery/zookeeper.md
b/docs/en/latest/discovery/zookeeper.md
deleted file mode 100644
index 3adf52dc9..000000000
--- a/docs/en/latest/discovery/zookeeper.md
+++ /dev/null
@@ -1,144 +0,0 @@
----
-title: zookeeper
----
-
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-## Service Discovery Via Zookeeper
-
-`Zookeeper` service discovery needs to rely on the
[apisix-seed](https://github.com/api7/apisix-seed) project.
-
-### How `apisix-seed` Works
-
-
-
-`apisix-seed` completes data exchange by watching the changes of `etcd` and
`zookeeper` at the same time.
-
-The process is as follows:
-
-1. `APISIX` registers an upstream and specifies the service discovery type as
`zookeeper` to `etcd`.
-2. `apisix-seed` watches the resource changes of `APISIX` in `etcd` and
filters the discovery type and obtains the service name.
-3. `apisix-seed` binds the service to the `etcd` resource and starts watching
the service in zookeeper.
-4. The client registers the service with `zookeeper`.
-5. `apisix-seed` gets the service changes in `zookeeper`.
-6. `apisix-seed` queries the bound `etcd` resource information through the
service name, and writes the updated service node to `etcd`.
-7. The `APISIX` worker watches `etcd` changes and refreshes the service node
information to the memory.
-
-### Setting `apisix-seed` and Zookeeper
-
-The configuration steps are as follows:
-
-1. Start the Zookeeper service
-
-```bash
-docker run -itd --rm --name=dev-zookeeper -p 2181:2181 zookeeper:3.7.0
-```
-
-2. Download and compile the `apisix-seed` project.
-
-```bash
-git clone https://github.com/api7/apisix-seed.git
-cd apisix-seed
-go build
-```
-
-3. Modify the `apisix-seed` configuration file, config path `conf/conf.yaml`.
-
-```bash
-etcd: # APISIX ETCD Configure
- host:
- - "http://127.0.0.1:2379";
- prefix: /apisix
- timeout: 30
-
-discovery:
- zookeeper: # Zookeeper Service Discovery
- hosts:
- - "127.0.0.1:2181" # Zookeeper service address
- prefix: /zookeeper
- weight: 100 # default weight for node
- timeout: 10 # default 10s
-```
-
-4. Start `apisix-seed` to monitor service changes
-
-```bash
-./apisix-seed
-```
-
-### Setting `APISIX` Route and Upstream
-
-Set a route, the request path is `/zk/*`, the upstream uses zookeeper as
service discovery, and the service name
-is `APISIX-ZK`.
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uri": "/zk/*",
- "upstream": {
- "service_name": "APISIX-ZK",
- "type": "roundrobin",
- "discovery_type": "zookeeper"
- }
-}'
-```
-
-### Register Service and verify Request
-
-1. Service registration using Zookeeper CLI
-
-- Register Service
-
-```bash
-# Login Container
-docker exec -it ${CONTAINERID} /bin/bash
-# Login Zookeeper Client
-oot@ae2f093337c1:/apache-zookeeper-3.7.0-bin# ./bin/zkCli.sh
-# Register Service
-[zk: localhost:2181(CONNECTED) 0] create /zookeeper/APISIX-ZK
'{"host":"127.0.0.1:1980","weight":100}'
-```
-
-- Successful Response
-
-```bash
-Created /zookeeper/APISIX-ZK
-```
-
-2. Verify Request
-
-- Request
-
-```bash
-curl -i http://127.0.0.1:9080/zk/hello
-```
-
-- Response
-
-```bash
-HTTP/1.1 200 OK
-Connection: keep-alive
-Content-Type: text/html; charset=utf-8
-Date: Tue, 29 Mar 2022 08:51:28 GMT
-Server: APISIX/2.12.0
-Transfer-Encoding: chunked
-
-hello
-```
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 92b2967f3..1cb779f48 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -206,7 +206,7 @@
"discovery/dns",
"discovery/nacos",
"discovery/eureka",
- "discovery/zookeeper",
+ "discovery/control-plane-service-discovery",
"discovery/kubernetes"
]
},
diff --git a/docs/zh/latest/discovery/control-plane-service-discovery.md
b/docs/zh/latest/discovery/control-plane-service-discovery.md
new file mode 100644
index 000000000..b6bcb7450
--- /dev/null
+++ b/docs/zh/latest/discovery/control-plane-service-discovery.md
@@ -0,0 +1,72 @@
+---
+title: 控制面服务发现
+keywords:
+ - API 网关
+ - APISIX
+ - ZooKeeper
+ - Nacos
+ - APISIX-Seed
+description: 本文档介绍了如何在 API 网关 Apache APISIX 控制面通过 Nacos 和 Zookeeper 实现服务发现。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+本文档介绍了如何在 APISIX 控制面通过 Nacos 和 Zookeeper 实现服务发现。
+
+## APISIX-Seed 架构
+
+Apache APISIX 在早期已经支持了数据面服务发现，现在 APISIX 也通过
[APISIX-Seed](https://github.com/api7/apisix-seed) 项目实现了控制面服务发现，下图为 APISIX-Seed
架构图。
+
+
+
+图中的数字代表的具体信息如下：
+
+1. 通过 Admin API 向 APISIX 注册上游并指定服务发现类型。APISIX-Seed 将监听 etcd 中的 APISIX
资源变化，过滤服务发现类型并获取服务名称（如 ZooKeeper）；
+2. APISIX-Seed 将在服务注册中心（如 ZooKeeper）订阅指定的服务名称，以监控和更新对应的服务信息；
+3. 客户端向服务注册中心注册服务后，APISIX-Seed 会获取新的服务信息，并将更新后的服务节点写入 etcd；
+4. 当 APISIX-Seed 在 etcd 中更新相应的服务节点信息时，APISIX 会将最新的服务节点信息同步到内存中。
+
+:::note
+
+引入 APISIX-Seed 后，如果注册中心的服务变化频繁，etcd 中的数据也会频繁变化。因此，需要在启动 etcd 时设置
`--auto-compaction` 选项，用来定期压缩历史记录，避免耗尽 etcd 存储空间。详细信息请参考
[revisions](https://etcd.io/docs/v3.5/learning/api/#revisions)。
+
+:::
+
+## 为什么需要 APISIX-Seed？
+
+- 网络拓扑变得更简单
+
+ APISIX 不需要与每个注册中心保持网络连接，只需要关注 etcd 中的配置信息即可。这将大大简化网络拓扑。
+
+- 上游服务总数据量变小
+
+ 由于 `registry` 的特性，APISIX 可能会在 Worker 中存储全量的 `registry` 服务数据，例如
Consul_KV。通过引入 APISIX-Seed，APISIX 的每个进程将不需要额外缓存上游服务相关信息。
+
+- 更容易管理
+
+ 服务发现配置需要为每个 APISIX 实例配置一次。通过引入 APISIX-Seed，APISIX 将对服务注册中心的配置变化无感知。
+
+## 支持的服务发现类型
+
+目前已经支持了 ZooKeeper 和 Nacos，后续还将支持更多的服务注册中心，更多信息请参考：[APISIX
Seed](https://github.com/api7/apisix-seed#apisix-seed-for-apache-apisix)。
+
+- 如果你想启用控制面 ZooKeeper 服务发现，请参考：[ZooKeeper
部署教程](https://github.com/api7/apisix-seed/blob/main/docs/en/latest/zookeeper.md)。
+
+- 如果你想启用控制面 Nacos 服务发现，请参考：[Nacos
部署教程](https://github.com/api7/apisix-seed/blob/main/docs/en/latest/zookeeper.md)。
diff --git a/docs/zh/latest/discovery/zookeeper.md
b/docs/zh/latest/discovery/zookeeper.md
deleted file mode 100644
index db2bec301..000000000
--- a/docs/zh/latest/discovery/zookeeper.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-title: zookeeper
-keywords:
- - APISIX
- - ZooKeeper
- - apisix-seed
-description: 本篇文档介绍了如何使用 ZooKeeper 做服务发现
----
-
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-目前，如果你想在 APISIX 控制面使用 ZooKeeper 实现服务发现功能，需要依赖
[apisix-seed](https://github.com/api7/apisix-seed) 项目。
-
-## `apisix-seed` 工作原理
-
-
-
-`apisix-seed` 通过同时监听 etcd 和 ZooKeeper 的变化来完成数据交换。
-
-流程如下：
-
-1. 使用 APISIX 注册一个上游服务，并将服务类型设置为 `zookeeper` 并保存到 etcd；
-2. `apisix-seed` 监听 etcd 中 APISIX 的资源变更，并过滤服务发现类型获得服务名称；
-3. `apisix-seed` 将服务绑定到 etcd 资源，并开始在 ZooKeeper 中监控此服务；
-4. 客户端向 ZooKeeper 注册该服务；
-5. `apisix-seed` 获取 ZooKeeper 中的服务变更；
-6. `apisix-seed` 通过服务名称查询绑定的 etcd 资源，并将更新后的服务节点写入 etcd；
-7. APISIX Worker 监控 etcd 资源变更，并在内存中刷新服务节点信息。
-
-## 如何使用
-
-### 环境准备：配置 `apisix-seed` 和 ZooKeeper
-
-1. 启动 ZooKeeper
-
-```bash
-docker run -itd --rm --name=dev-zookeeper -p 2181:2181 zookeeper:3.7.0
-```
-
-2. 下载并编译 `apisix-seed` 项目
-
-```bash
-git clone https://github.com/api7/apisix-seed.git
-cd apisix-seed
-go build
-```
-
-3. 参考以下信息修改 `apisix-seed` 配置文件，路径为 `conf/conf.yaml`
-
-```bash
-etcd: # APISIX etcd 配置
- host:
- - "http://127.0.0.1:2379";
- prefix: /apisix
- timeout: 30
-
-discovery:
- zookeeper: # 配置 ZooKeeper 进行服务发现
- hosts:
- - "127.0.0.1:2181" # ZooKeeper 服务器地址
- prefix: /zookeeper
- weight: 100 # ZooKeeper 节点默认权重设为 100
- timeout: 10 # ZooKeeper 会话超时时间默认设为 10 秒
-```
-
-4. 启动 `apisix-seed` 以监听服务变更
-
-```bash
-./apisix-seed
-```
-
-### 设置 APISIX 路由和上游
-
-通过以下命令设置路由，请求路径设置为 `/zk/*`，上游使用 ZooKeeper 作为服务发现，服务名称为 `APISIX-ZK`。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uri": "/zk/*",
- "upstream": {
- "service_name": "APISIX-ZK",
- "type": "roundrobin",
- "discovery_type": "zookeeper"
- }
-}'
-```
-
-### 注册服务
-
-使用 ZooKeeper-cli 注册服务
-
-登录 ZooKeeper 容器，使用 CLI 程序进行服务注册。具体命令如下：
-
-```bash
-# 登陆容器
-docker exec -it ${CONTAINERID} /bin/bash
-# 登陆 ZooKeeper 客户端
-oot@ae2f093337c1:/apache-zookeeper-3.7.0-bin# ./bin/zkCli.sh
-# 注册服务
-[zk: localhost:2181(CONNECTED) 0] create /zookeeper/APISIX-ZK
'{"host":"127.0.0.1","port":1980,"weight":100}'
-```
-
-返回结果如下：
-
-```bash
-Created /zookeeper/APISIX-ZK
-```
-
-### 请求验证
-
-通过以下命令请求路由：
-
-```bash
-curl -i http://127.0.0.1:9080/zk/hello
-```
-
-正常返回结果：
-
-```bash
-HTTP/1.1 200 OK
-Connection: keep-alive
-...
-hello
-```
