feat: apigw manager add plugin use guide (#155)

sdks/apigw-manager/README.md

@@ -69,8 +69,8 @@ support-files
 ```
 
 definition.yaml 中可以使用 Django 模版语法引用和渲染变量，内置以下变量：
-- `settings`：Django 提供的配置对象,优先适合用于使用 Django Command 同步
-- `environ`：环境变量,推荐镜像同步方式使用
+- `settings`：Django 提供的配置对象，优先适合用于使用 Django Command 同步
+- `environ`：环境变量，推荐镜像同步方式使用
 
 推荐在一个文件中统一进行定义，用命名空间区分不同配置间的定义，definition.yaml 样例：
 
@@ -127,11 +127,28 @@ stage:
         # 网关调用后端服务的默认域名或IP，不包含Path，比如：http://api.example.com
         - host: ""
           weight: 100
-    # Header转换；如未使用，可去除此配置
-    # transform_headers:
-    #   # 设置Headers
-    #   set:
-    #     X-Token: "token"
+    # 环境插件配置
+    # pluginConfigs:
+    #     - type: bk-rate-limit
+    #       yaml: |-
+    #         rates:
+    #           __default:
+    #           - period: 1
+    #             tokens: 100
+    #     - type: bk-header-rewrite
+    #       yaml: |-
+    #         set:
+    #           - key: test
+    #             value: '2'
+    #         remove: []
+    #     - type: bk-cors
+    #       yaml: |-
+    #         allow_origins: '*'
+    #         allow_methods: '*'
+    #         allow_headers: '*'
+    #         expose_headers: '*'
+    #         max_age: 86400
+    #         allow_credential: false
 
 
 # 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
@@ -191,15 +208,17 @@ resource_docs:
 ```
 
 **注意：**
-- 同步资源后，需要创建版本并发布才能生效，发布数据定义于 definition.yaml `release`
+- 同步资源或者环境相关配置后，需要创建版本并发布才能生效，发布数据定义于 definition.yaml `release`
 - 资源配置 resources.yaml 变更时，需要更新 definition.yaml `release` 中的版本号 version，以便正确创建资源版本及 SDK
-
+- 详细的插件配置见：[插件配置说明](docs/plugin-use-guide.md)
 #### 2. resources.yaml
 
 用于定义资源配置，建议通过网关管理端导出。为了方便用户直接使用网关导出的资源文件，资源定义默认没有命名空间。
 
 样例可参考：[resources.yaml](examples/django/use-custom-script/support-files/resources.yaml)
 
+> 详细的插件配置见：[插件配置说明](docs/plugin-use-guide.md)
+
 #### 3. apidocs（可选）
 
 资源文档，资源文档为 markdown 格式。资源文档的文件名，应为 `资源名称` + `.md` 格式，假如资源名称为 get_user，则文档文件名应为 get_user.md。
@@ -447,8 +466,12 @@ APIGW_MANAGER_DUMMY_PAYLOAD_USERNAME  # JWT payload 中的 username
 这种大概率是自定义脚本有问题，参照文档，按照对应目录下的 examples 的同步脚本即可。
 
 ### 2.执行同步命令时报错：`Error responded by API Gateway, status_code:_code: 404, request_id:, error_code: 1640401, API not found`
-这种大概率是网关URL `BK_API_URL_TMPL` 漏配或者配错了。eg: BK_API_URL_TMPL: http://bkapi.example.com/api/{api_name}"l, 注意 {api_name}是占位符需要保留
+网关URL `BK_API_URL_TMPL` 漏配或者配错了(自定义脚本中存在错误)。举例说明: BK_API_URL_TMPL: http://bkapi.example.com/api/{api_name}"l, 注意 {api_name}是占位符需要保留
 
 ### 3.同步过程中报错: `校验失败: api_type: api_type 为 1 时，网关名 name 需以 bk- 开头。`
 这个是因为 `definition.yaml` 定义的 apigateway.api_type为 1，标记网关为官方网关，网关名需以 `bk-` 开头，可选；非官方网关，可去除此配置
-当设置为 1 时,则 `sync-apigateway.sh`里面的 `gateway_name` 参数需要以 bk- 开头
+当设置为 1 时,则 `sync-apigateway.sh`里面的 `gateway_name` 参数需要以 bk- 开头
+
+### 4.definition.yaml 指定了一个环境，为啥发布时却将其他环境也进行了发布？
+definition.yaml 指定的环境配置适用于 `sync_apigw_stage` 命令，而资源发布 `create_version_and_release_apigw` 需要通过指定 --stage prod test 等方式来指定，未指定则
+会发布所有该网关存在的环境

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

@@ -0,0 +1,85 @@
+# 插件配置说明
+插件配置支持主要在 `stage`(definition.yaml) 和 `resource`(resource.yaml) 两个维度上，资源配置的插件优先级最高。
+> 注意：所有配置均以 yaml 配置同步为主，举例来说： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果 yaml 没有配置该插件，则也不会移除
+> 用户之前在页面创建的插件配置，不过 yaml 如果没有配置上一次yaml配置的插件，则会移除上一次 yaml 配置的插件。
+> `CORS` 插件和 `IP 访问保护插件` 不推荐在yaml配置绑定在环境上。
+
+## 跨域资源共享（CORS）插件
+
+| 参数             | 类型   | 默认值 | 描述                                                         |
+| ---------------- | ------ | ------ | ------------------------------------------------------------ |
+| allow_origins    | 字符串 | ""     | 允许跨域访问的 Origin，可以使用 * 表示允许所有 Origin 通过。 |
+| allow_methods    | 字符串 | "**"   | 允许跨域访问的 Method，可以使用 * 表示允许所有 Method 通过。 |
+| allow_headers    | 字符串 | "**"   | 允许跨域访问时请求方携带的 Header，可以使用 * 表示允许所有 Header 通过。 |
+| expose_headers   | 字符串 | ""     | 允许跨域访问时响应方携带的 Header，可以使用 * 表示允许任意 Header。 |
+| max_age          | 整数   | 86400  | 浏览器缓存 CORS 结果的最大时间，单位为秒。                   |
+| allow_credential | 布尔值 | true   | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。           |
+
+### 配置例子
+
+```yaml
+- type: bk-cors
+  yaml: |-
+    allow_origins: '*'
+    allow_methods: '*'
+    allow_headers: '*'
+    expose_headers: '*'
+    max_age: 86400
+    allow_credential: false
+```
+
+## Header 转换插件
+
+| 参数   | 类型 | 默认值 | 描述                         |
+| ------ | ---- | ------ | ---------------------------- |
+| set    | 数组 | []     | 设置的请求头，包括键和值。   |
+| remove | 数组 | []     | 删除的请求头，只需要提供键。 |
+
+### 配置例子
+
+```yaml
+- type: bk-header-rewrite
+  yaml: |-
+    set:
+      - key: test
+        value: '2'
+    remove: []
+```
+
+## IP 访问保护插件
+
+| 参数      | 类型   | 默认值 | 描述                                   |
+| --------- | ------ | ------ | -------------------------------------- |
+| whitelist | 字符串 | ""     | 白名单中的 IP 地址，支持 CIDR 表示法。 |
+| blacklist | 字符串 | ""     | 黑名单中的 IP 地址，支持 CIDR 表示法。 |
+| message   | 字符串 | ""     | 当 IP 地址不被允许时显示的消息。       |
+
+### 配置例子
+
+```yaml
+- type: bk-ip-restriction
+  yaml: |-
+    whitelist: '1.1.1.1'
+    blacklist: '2.2.2.2'
+    message: 'Your IP is not allowed'
+```
+
+## 频率控制插件
+
+| 参数        | 类型   | 默认值 | 描述                                             |
+| ----------- | ------ | ------ | ------------------------------------------------ |
+| rates       | 对象   | {}     | 包含默认频率限制和特殊应用频率限制的对象。       |
+| default     | 对象   | {}     | 单个应用的默认频率限制，包括次数和时间范围。     |
+| specials    | 数组   | []     | 特殊应用频率限制，对指定应用设置单独的频率限制。 |
+| bk_app_code | 字符串 | ""     | 蓝鲸应用ID，用于特殊应用频率限制。               |
+
+### 配置例子
+
+```yaml
+- type: bk-rate-limit
+  yaml: |-
+    rates:
+      __default:
+      - period: 1
+          tokens: 100
+```

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

@@ -39,7 +39,7 @@ python manage.py sync_apigw_resources --delete --gateway-name=${gateway_name} --
 # 可选，同步资源文档
 python manage.py sync_resource_docs_by_archive --gateway-name=${gateway_name} --file="${definition_file}"
 
-# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
+# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK  指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
 python manage.py create_version_and_release_apigw --gateway-name=${gateway_name} --file="${definition_file}"
 
 # 可选，为应用主动授权
@@ -152,7 +152,7 @@ python manage.py add_related_apps --gateway-name=${gateway_name} --file="${defin
 # 可选，申请网关权限
 python manage.py apply_apigw_permissions --gateway-name=${gateway_name} --file="${definition_file}"
 
-# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
+# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK 指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
 python manage.py create_version_and_release_apigw --gateway-name=${gateway_name} --file="${definition_file}"
 
 # 获取网关公钥

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

@@ -267,13 +267,13 @@ docker run --rm \
 ### 支持同步指令
 
 ```bash
-#可选，为网关添加关联应用，关联应用可以通过网关 bk-apigateway 提供的接口管理网关数据
+# 可选，为网关添加关联应用，关联应用可以通过网关 bk-apigateway 提供的接口管理网关数据
 call_definition_command_or_exit add_related_apps "${definition_file}" --gateway-name=${gateway_name}
 
-#可选，申请网关权限 
+# 可选，申请网关权限 
 call_definition_command_or_exit apply_apigw_permissions "${definition_file}" --gateway-name=${gateway_name} 
 
-#创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK
+# 创建资源版本并发布；指定参数 --generate-sdks 时，会同时生成资源版本对应的网关 SDK, 指定 --stage stage1 stage2 时会发布指定环境,不设置则发布所有环境
 call_definition_command_or_exit create_version_and_release_apigw "${definition_file}" --gateway-name=${gateway_name}
 
 # 获取网关公钥，存放到文件 apigateway.pub 

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

@@ -24,7 +24,30 @@ stage:
       hosts:
         - host: "https://httpbin.org"
           weight: 100
+  # 环境插件配置
+  # plugin_configs:
+  #     - type: bk-rate-limit
+  #       yaml: |-
+  #         rates:
+  #           __default:
+  #           - period: 1
+  #             tokens: 100
+  #     - type: bk-header-rewrite
+  #       yaml: |-
+  #         set:
+  #           - key: test
+  #             value: '2'
+  #         remove: []
+  #     - type: bk-cors
+  #       yaml: |-
+  #         allow_origins: '*'
+  #         allow_methods: '*'
+  #         allow_headers: '*'
+  #         expose_headers: '*'
+  #         max_age: 86400
+  #         allow_credential: false
 
+
 # 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
 # 同步脚本 sync-apigateway.sh 需要新增以下命令:
 # 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

@@ -32,3 +32,25 @@ paths:
           userVerifiedRequired: false
           resourcePermissionRequired: false
         descriptionEn:
+        # 资源插件配置
+        # pluginConfigs:
+        #     - type: bk-rate-limit
+        #       yaml: |-
+        #         rates:
+        #           __default:
+        #           - period: 1
+        #             tokens: 100
+        #     - type: bk-header-rewrite
+        #       yaml: |-
+        #         set:
+        #           - key: test
+        #             value: '2'
+        #         remove: []
+        #     - type: bk-cors
+        #       yaml: |-
+        #         allow_origins: '*'
+        #         allow_methods: '*'
+        #         allow_headers: '*'
+        #         expose_headers: '*'
+        #         max_age: 86400
+        #         allow_credential: false

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

@@ -24,6 +24,28 @@ stage:
       hosts:
         - host: "https://httpbin.org"
           weight: 100
+  # 环境插件配置
+  # plugin_configs:
+  #     - type: bk-rate-limit
+  #       yaml: |-
+  #         rates:
+  #           __default:
+  #           - period: 1
+  #             tokens: 100
+  #     - type: bk-header-rewrite
+  #       yaml: |-
+  #         set:
+  #           - key: test
+  #             value: '2'
+  #         remove: []
+  #     - type: bk-cors
+  #       yaml: |-
+  #         allow_origins: '*'
+  #         allow_methods: '*'
+  #         allow_headers: '*'
+  #         expose_headers: '*'
+  #         max_age: 86400
+  #         allow_credential: false
 
 # 支持定义多个stage,如果定义多个，则同步脚本需要添加对应的同步命令，并指明：namespace(默认：stage) eg：stage2
 # 同步脚本 sync-apigateway.sh 需要新增以下命令:

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

@@ -32,3 +32,25 @@ paths:
           userVerifiedRequired: false
           resourcePermissionRequired: false
         descriptionEn:
+        # 插件配置
+        # pluginConfigs:
+        #     - type: bk-rate-limit
+        #       yaml: |-
+        #         rates:
+        #           __default:
+        #           - period: 1
+        #             tokens: 100
+        #     - type: bk-header-rewrite
+        #       yaml: |-
+        #         set:
+        #           - key: test
+        #             value: '2'
+        #         remove: []
+        #     - type: bk-cors
+        #       yaml: |-
+        #         allow_origins: '*'
+        #         allow_methods: '*'
+        #         allow_headers: '*'
+        #         expose_headers: '*'
+        #         max_age: 86400
+        #         allow_credential: false