Skip to content

Commit f25602f

Browse files
dongjiang1989dongjiang1989
committed
add zookeeper discovery docs
Signed-off-by: dongjiang1989 <dongjiang1989@126.com>
1 parent ea3c33e commit f25602f

File tree

2 files changed

+368
-0
lines changed

2 files changed

+368
-0
lines changed

‎docs/en/latest/discovery/zookeeper.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Zookeeper
3+
keywords:
4+
- API Gateway
5+
- Apache APISIX
6+
- ZooKeeper
7+
- Service Discovery
8+
description: This documentation describes implementing service discovery through ZooKeeper on the API Gateway Apache APISIX.
9+
---
10+
11+
<!--
12+
#
13+
# Licensed to the Apache Software Foundation (ASF) under one or more
14+
# contributor license agreements. See the NOTICE file distributed with
15+
# this work for additional information regarding copyright ownership.
16+
# The ASF licenses this file to You under the Apache License, Version 2.0
17+
# (the "License"); you may not use this file except in compliance with
18+
# the License. You may obtain a copy of the License at
19+
#
20+
# http://www.apache.org/licenses/LICENSE-2.0
21+
#
22+
# Unless required by applicable law or agreed to in writing, software
23+
# distributed under the License is distributed on an "AS IS" BASIS,
24+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25+
# See the License for the specific language governing permissions and
26+
# limitations under the License.
27+
#
28+
-->
29+
30+
## Service Discovery via ZooKeeper
31+
32+
Apache APISIX supports integrating with ZooKeeper for service discovery. This allows APISIX to dynamically fetch service instance information from ZooKeeper and route requests accordingly.
33+
34+
## Configuration for ZooKeeper
35+
36+
To enable ZooKeeper service discovery, add the following configuration to `conf/config.yaml`:
37+
38+
```yaml
39+
discovery:
40+
zookeeper:
41+
connect_string: "127.0.0.1:2181,127.0.0.1:2182" # ZooKeeper Cluster Addresses (separated by commas for multiple addresses)
42+
fetch_interval: 10 # Interval (in seconds) for fetching service data. Default: 10s
43+
weight: 100 # Default weight for service instances. Default value is 100, and the value range is 1-500.
44+
cache_ttl: 30 # The time after which service instance cache becomes expired. Default: 60s
45+
connect_timeout: 2000 # Connect timeout (in ms). Default: 5000ms
46+
session_timeout: 30000 # Session Timeout (in ms). Default: 30000ms
47+
root_path: "/apisix/discovery/zk" # Root path for service registration in ZooKeeper, default: "/apisix/discovery/zk"
48+
auth: # ZooKeeper Authentication Information. Format requirement: "digest:{username}:{password}".
49+
type: "digest"
50+
creds: "username:password"
51+
```
52+
53+
And you can config it in short by default value:
54+
55+
```yaml
56+
discovery:
57+
zookeeper:
58+
connect_string: "127.0.0.1:2181"
59+
```
60+
61+
### Upstream setting
62+
63+
#### L7 (HTTP/HTTPS)
64+
65+
Here is an example of routing requests with the URI `/zookeeper/*` to a service named `APISIX-ZOOKEEPER` registered in ZooKeeper:
66+
67+
:::note
68+
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
69+
70+
```bash
71+
$ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
72+
```
73+
74+
:::
75+
76+
```shell
77+
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
78+
{
79+
"uri": "/zookeeper/*",
80+
"upstream": {
81+
"service_name": "APISIX-ZOOKEEPER",
82+
"type": "roundrobin",
83+
"discovery_type": "zookeeper"
84+
}
85+
}'
86+
```
87+
88+
The formatted response as below:
89+
90+
```json
91+
{
92+
"node": {
93+
"key": "/apisix/routes/1",
94+
"value": {
95+
"id": "1",
96+
"create_time": 1690000000,
97+
"status": 1,
98+
"update_time": 1690000000,
99+
"upstream": {
100+
"hash_on": "vars",
101+
"pass_host": "pass",
102+
"scheme": "http",
103+
"service_name": "APISIX-ZOOKEEPER",
104+
"type": "roundrobin",
105+
"discovery_type": "zookeeper"
106+
},
107+
"priority": 0,
108+
"uri": "/zookeeper/*"
109+
}
110+
}
111+
}
112+
```
113+
114+
#### L4 (TCP/UDP)
115+
116+
ZooKeeper service discovery also supports L4 proxy. Here's an example configuration for TCP:
117+
118+
```shell
119+
$ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
120+
{
121+
"remote_addr": "127.0.0.1",
122+
"upstream": {
123+
"scheme": "tcp",
124+
"discovery_type": "zookeeper",
125+
"service_name": "APISIX-ZOOKEEPER-TCP",
126+
"type": "roundrobin"
127+
}
128+
}'
129+
```
130+
131+
### discovery_args
132+
133+
| Name | Type | Required | Default | Valid | Description |
134+
| ------------ | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
135+
| root_path | string | optional | "/apisix/discovery/zk" | | Custom root path for the service in ZooKeeper |
136+
137+
#### Specify Root Path
138+
139+
Example of routing to a service under a custom root path:
140+
141+
```shell
142+
$ curl http://127.0.0.1:9180/apisix/admin/routes/2 -H "X-API-KEY: $admin_key" -X PUT -i -d '
143+
{
144+
"uri": "/zookeeper/custom/*",
145+
"upstream": {
146+
"service_name": "APISIX-ZOOKEEPER",
147+
"type": "roundrobin",
148+
"discovery_type": "zookeeper",
149+
"discovery_args": {
150+
"root_path": "/custom/services"
151+
}
152+
}
153+
}'
154+
155+
```
156+
157+
The formatted response as below:
158+
159+
```json
160+
{
161+
"node": {
162+
"key": "/apisix/routes/2",
163+
"value": {
164+
"id": "2",
165+
"create_time": 1615796097,
166+
"status": 1,
167+
"update_time": 1615799165,
168+
"upstream": {
169+
"hash_on": "vars",
170+
"pass_host": "pass",
171+
"scheme": "http",
172+
"service_name": "APISIX-ZOOKEEPER",
173+
"type": "roundrobin",
174+
"discovery_type": "zookeeper",
175+
"discovery_args": {
176+
"root_path": "/custom/services"
177+
}
178+
},
179+
"priority": 0,
180+
"uri": "/zookeeper/*"
181+
}
182+
}
183+
}
184+
```

