feat: apigw manager add plugin use guide

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
 
 # 主动授权，网关主动给应用，添加访问网关所有资源或者具体某个资源的权限；
 # 用于命令 `grant_apigw_permissions`
@@ -173,15 +190,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。
@@ -385,7 +404,7 @@ 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` 漏配或者配错了(自定义脚本中存在错误)。eg: 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-` 开头，可选；非官方网关，可去除此配置

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

@@ -0,0 +1,98 @@
+# 插件配置说明
+插件配置支持主要在 `stage`(definition.yaml) 和 `resource`(resource.yaml) 两个维度上，资源配置的插件优先级最高。
+> 注意：所有配置均以yaml配置同步为主，eg： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果yaml没有配置该插件，则也不会移除
+> 用户之前在页面创建的插件配置，不过yaml如果没有配置上一次yaml配置的插件，则会移除上一次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
+1- type: bk-header-rewrite
+2  yaml: |-
+3    set:
+4      - key: test
+5        value: '2'
+6    remove: []
+```
+
+## IP 访问保护插件
+
+| 参数      | 类型   | 默认值 | 描述                                   |
+| --------- | ------ | ------ | -------------------------------------- |
+| whitelist | 字符串 | ""     | 白名单中的 IP 地址，支持 CIDR 表示法。 |
+| blacklist | 字符串 | ""     | 黑名单中的 IP 地址，支持 CIDR 表示法。 |
+| message   | 字符串 | ""     | 当 IP 地址不被允许时显示的消息。       |
+
+### 配置例子
+
+```yaml
+1- type: bk-ip-restriction
+2  yaml: |-
+3    whitelist: '1.1.1.1'
+4    blacklist: '2.2.2.2'
+5    message: 'Your IP is not allowed'
+```
+
+## 频率控制插件
+
+| 参数        | 类型   | 默认值 | 描述                                             |
+| ----------- | ------ | ------ | ------------------------------------------------ |
+| rates       | 对象   | {}     | 包含默认频率限制和特殊应用频率限制的对象。       |
+| default     | 对象   | {}     | 单个应用的默认频率限制，包括次数和时间范围。     |
+| specials    | 数组   | []     | 特殊应用频率限制，对指定应用设置单独的频率限制。 |
+| bk_app_code | 字符串 | ""     | 蓝鲸应用ID，用于特殊应用频率限制。               |
+
+### 配置例子
+
+```yaml
+1- type: bk-rate-limit
+2  yaml: |-
+3    rates:
+4      __default:
+5        - period: 1
+6          tokens: 100
+```
+
+
+
+## 网关错误使用HTTP状态码200插件（不推荐）
+
+此插件没有配置参数。
+
+### 配置例子
+
+```yaml
+1- type: bk-status-rewrite
+2  yaml: '{}'
+3    # 该插件无需配置参数
+```

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