Skip to content

Commit 0b4ff22

Browse files
Han-Ya-JunHan-Ya-Jun
authored
feat: apigw manager add plugin use guide (TencentBlueKing#155)
1 parent de12dce commit 0b4ff22

8 files changed

Lines changed: 213 additions & 16 deletions

File tree

‎sdks/apigw-manager/README.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,8 @@ support-files
6969
```
7070

7171
definition.yaml 中可以使用 Django 模版语法引用和渲染变量，内置以下变量：
72-
- `settings`：Django 提供的配置对象,优先适合用于使用 Django Command 同步
73-
- `environ`：环境变量,推荐镜像同步方式使用
72+
- `settings`：Django 提供的配置对象，优先适合用于使用 Django Command 同步
73+
- `environ`：环境变量，推荐镜像同步方式使用
7474

7575
推荐在一个文件中统一进行定义，用命名空间区分不同配置间的定义，definition.yaml 样例：
7676

@@ -127,11 +127,28 @@ stage:
127127
# 网关调用后端服务的默认域名或IP，不包含Path，比如：http://api.example.com
128128
- host: ""
129129
weight: 100
130-
# Header转换；如未使用，可去除此配置
131-
# transform_headers:
132-
# # 设置Headers
133-
# set:
134-
# X-Token: "token"
130+
# 环境插件配置
131+
# pluginConfigs:
132+
# - type: bk-rate-limit
133+
# yaml: |-
134+
# rates:
135+
# __default:
136+
# - period: 1
137+
# tokens: 100
138+
# - type: bk-header-rewrite
139+
# yaml: |-
140+
# set:
141+
# - key: test
142+
# value: '2'
143+
# remove: []
144+
# - type: bk-cors
145+
# yaml: |-
146+
# allow_origins: '*'
147+
# allow_methods: '*'
148+
# allow_headers: '*'
149+
# expose_headers: '*'
150+
# max_age: 86400
151+
# allow_credential: false
135152

136153

137154
# 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
@@ -191,15 +208,17 @@ resource_docs:
191208
```
192209
193210
**注意：**
194-
- 同步资源后，需要创建版本并发布才能生效，发布数据定义于 definition.yaml `release`
211+
- 同步资源或者环境相关配置后，需要创建版本并发布才能生效，发布数据定义于 definition.yaml `release`
195212
- 资源配置 resources.yaml 变更时，需要更新 definition.yaml `release` 中的版本号 version，以便正确创建资源版本及 SDK
196-
213+
- 详细的插件配置见：[插件配置说明](docs/plugin-use-guide.md)
197214
#### 2. resources.yaml
198215

199216
用于定义资源配置，建议通过网关管理端导出。为了方便用户直接使用网关导出的资源文件，资源定义默认没有命名空间。
200217

201218
样例可参考：[resources.yaml](examples/django/use-custom-script/support-files/resources.yaml)
202219

220+
> 详细的插件配置见：[插件配置说明](docs/plugin-use-guide.md)
221+
203222
#### 3. apidocs（可选）
204223

205224
资源文档，资源文档为 markdown 格式。资源文档的文件名，应为 `资源名称` + `.md` 格式，假如资源名称为 get_user，则文档文件名应为 get_user.md。
@@ -447,8 +466,12 @@ APIGW_MANAGER_DUMMY_PAYLOAD_USERNAME # JWT payload 中的 username
447466
这种大概率是自定义脚本有问题，参照文档，按照对应目录下的 examples 的同步脚本即可。
448467
449468
### 2.执行同步命令时报错：`Error responded by API Gateway, status_code:_code: 404, request_id:, error_code: 1640401, API not found`
450-
这种大概率是网关URL `BK_API_URL_TMPL` 漏配或者配错了。eg: BK_API_URL_TMPL: http://bkapi.example.com/api/{api_name}"l, 注意 {api_name}是占位符需要保留
469+
网关URL `BK_API_URL_TMPL` 漏配或者配错了(自定义脚本中存在错误)。举例说明: BK_API_URL_TMPL: http://bkapi.example.com/api/{api_name}"l, 注意 {api_name}是占位符需要保留
451470
452471
### 3.同步过程中报错: `校验失败: api_type: api_type 为 1 时，网关名 name 需以 bk- 开头。`
453472
这个是因为 `definition.yaml` 定义的 apigateway.api_type为 1，标记网关为官方网关，网关名需以 `bk-` 开头，可选；非官方网关，可去除此配置
454-
当设置为 1 时,则 `sync-apigateway.sh`里面的 `gateway_name` 参数需要以 bk- 开头
473+
当设置为 1 时,则 `sync-apigateway.sh`里面的 `gateway_name` 参数需要以 bk- 开头
474+
475+
### 4.definition.yaml 指定了一个环境，为啥发布时却将其他环境也进行了发布？
476+
definition.yaml 指定的环境配置适用于 `sync_apigw_stage` 命令，而资源发布 `create_version_and_release_apigw` 需要通过指定 --stage prod test 等方式来指定，未指定则
477+
会发布所有该网关存在的环境

‎sdks/apigw-manager/docs/plugin-use-guide.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# 插件配置说明
2+
插件配置支持主要在 `stage`(definition.yaml) 和 `resource`(resource.yaml) 两个维度上，资源配置的插件优先级最高。
3+
> 注意：所有配置均以 yaml 配置同步为主，举例来说： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果 yaml 没有配置该插件，则也不会移除
4+
> 用户之前在页面创建的插件配置，不过 yaml 如果没有配置上一次yaml配置的插件，则会移除上一次 yaml 配置的插件。
5+
> `CORS` 插件和 `IP 访问保护插件` 不推荐在yaml配置绑定在环境上。
6+
7+
## 跨域资源共享（CORS）插件
8+
9+
| 参数 | 类型 | 默认值 | 描述 |
10+
| ---------------- | ------ | ------ | ------------------------------------------------------------ |
11+
| allow_origins | 字符串 | "" | 允许跨域访问的 Origin，可以使用 * 表示允许所有 Origin 通过。 |
12+
| allow_methods | 字符串 | "**" | 允许跨域访问的 Method，可以使用 * 表示允许所有 Method 通过。 |
13+
| allow_headers | 字符串 | "**" | 允许跨域访问时请求方携带的 Header，可以使用 * 表示允许所有 Header 通过。 |
14+
| expose_headers | 字符串 | "" | 允许跨域访问时响应方携带的 Header，可以使用 * 表示允许任意 Header。 |
15+
| max_age | 整数 | 86400 | 浏览器缓存 CORS 结果的最大时间，单位为秒。 |
16+
| allow_credential | 布尔值 | true | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。 |
17+
18+
### 配置例子
19+
20+
```yaml
21+
- type: bk-cors
22+
yaml: |-
23+
allow_origins: '*'
24+
allow_methods: '*'
25+
allow_headers: '*'
26+
expose_headers: '*'
27+
max_age: 86400
28+
allow_credential: false
29+
```
30+
31+
## Header 转换插件
32+
33+
| 参数 | 类型 | 默认值 | 描述 |
34+
| ------ | ---- | ------ | ---------------------------- |
35+
| set | 数组 | [] | 设置的请求头，包括键和值。 |
36+
| remove | 数组 | [] | 删除的请求头，只需要提供键。 |
37+
38+
### 配置例子
39+
40+
```yaml
41+
- type: bk-header-rewrite
42+
yaml: |-
43+
set:
44+
- key: test
45+
value: '2'
46+
remove: []
47+
```
48+
49+
## IP 访问保护插件
50+
51+
| 参数 | 类型 | 默认值 | 描述 |
52+
| --------- | ------ | ------ | -------------------------------------- |
53+
| whitelist | 字符串 | "" | 白名单中的 IP 地址，支持 CIDR 表示法。 |
54+
| blacklist | 字符串 | "" | 黑名单中的 IP 地址，支持 CIDR 表示法。 |
55+
| message | 字符串 | "" | 当 IP 地址不被允许时显示的消息。 |
56+
57+
### 配置例子
58+
59+
```yaml
60+
- type: bk-ip-restriction
61+
yaml: |-
62+
whitelist: '1.1.1.1'
63+
blacklist: '2.2.2.2'
64+
message: 'Your IP is not allowed'
65+
```
66+
67+
## 频率控制插件
68+
69+
| 参数 | 类型 | 默认值 | 描述 |
70+
| ----------- | ------ | ------ | ------------------------------------------------ |
71+
| rates | 对象 | {} | 包含默认频率限制和特殊应用频率限制的对象。 |
72+
| default | 对象 | {} | 单个应用的默认频率限制，包括次数和时间范围。 |
73+
| specials | 数组 | [] | 特殊应用频率限制，对指定应用设置单独的频率限制。 |
74+
| bk_app_code | 字符串 | "" | 蓝鲸应用ID，用于特殊应用频率限制。 |
75+
76+
### 配置例子
77+
78+
```yaml
79+
- type: bk-rate-limit
80+
yaml: |-
81+
rates:
82+
__default:
83+
- period: 1
84+
tokens: 100
85+
```

‎sdks/apigw-manager/docs/sync-apigateway-with-django.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ python manage.py sync_apigw_resources --delete --gateway-name=${gateway_name} --
3939
# 可选，同步资源文档
4040
python manage.py sync_resource_docs_by_archive --gateway-name=${gateway_name} --file="${definition_file}"
4141

42-
# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
42+
# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK 指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
4343
python manage.py create_version_and_release_apigw --gateway-name=${gateway_name} --file="${definition_file}"
4444

4545
# 可选，为应用主动授权
@@ -152,7 +152,7 @@ python manage.py add_related_apps --gateway-name=${gateway_name} --file="${defin
152152
# 可选，申请网关权限
153153
python manage.py apply_apigw_permissions --gateway-name=${gateway_name} --file="${definition_file}"
154154

155-
# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
155+
# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK 指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
156156
python manage.py create_version_and_release_apigw --gateway-name=${gateway_name} --file="${definition_file}"
157157

158158
# 获取网关公钥

‎sdks/apigw-manager/docs/sync-apigateway-with-docker.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -267,13 +267,13 @@ docker run --rm \
267267
### 支持同步指令
268268

269269
```bash
270-
#可选，为网关添加关联应用，关联应用可以通过网关 bk-apigateway 提供的接口管理网关数据
270+
# 可选，为网关添加关联应用，关联应用可以通过网关 bk-apigateway 提供的接口管理网关数据
271271
call_definition_command_or_exit add_related_apps "${definition_file}" --gateway-name=${gateway_name}
272272

273-
#可选，申请网关权限
273+
# 可选，申请网关权限
274274
call_definition_command_or_exit apply_apigw_permissions "${definition_file}" --gateway-name=${gateway_name}
275275

276-
#创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
276+
# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK, 指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
277277
call_definition_command_or_exit create_version_and_release_apigw "${definition_file}" --gateway-name=${gateway_name}
278278

279279
# 获取网关公钥，存放到文件 apigateway.pub

‎sdks/apigw-manager/examples/chart/use-configmap/files/support-files/definition.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,30 @@ stage:
2424
hosts:
2525
- host: "https://httpbin.org"
2626
weight: 100
27+
# 环境插件配置
28+
# plugin_configs:
29+
# - type: bk-rate-limit
30+
# yaml: |-
31+
# rates:
32+
# __default:
33+
# - period: 1
34+
# tokens: 100
35+
# - type: bk-header-rewrite
36+
# yaml: |-
37+
# set:
38+
# - key: test
39+
# value: '2'
40+
# remove: []
41+
# - type: bk-cors
42+
# yaml: |-
43+
# allow_origins: '*'
44+
# allow_methods: '*'
45+
# allow_headers: '*'
46+
# expose_headers: '*'
47+
# max_age: 86400
48+
# allow_credential: false
2749

50+
2851
# 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
2952
# 同步脚本 sync-apigateway.sh 需要新增以下命令:
3053
# call_definition_command_or_exit sync_apigw_stage "${definition_file}" --gateway-name=${gateway_name} --namespace="stage2"

‎sdks/apigw-manager/examples/chart/use-configmap/files/support-files/resources.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,25 @@ paths:
3232
userVerifiedRequired: false
3333
resourcePermissionRequired: false
3434
descriptionEn:
35+
# 资源插件配置
36+
# pluginConfigs:
37+
# - type: bk-rate-limit
38+
# yaml: |-
39+
# rates:
40+
# __default:
41+
# - period: 1
42+
# tokens: 100
43+
# - type: bk-header-rewrite
44+
# yaml: |-
45+
# set:
46+
# - key: test
47+
# value: '2'
48+
# remove: []
49+
# - type: bk-cors
50+
# yaml: |-
51+
# allow_origins: '*'
52+
# allow_methods: '*'
53+
# allow_headers: '*'
54+
# expose_headers: '*'
55+
# max_age: 86400
56+
# allow_credential: false

‎sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/definition.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,28 @@ stage:
2424
hosts:
2525
- host: "https://httpbin.org"
2626
weight: 100
27+
# 环境插件配置
28+
# plugin_configs:
29+
# - type: bk-rate-limit
30+
# yaml: |-
31+
# rates:
32+
# __default:
33+
# - period: 1
34+
# tokens: 100
35+
# - type: bk-header-rewrite
36+
# yaml: |-
37+
# set:
38+
# - key: test
39+
# value: '2'
40+
# remove: []
41+
# - type: bk-cors
42+
# yaml: |-
43+
# allow_origins: '*'
44+
# allow_methods: '*'
45+
# allow_headers: '*'
46+
# expose_headers: '*'
47+
# max_age: 86400
48+
# allow_credential: false
2749

2850
# 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
2951
# 同步脚本 sync-apigateway.sh 需要新增以下命令:

‎sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/resources.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,25 @@ paths:
3232
userVerifiedRequired: false
3333
resourcePermissionRequired: false
3434
descriptionEn:
35+
# 插件配置
36+
# pluginConfigs:
37+
# - type: bk-rate-limit
38+
# yaml: |-
39+
# rates:
40+
# __default:
41+
# - period: 1
42+
# tokens: 100
43+
# - type: bk-header-rewrite
44+
# yaml: |-
45+
# set:
46+
# - key: test
47+
# value: '2'
48+
# remove: []
49+
# - type: bk-cors
50+
# yaml: |-
51+
# allow_origins: '*'
52+
# allow_methods: '*'
53+
# allow_headers: '*'
54+
# expose_headers: '*'
55+
# max_age: 86400
56+
# allow_credential: false

0 commit comments

Comments
 (0)