From d7badd9f4b0f505047f019438eccc179f1e9deb0 Mon Sep 17 00:00:00 2001 From: Han-Ya-Jun <1581532052@qq.com> Date: Thu, 29 Feb 2024 16:36:10 +0800 Subject: [PATCH 1/3] feat: apigw manager add plugin use guide --- sdks/apigw-manager/README.md | 39 ++++++-- sdks/apigw-manager/docs/plugin-use-guide.md | 98 +++++++++++++++++++ .../files/support-files/definition.yaml | 23 +++++ .../files/support-files/resources.yaml | 22 +++++ .../support-files/definition.yaml | 22 +++++ .../support-files/resources.yaml | 22 +++++ 6 files changed, 216 insertions(+), 10 deletions(-) create mode 100644 sdks/apigw-manager/docs/plugin-use-guide.md diff --git a/sdks/apigw-manager/README.md b/sdks/apigw-manager/README.md index c89f8969..a9781b74 100644 --- a/sdks/apigw-manager/README.md +++ b/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-` 开头，可选；非官方网关，可去除此配置 diff --git a/sdks/apigw-manager/docs/plugin-use-guide.md b/sdks/apigw-manager/docs/plugin-use-guide.md new file mode 100644 index 00000000..358885aa --- /dev/null +++ b/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 # 该插件无需配置参数 +``` \ No newline at end of file diff --git a/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/definition.yaml b/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/definition.yaml index 6f0218f5..861ee689 100644 --- a/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/definition.yaml +++ b/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" diff --git a/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/resources.yaml b/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/resources.yaml index 1435567e..d855158a 100644 --- a/sdks/apigw-manager/examples/chart/use-configmap/files/support-files/resources.yaml +++ b/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 diff --git a/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/definition.yaml b/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/definition.yaml index f2efa4dc..8ca02115 100644 --- a/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/definition.yaml +++ b/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 需要新增以下命令: diff --git a/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/resources.yaml b/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/resources.yaml index 1435567e..160cc97e 100644 --- a/sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/resources.yaml +++ b/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 From 919961064b599ade73b71a115675ac8688d846aa Mon Sep 17 00:00:00 2001 From: Han-Ya-Jun <1581532052@qq.com> Date: Thu, 29 Feb 2024 17:16:39 +0800 Subject: [PATCH 2/3] fix: fix doc --- sdks/apigw-manager/docs/plugin-use-guide.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/sdks/apigw-manager/docs/plugin-use-guide.md b/sdks/apigw-manager/docs/plugin-use-guide.md index 358885aa..dc05c093 100644 --- a/sdks/apigw-manager/docs/plugin-use-guide.md +++ b/sdks/apigw-manager/docs/plugin-use-guide.md @@ -2,6 +2,7 @@ 插件配置支持主要在 `stage`(definition.yaml) 和 `resource`(resource.yaml) 两个维度上，资源配置的插件优先级最高。 > 注意：所有配置均以yaml配置同步为主，eg： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果yaml没有配置该插件，则也不会移除 > 用户之前在页面创建的插件配置，不过yaml如果没有配置上一次yaml配置的插件，则会移除上一次yaml配置的插件。 +> `CORS` 插件和 `IP 访问保护插件` 不推荐在yaml配置绑定在环境上。 ## 跨域资源共享（CORS）插件 @@ -79,20 +80,6 @@ 2 yaml: |- 3 rates: 4 __default: -5 - period: 1 +5 - period: 1 6 tokens: 100 ``` - - - -## 网关错误使用HTTP状态码200插件（不推荐） - -此插件没有配置参数。 - -### 配置例子 - -```yaml -1- type: bk-status-rewrite -2 yaml: '{}' -3 # 该插件无需配置参数 -``` \ No newline at end of file From 2dbf4fec4084628f17f01254a8d111c80ed41867 Mon Sep 17 00:00:00 2001 From: Han-Ya-Jun <1581532052@qq.com> Date: Wed, 29 May 2024 14:55:58 +0800 Subject: [PATCH 3/3] doc: fix doc --- sdks/apigw-manager/README.md | 8 +++- sdks/apigw-manager/docs/plugin-use-guide.md | 38 +++++++++---------- .../docs/sync-apigateway-with-django.md | 4 +- .../docs/sync-apigateway-with-docker.md | 6 +-- 4 files changed, 30 insertions(+), 26 deletions(-) diff --git a/sdks/apigw-manager/README.md b/sdks/apigw-manager/README.md index a9781b74..a6fe4470 100644 --- a/sdks/apigw-manager/README.md +++ b/sdks/apigw-manager/README.md @@ -404,8 +404,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- 开头 \ No newline at end of file +当设置为 1 时,则 `sync-apigateway.sh`里面的 `gateway_name` 参数需要以 bk- 开头 + +### 4.definition.yaml 指定了一个环境，为啥发布时却将其他环境也进行了发布？ +definition.yaml 指定的环境配置适用于 `sync_apigw_stage` 命令，而资源发布 `create_version_and_release_apigw` 需要通过指定 --stage prod test 等方式来指定，未指定则 +会发布所有该网关存在的环境 \ No newline at end of file diff --git a/sdks/apigw-manager/docs/plugin-use-guide.md b/sdks/apigw-manager/docs/plugin-use-guide.md index dc05c093..88e78da7 100644 --- a/sdks/apigw-manager/docs/plugin-use-guide.md +++ b/sdks/apigw-manager/docs/plugin-use-guide.md @@ -1,7 +1,7 @@ # 插件配置说明 插件配置支持主要在 `stage`(definition.yaml) 和 `resource`(resource.yaml) 两个维度上，资源配置的插件优先级最高。 -> 注意：所有配置均以yaml配置同步为主，eg： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果yaml没有配置该插件，则也不会移除 -> 用户之前在页面创建的插件配置，不过yaml如果没有配置上一次yaml配置的插件，则会移除上一次yaml配置的插件。 +> 注意：所有配置均以 yaml 配置同步为主，举例来说： 如果通过yaml配置的插件配置则会覆盖掉用户在网关管理页面创建的插件配置，如果 yaml 没有配置该插件，则也不会移除 +> 用户之前在页面创建的插件配置，不过 yaml 如果没有配置上一次yaml配置的插件，则会移除上一次 yaml 配置的插件。 > `CORS` 插件和 `IP 访问保护插件` 不推荐在yaml配置绑定在环境上。 ## 跨域资源共享（CORS）插件 @@ -38,12 +38,12 @@ ### 配置例子 ```yaml -1- type: bk-header-rewrite -2 yaml: |- -3 set: -4 - key: test -5 value: '2' -6 remove: [] +- type: bk-header-rewrite + yaml: |- + set: + - key: test + value: '2' + remove: [] ``` ## IP 访问保护插件 @@ -57,11 +57,11 @@ ### 配置例子 ```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' +- type: bk-ip-restriction + yaml: |- + whitelist: '1.1.1.1' + blacklist: '2.2.2.2' + message: 'Your IP is not allowed' ``` ## 频率控制插件 @@ -76,10 +76,10 @@ ### 配置例子 ```yaml -1- type: bk-rate-limit -2 yaml: |- -3 rates: -4 __default: -5 - period: 1 -6 tokens: 100 +- type: bk-rate-limit + yaml: |- + rates: + __default: + - period: 1 + tokens: 100 ``` diff --git a/sdks/apigw-manager/docs/sync-apigateway-with-django.md b/sdks/apigw-manager/docs/sync-apigateway-with-django.md index 6fe155cd..aaa36288 100644 --- a/sdks/apigw-manager/docs/sync-apigateway-with-django.md +++ b/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}" # 获取网关公钥 diff --git a/sdks/apigw-manager/docs/sync-apigateway-with-docker.md b/sdks/apigw-manager/docs/sync-apigateway-with-docker.md index 70e67eda..d5b4ca28 100644 --- a/sdks/apigw-manager/docs/sync-apigateway-with-docker.md +++ b/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