‎docs/zh/latest/discovery/zookeeper.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Zookeeper
3+
keywords:
4+
- API 网关
5+
- Apache APISIX
6+
- ZooKeeper
7+
- 服务发现
8+
description: 本文档介绍了如何在 API 网关 Apache APISIX 上通过 ZooKeeper 实现服务发现。
9+
---
10+
11+
<!--
12+
#
13+
# Licensed to the Apache Software Foundation (ASF) under one or more
14+
# contributor license agreements. See the NOTICE file distributed with
15+
# this work for additional information regarding copyright ownership.
16+
# The ASF licenses this file to You under the Apache License, Version 2.0
17+
# (the "License"); you may not use this file except in compliance with
18+
# the License. You may obtain a copy of the License at
19+
#
20+
# http://www.apache.org/licenses/LICENSE-2.0
21+
#
22+
# Unless required by applicable law or agreed to in writing, software
23+
# distributed under the License is distributed on an "AS IS" BASIS,
24+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25+
# See the License for the specific language governing permissions and
26+
# limitations under the License.
27+
#
28+
-->
29+
30+
## 通过 ZooKeeper 实现服务发现
31+
32+
Apache APISIX 支持与 ZooKeeper 集成以实现服务发现。这使得 APISIX 能够从 ZooKeeper 动态获取服务实例信息，并据此进行请求路由。
33+
34+
## ZooKeeper 配置
35+
36+
要启用 ZooKeeper 服务发现，请在 `conf/config.yaml` 中添加以下配置：
37+
38+
```yaml
39+
discovery:
40+
zookeeper:
41+
connect_string: "127.0.0.1:2181,127.0.0.1:2182" # ZooKeeper 集群地址（多个地址用逗号分隔）
42+
fetch_interval: 10 # 获取服务数据的间隔时间（秒）。默认值：10s
43+
weight: 100 # 服务实例的默认权重。默认值为 100，取值范围是 1-500。
44+
cache_ttl: 30 # 服务实例缓存过期时间。默认值：60s
45+
connect_timeout: 2000 # 连接超时时间（毫秒）。默认值：5000ms
46+
session_timeout: 30000 # 会话超时时间（毫秒）。默认值：30000ms
47+
root_path: "/apisix/discovery/zk" # ZooKeeper 中服务注册的根路径，默认值："/apisix/discovery/zk"
48+
auth: # ZooKeeper 认证信息。格式要求："digest:{username}:{password}"。
49+
type: "digest"
50+
creds: "username:password"
51+
```
52+
53+
您也可以使用默认值进行简化配置：
54+
55+
```yaml
56+
discovery:
57+
zookeeper:
58+
connect_string: "127.0.0.1:2181"
59+
```
60+
61+
### 上游设置
62+
63+
#### L7（HTTP/HTTPS）
64+
65+
以下示例将 URI 为 `/zookeeper/*` 的请求路由到在 ZooKeeper 中注册的名为 `APISIX-ZOOKEEPER` 的服务：
66+
67+
:::note
68+
69+
您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
70+
71+
```bash
72+
$ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
73+
```
74+
75+
:::
76+
77+
```shell
78+
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
79+
{
80+
"uri": "/zookeeper/*",
81+
"upstream": {
82+
"service_name": "APISIX-ZOOKEEPER",
83+
"type": "roundrobin",
84+
"discovery_type": "zookeeper"
85+
}
86+
}'
87+
```
88+
89+
格式化后的响应如下：
90+
91+
```json
92+
{
93+
"node": {
94+
"key": "/apisix/routes/1",
95+
"value": {
96+
"id": "1",
97+
"create_time": 1690000000,
98+
"status": 1,
99+
"update_time": 1690000000,
100+
"upstream": {
101+
"hash_on": "vars",
102+
"pass_host": "pass",
103+
"scheme": "http",
104+
"service_name": "APISIX-ZOOKEEPER",
105+
"type": "roundrobin",
106+
"discovery_type": "zookeeper"
107+
},
108+
"priority": 0,
109+
"uri": "/zookeeper/*"
110+
}
111+
}
112+
}
113+
```
114+
115+
#### 四层（TCP/UDP）
116+
117+
ZooKeeper 服务发现也支持 L4 代理。以下是 TCP 的配置示例：
118+
119+
```shell
120+
$ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_key" -X PUT -i -d '
121+
{
122+
"remote_addr": "127.0.0.1",
123+
"upstream": {
124+
"scheme": "tcp",
125+
"discovery_type": "zookeeper",
126+
"service_name": "APISIX-ZOOKEEPER-TCP",
127+
"type": "roundrobin"
128+
}
129+
}'
130+
```
131+
132+
### 参数
133+
134+
| 名字 | 类型 | 可选项 | 默认值 | 有效值 | 说明 |
135+
| ------------ | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
136+
| root_path | string | 可选 | "/apisix/discovery/zk" | | ZooKeeper 中服务的自定义根路径 |
137+
138+
#### 指定根路径
139+
140+
路由到自定义根路径下服务的示例：
141+
142+
```shell
143+
$ curl http://127.0.0.1:9180/apisix/admin/routes/2 -H "X-API-KEY: $admin_key" -X PUT -i -d '
144+
{
145+
"uri": "/zookeeper/custom/*",
146+
"upstream": {
147+
"service_name": "APISIX-ZOOKEEPER",
148+
"type": "roundrobin",
149+
"discovery_type": "zookeeper",
150+
"discovery_args": {
151+
"root_path": "/custom/services"
152+
}
153+
}
154+
}'
155+
```
156+
157+
格式化后的响应如下：
158+
159+
```json
160+
{
161+
"node": {
162+
"key": "/apisix/routes/2",
163+
"value": {
164+
"id": "2",
165+
"create_time": 1615796097,
166+
"status": 1,
167+
"update_time": 1615799165,
168+
"upstream": {
169+
"hash_on": "vars",
170+
"pass_host": "pass",
171+
"scheme": "http",
172+
"service_name": "APISIX-ZOOKEEPER",
173+
"type": "roundrobin",
174+
"discovery_type": "zookeeper",
175+
"discovery_args": {
176+
"root_path": "/custom/services"
177+
}
178+
},
179+
"priority": 0,
180+
"uri": "/zookeeper/*"
181+
}
182+
}
183+
}
184+
```

0 commit comments

Comments
 (0)