tencentblueking/blueking-apigateway

蓝鲸 API 网关（API Gateway），是一种高性能、高可用的 API 托管服务

简体中文 | English

概览

蓝鲸 API 网关（API Gateway），是一种高性能、高可用的 API 托管服务，可以帮助开发者创建、发布、维护、监控和保护 API， 以快速、低成本、低风险地对外开放蓝鲸应用或其他系统的数据或服务

本项目是 蓝鲸 API 网关 - 控制面。

蓝鲸 API 网关核心服务开源项目

• 蓝鲸 API 网关 - 控制面
  • dashboard：API 网关的控制面
  • dashboard-front: API 网关控制面前端
  • core-api: 网关高性能核心 API
  • esb: ESB 组件服务
• 蓝鲸 API 网关 - 数据面
• 蓝鲸 API 网关 - Operator

功能特性

• API 生命周期管理: 涵盖 API 的配置、发布、测试、监控、下线等各个生命周期的管理。
• 版本发布: 支持多环境管理，用户可新建环境，满足开发、测试、正式等多环境的需求;提供 API 的版本管理，各环境可一键切换版本，互不影响。
• 文档和SDK: 提供在线文档，及调用网关 API 的 SDK，降低 API 的使用门槛。
• 权限管理: 默认开启权限限制, 支持权限期限及授权维度。
• 安全防护: 支持蓝鲸应用认证、用户认证，控制请求来源; 支持 IP 访问控制，可设置 IP 黑/白名单; 支持秒级的流量控制，可根据需求进行流量分配，以避免高流量导致的后端服务过载; 支持操作审计。
• 可观测性: 支持调用流水查询; 支持接入 OpenTelemetry; 内置多种告警策略。

快速开始

• 本地开发部署指引

支持

• 蓝鲸 API 网关产品白皮书
• 蓝鲸智云 - 学习社区
• 蓝鲸 DevOps 在线视频教程
• 加入技术交流 QQ 群：

蓝鲸社区

• BK-CI：蓝鲸持续集成平台是一个开源的持续集成和持续交付系统，可以轻松将你的研发流程呈现到你面前。
• BK-BCS：蓝鲸容器管理平台是以容器技术为基础，为微服务业务提供编排管理的基础服务平台。
• BK-SOPS：标准运维（SOPS）是通过可视化的图形界面进行任务流程编排和执行的系统，是蓝鲸体系中一款轻量级的调度编排类 SaaS 产品。
• BK-CMDB：蓝鲸配置平台是一个面向资产及应用的企业级配置管理平台。
• BK-JOB：蓝鲸作业平台（Job）是一套运维脚本管理系统，具备海量任务并发处理能力。

贡献

如果你有好的意见或建议，欢迎给我们提 Issues 或 PullRequests，为蓝鲸开源社区贡献力量。关于分支 / Issue 及 PR, 请查看 CONTRIBUTING。

腾讯开源激励计划 鼓励开发者的参与和贡献，期待你的加入。

blueking-apigateway's Issues

API 网关：dashboard 使用 RabbitMQ 作为 celery 的 broker (>=1.12.1 版本)

Description

网关管理端 dashboard 模块，需要用到 celery 后台任务，其默认使用 redis 作为 celery broker，但是此方案有一些缺点：

• 1. 多个部署实例如果共用了 redis，可能导致 celery 任务被错误调度
• 2. 不太可靠，没有机制保证消息的消费，消费者消费失败时候，消息体丢失
• 3. 无法保证顺序，redis 无法保证任务执行的顺序，可能会导致任务之间的依赖关系出现问题

对于开发环境，可使用默认的 redis，比较简单；但对于生产环境，推荐使用 RabbitMQ。网关在 >= 1.12.1 版本，支持配置外部的 RabbitMQ，values.yaml 中配置样例如下；可以为每个环境创建单独的 vhost，保障部署环境数据的隔离。

## 外部 Rabbitmq 配置
##
externalRabbitmq:
  ## 默认 Rabbitmq 连接信息
  ## 如未完成配置，则使用 redis 作为 celery broker
  ##
  default:
    ## 连接地址
    ##
    host: "rabbitmq.example.com"
    ## 连接端口
    ##
    port: 5672
    ## 用户名
    ##
    username: "bk_apigateway"
    ## 明文方式的密码
    ##
    password: ""
    ## virtual host
    ##
    vhost: "bk_apigateway"

bk-apigateway FAQ

Description

[toc]

网关错误响应说明

499

无response body

• 原因: client 调用网关等待时间超过设置的timeout时间, 主动关闭连接, 此时网关会主动关闭后端接口的调用, 返回 499
• 处理: 被调用方提升接口性能, 或者调大client的超时时间(不建议过大)

504

{
  "code_name": "REQUEST_BACKEND_TIMEOUT",
  "data": null,
  "code": 1650401,
  "message": "Request backend service timeout [upstream_error=\"cannot read header from upstream\"]",
  "result": false
}

• 原因: 网关资源会配置后端接口的timeout时间, 如果后端接口调用超时, 此时网关返回504
• 处理: 被调用方提升接口性能, 或者调大网关的超时时间(不建议过大)

后台错误响应说明

调用方式

认证

概念

• 应用认证: 蓝鲸PaaS平台会给每个应用分配一个唯一的bk_app_code, 以及对应的bk_app_secret用于应用身份认证; 如果 API 启用了应用认证, 那么调用方需要在请求头中提供合法的bk_app_code/bk_app_secret, 网关会校验应用是否合法
• 用户认证: 蓝鲸统一登录, 会给每个登录的用户分配唯一的登录态bk_token(在cookie中), 用于用户身份认证; 如果 API 启用了 用户认证, 那么调用方需要在请求头中提供合法的bk_token, 网关会校验用户是否合法
• 校验访问权限: 某些API开启了校验访问权限, 则需要应用开发者到蓝鲸开发者中心申请 应用调用该API的权限, 审批通过后, 这个蓝鲸应用才能调用这个 API, 否则会返回无权限; 注意: 校验访问权限要求该 API 开启 应用认证, 网关需要拿应用认证通过后的bk_app_code进行权限校验
• access_token: 蓝鲸的 bkauth(旧版本的ssm) 等服务, 提供了access_token签发, 支持签发 应用身份access_token(代表一个已认证应用) 以及 应用+用户身份 access_token (代表一个已认证应用+已认证用户); 在无用户登录态/定时任务/脚本等调用网关 API 的场景, 可以使用access_token替代 bk_app_code/bk_app_secret/bk_token

认证 Header 头

X-Bkapi-Authorization: {}

示例:

# 调用目标 API 开启: 应用认证+用户认证
X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}

# 调用目标 API 开启: 应用认证
X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y"}

# 调用目标 API 开启: 用户认证
X-Bkapi-Authorization: {"bk_token": "z"}

# 使用access_token
X-Bkapi-Authorization: {"access_token": "z"}

curl 请求示例:

curl 'http://bkapi.example.com/prod/users/'
    -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}'

认证报错信息

message: app code cannot be empty

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"app code cannot be empty\"]",
  "result": false
}

• 原因: 没有提供 X-Bkapi-Authorization 头或者 X-Bkapi-Authorization头中没有 bk_app_code
• 处理: 提供 X-Bkapi-Authorization 头并且里面包含 bk_app_code

message: please provide bk_app_secret or bk_signature to verify app

status: 400


{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"please provide bk_app_secret or bk_signature to verify app\"]",
  "result": false
}

• 原因: X-Bkapi-Authorization头中没有 bk_app_secret
• 处理: X-Bkapi-Authorization 头里面包含 bk_app_secret

message: bk_app_code or bk_app_secret is incorrect

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"bk_app_code or bk_app_secret is incorrect\"]",
  "result": false
}

• 原因: bk_app_code + bk_app_secret 校验失败, 不合法
• 处理: 确认发起请求头中 bk_app_code / bk_app_secret 合法, 与蓝鲸 PaaS 平台或运维签发给到的一致

message: user authentication failed, please provide a valid user identity, such as bk_username, bk_token, access_token

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"user authentication failed, please provide a valid user identity, such as bk_username, bk_token, access_token\"]",
  "result": false
}

• 原因:
  • 没有提供X-Bkapi-Authorization 头
  • 头里面没有包含 bk_token or access_token
  • bk_token 不合法(会到蓝鲸统一登录校验, 校验失败, 可能是非法的bk_token或已过期)
  • access_token不合法(会到蓝鲸bkauth/ssm校验, 校验失败, 可能是非法的access_token或已过期)
• 处理: 确认 bk_token/access_token 存在并且合法

message: user authentication failed, the user indicated by bk_username is not verified

status: 400

{
    "code":1640001,
    "data":null,
    "code_name":"INVALID_ARGS",
    "message":"Parameters error [reason=\"user authentication failed, the user indicated by bk_username is not verified\"]",
    "result":false
}

• 原因：
  • 提供的用户认证信息里面，只有 bk_username，没有 bk_token, access_token 等能表示用户真实身份的信息，而 bk_username 不能真实表示用户真实身份（非 verified)
• 处理：网关"插件配置”中，查找插件“免用户认证应用白名单(不推荐)”，在该插件配置中，将应用添加到免用户认证应用白名单中。该插件不推荐使用，非官方网关，暂可能无法添加此插件。

message: App has no permission to the resource

status: 403

{
  "code": 1640301,
  "data": null,
  "code_name": "APP_NO_PERMISSION",
  "message": "App has no permission to the resource",
  "result": false
}

• 原因: 网关 API 开启了 校验访问权限, 调用方bk_app_code无权限调用(没有申请权限或者权限过期)
• 处理: 申请权限/权限续期

权限

API 网关：如何添加自定义编码组件

Description

不同的版本，有不同的处理方案。先获取服务版本号（容器化 chart version，二进制 app version），再根据版本号找对应的方案进行处理。

容器化版本

• 1. chart README.md 常见问题中，2. 如何导入自定义编码组件 部分有介绍，请参考，将组件代码添加到容器
• 2. 在网关管理端 -> 组件管理中，新建组件

二进制版本（新版二进制版本，将默认使用旧版 open-paas/esb 服务，请检查链路确认）

在 ESB 项目的 components/generic/apis 目录下，将组件代码 copy 到此目录下，并创建对应的组件。

旧版二进制版本 (open-paas/esb)

• 在 ESB 项目的 components/generic/apis 目录下，将组件代码 copy 到此目录下，并创建对应的组件。

文档阅读, 搭建环境

• 梳理APIGateway的模块划分
• 搭建APIGateway的本地测试环境
• 体验APIGateway运行的整体流程, 是否流程

---

M06后2天处理

feat: 权限管理功能

Description

权限管理功能

API 网关：采用认证信息标准化方案调用 API

背景

蓝鲸认证信息，是用于标识蓝鲸应用和用户的数据；调用者访问接入蓝鲸 API 网关的云 API 接口时，如果云 API 接口需要认证应用或用户，则请求时需要携带这些认证信息，才能正常发起请求。

目前，API 网关支持 2 种传递认证信息的方案：

• 方案一： 认证数据与请求参数放在一起，如放在 querystring、body 中 （不推荐）
• 方案二： 认证数据放在请求头 X-Bkapi-Authorization 中 （推荐）

采用方案一时，API 网关需要处理额外的任务，包括解析 querystring 和多种格式的 body（如 json、x-www-form-urlencoded、form-data 等）来获取认证信息，以及在向后端转发请求时，删除请求参数中的敏感数据（如 bk_app_secret、bk_token 等）。这存在以下问题：

• 1. API 网关需要解析请求参数，这对性能造成了重大消耗
• 2. 在 API 网关删除敏感参数的过程中，实际的请求参数被修改
• 3. 在整个请求过程中，请求参数可能被记录在日志中，带来敏感信息泄露的潜在风险

因此，推荐采用第二种方案进行认证信息的传递。目前正在使用第一种方案的调用者，也需要切换至第二种方案，并且去除请求参数中的蓝鲸认证信息（迁移方案参考下文）。

认证信息标准化方案

认证信息的标准化方案，即上文提到的第二个方案，可通过请求头 X-Bkapi-Authorization 传递认证信息，值为 JSON 格式字符串。

**注意：**二进制版本 open-paas/esb >= 2.12.20 支持 X-Bkapi-Authorization，应用调整时，需关注

• 1. 方案一：标注有此版本依赖；对应的蓝鲸运营大版本为 >= 6.0.5 版本，如果 open-paas 版本 < 2.12.20，访问 esb 组件会失败
• 2. 方案二：应用通过功能开关，设置是否将认证参数多传一份到请求参数

示例： 使用 curl 命令，请求时携带认证请求头

# 调用目标 API 开启: 应用认证+用户认证
curl -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}' "http://example.com/api"
# 用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

# 调用目标 API 开启: 应用认证
curl -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y"}' "http://example.com/api"
# 应用态 access_token 或用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

# 调用目标 API 开启: 用户认证
curl -H 'X-Bkapi-Authorization: {"bk_token": "x"}' "http://example.com/api"
# 用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

示例： 使用 Python 语言和 requests 模块

import json
import requests

# 认证应用 + 用户
requests.get(
    "http://example.com/api",
    headers={
        "X-Bkapi-Authorization": json.dumps({
            "bk_app_code": "demo",
            "bk_app_secret": "secret",
            "bk_token": "your_token",
        })
    },
)

requests.get(
    "http://example.com/api",
    headers={
        "X-Bkapi-Authorization": json.dumps({"access_token": "abc"})
    },
)

X-Bkapi-Authorization 请求头所支持的全部字段如下表所示：

字段	类型	版本	描述
bk_app_code	string	开源版/上云版	应用 ID，可以通过蓝鲸开发者中心 -> 应用基本设置 -> 基本信息 -> 鉴权信息获取；网关 SDK 默认已添加
bk_app_secret	string	开源版/上云版	安全秘钥，可以通过蓝鲸开发者中心 -> 应用基本设置 -> 基本信息 -> 鉴权信息获取；网关 SDK 默认已添加
bk_token	string	开源版	用户登录态，用于认证用户；登录蓝鲸，对应 Cookies 中 bk_token 字段的值；提供 bk_token 时，不需要再提供 bk_username
bk_ticket	string	上云版	用户登录态，用于认证用户；登录蓝鲸，对应 Cookies 中 bk_ticket 字段的值；提供 bk_ticket 时，不需要再提供 bk_username
bk_username	string	开源版/上云版	当前用户用户名；仅用于应用免用户认证的场景中，用于指定当前用户。应用需向网关管理员申请免用户认证白名单，由于用户未经过校验，存在安全风险，请谨慎使用
access_token	string	上云版	用户态 access_token，或应用态 access_token

注意：

• 1. 认证应用：应用态 access_token、用户 access_token、 bk_app_code + bk_app_secret 三选一即可
• 2. 认证用户：用户态 access_token、bk_token 或 bk_ticket、bk_username 三选一即可；如果需要使用 bk_username，则应用需向网关管理员申请免用户认证

如何迁移到标准化认证信息方案

直接调用

• 请根据上文描述，将蓝鲸认证信息，从请求参数（querystring、body）中，切换到请求头 X-Bkapi-Authorization 中
• 旧版中，如果使用 app_code, app_secret, username 等蓝鲸认证参数，可将其原样迁移到 X-Bkapi-Authorization 中，或将其转换为新字段：app_code => bk_app_code, app_secret => bk_app_secret, username => bk_username，如 {"app_code": "x", "app_secret": "y", "username": "z"} 可转换为 {"bk_app_code": "x", "bk_app_secret": "y", "bk_username": "z"}

使用蓝鲸网关SDK/组件 SDK

• 使用开源版组件 API SDK：bkapi-component-open
• 网关 API SDK：如果当前请求存在问题，请联系网关管理员生成新版 SDK，并按照网关使用文档，切换到新版调用方式
• 上云版使用非 open SDK，需待 SDK 升级版本后，应用升级 SDK 版本，如 ieod 版本 SDK

注意：

1. 二进制版本 open-paas/esb >= 2.12.20 支持 X-Bkapi-Authorization，应用调整时，需关注
   • 1.1 方案一：标注有此版本依赖；对应的蓝鲸运营大版本为 >= 6.0.5 版本，如果 open-paas 版本 < 2.12.20，访问 esb 组件会失败
   • 1.2 方案二：应用通过功能开关，设置是否将认证参数多传一份到请求参数
2. bk_login 系统接口，参数 bk_username、bk_token 属于接口的普通参数，非网关的认证参数，需要放到请求参数中；如 bk_login/get_user, bk_login/is_login 组件
3. 组件系统 data 的接口，认证参数放到 x-bkapi-authorization 后，因后端接口逻辑要求，需要在请求参数中多传一个 bk_app_code（不需要传 bk_app_secret)

版本依赖

• 二进制版本：open-paas/esb >= 2.12.20
  • ESB 此版本开始支持请求头 X-Bkapi-Authorization 传递认证参数; 需要标注有此版本依赖，如果不能标注，可单独反馈，确认处理方案；对应的蓝鲸运营大版本为 >= 6.0.5 版本
• 容器化版本: 所有版本均支持

概念 & FAQ

请参考：#74

API 网关：请求日志查询

Description

本文档介绍，调用 API 后，如何查询请求的日志记录。容器化及二进制版本，网关都提供了对应的 API 请求日志采集功能，开启后，可采集及查询 API 请求日志记录。

容器化版本

网关 API

1. 如何启用网关 API 的日志采集

第一步：chart values.yaml 中，通过 apigateway.bkLogConfig 配置是否启用日志采集，及日志上报数据ID；将 enabled 设置为 true，并在日志平台 bklog "管理" -> "自定义上报" 中，创建 3 个 自定义上报数据ID，并配置 stdoutDataId、containerDataId、fileDataId。此时日志平台 bklog 将会采集网关请求流水日志文件 /usr/local/apisix/logs/access.log 中的请求流水日志。

第二步：采集项 index 默认应为 chart values.yaml 中 dashboard.bkApigwApiLogEsIndex 中配置的：2_bklog_bkapigateway_apigateway_container*（待确认）

第三步：观察日志平台 bklog 中是否采集到日志（需有请求量），并为其配置日志清洗。因请求流水为一个 json 字符串，需利用日志平台的清洗规则，将 json 串中日志解析为日志字段。

清洗模板参考：

2. 如何查询网关 API 的请求日志

在日志平台检索中，可查询清洗后的请求日志记录，index 为：[采集项]bkapigateway-apigateway-container(2_bklog.bkapigateway_apigateway_container)

组件 API

第一步：chart values.yaml 中，通过 bkEsb.bkLogConfig 配置是否启用日志采集，及日志上报数据ID；将 enabled 设置为 true，并在日志平台 bklog "管理" -> "自定义上报" 中，创建 2 个 自定义上报数据ID，并配置 stdoutDataId、containerDataId。此时日志平台 bklog 将会采集 ESB 请求流水日志文件 /apps/logs/esb_api.log 中的请求流水日志。

第二步：采集项 index 默认应为 chart values.yaml 中 dashboard.bkEsbApiLogEsIndex 中配置的：2_bklog_bkapigateway_esb_container*（待确认）

第三步：观察日志平台 bklog 中是否采集到日志（需有请求量），并为其配置日志清洗。因请求流水为一个 json 字符串，需利用日志平台的清洗规则，将 json 串中日志解析为日志字段。

清洗模板参考：

二进制版本

二进制版本，网关提供了基于 filebeat + logstash 的日志采集方案。需联系运维同学部署此日志采集方案。部署后，日志将采集到对应的 Elasticsearch 中，如需在线查看请求日志，可联系运维部署一个 Kibana。(日志采集方案在 paas_plugins 项目)

默认的 Elasticsearch index：

• 网关 API：bkapigateway_apigateway_api_log
• 组件 API：bkapigateway_esb_api_log

API网关：如何从 chart 0.4.x 迁移到 1.12.x

Description

0. 预准备：values.yaml

1.10.x 新版本增加了 ETCD 依赖，请提前准备。

更新 values：

• [必须] 将 etcd 信息配置到 externalEtcd 中；
• [必须] 配置 defaultMicroGatewayInstanceId：一个 uuid 字符串，创建后不能修改
• [推荐] 在 bkrepo 中创建名为 bk_apigateway 的项目和用户，将用户名密码更新到 bkrepoConfig，不配置将影响网关 SDK 功能；
• [推荐] 增加一个日志采集的 DataId，用于存储网关内部模块日志，配置到 apigateway.bkLogConfig.fileDataId，不配置会复用标准输出的 DataId；
• [推荐] 梳理访问链路的中间代理地址，将地址列表整理到 apigateway.pluginMetadata["bk-real-ip"].trustedAddresses 中，如不配置，将会影响 IP 访问控制插件和客户端 IP 获取的逻辑；
• [推荐] 添加 operator 模块个性化配置
• [推荐] 删除 apiSupport 配置，已合并到 dashboard 模块
• [推荐] 删除 caddy 配置，已合并到 bk-esb 模块

1. 金丝雀方案：基于 Ingress Nginx 的双 Release 发布

1.1 备份数据库

因灰度会变更 database，所以灰度前，需要备份数据库：bk_esb，bk_apigateway，以便于出现问题时进行回滚。

• 准备恢复数据的指令，恢复数据后，重启 Release bk-apigateway 的 Pod 即可

1.1 准备 values-canary.yaml

准备 values-canary.yaml，示例如下：

registerCrds: false

apigateway:
  bkapiServiceName: ""
  # 初始时，不创建新 Pod
  replicaCount: 0
  ingress:
    annotations:
      # 标记此 Ingress 为金丝雀发布
      nginx.ingress.kubernetes.io/canary: "true"
      # API 服务，设置灰度比例，范围：0 ~ 100。初始时，不灰度流量
      nginx.ingress.kubernetes.io/canary-weight: "0"

dashboard:
  ingress:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      # 前端项目，用户手动设置浏览器 Cookies：canary=always，则灰度此用户的请求
      nginx.ingress.kubernetes.io/canary-by-cookie: "canary"
      # 设置权重比例为 100，不灰度前端项目，直接发布
      # nginx.ingress.kubernetes.io/canary-weight: "100"

dashboardFe:
  ingress:
    annotations:
      nginx.ingress.kubernetes.io/canary: "true"
      # 前端项目，用户手动设置浏览器 Cookies：canary=always，则灰度此用户的请求
      nginx.ingress.kubernetes.io/canary-by-cookie: "canary"
      # 设置权重比例为 100，不灰度前端项目，直接发布
      # nginx.ingress.kubernetes.io/canary-weight: "100"

1.2 发布金丝雀 Release

# values.yaml 为正常发布的配置，values-canary.yaml 为金丝雀发布的特殊配置
helm install bk-apigateway-canary bkee/bk-apigateway -f values.yaml -f values-canary.yaml -n blueking

1.3 检查 bk-esb 组件数据，并将其同步到 apigateway

新版中，用户访问组件 API，请求流程如下：user -> apigateway -> bk-esb -> backend service。
因此，需要将 bk-esb 组件数据同步至 apigateway；为方便二者数据的映射，bk-esb 中的部分组件需要拆分或调整。

# 进入 dashboard 容器
kubectl exec -it bk-apigateway-canary-dashboard-<xxx> -- bash -n blueking

# 拆分组件：检查组件中同一 path 是否存在 method=""，及其它方法的组件，此类组件需要拆分或调整
# 执行过程中：部分组件直接修改，部分组件会要求确认；如无输出表示无需处理
python manage.py split_component_method [--dry-run]
- --dry-run: 不实际修改数据，可用于测试

# 同步 bk-esb 组件到 apigateway；此指令耗时 2 ~ 5 分钟，请等待
python manage.py sync_to_gateway_and_release

# 同步组件权限数据到 apigateway
python manage.py sync_esb_permissions_to_gateway

验证 bk-esb 组件。登录网关管理端 http://apigw.__bk_domain__，进入网关 bk-esb 管理页

• 基本设置 => 资源管理，检查网关 bk-esb 中资源是否为空
• 权限管理 => 应用权限，检查网关 bk-esb 权限数据是否正确

1.4 同步 dashboard 数据到 etcd

dashboard 创建成功后，进入 dashboard 同步网关数据到 etcd。

• 0.4.x 为 Go 版本网关，不依赖 etcd；1.10.x 为 apisix 网关，依赖 etcd。切换时，需提前为 1.10.x apisix 网关准备 etcd 数据。

# 进入 dashboard 容器
kubectl exec -it bk-apigateway-canary-dashboard-<xxx> -- bash -n blueking

# 执行 django command，将网关数据同步到 etcd
python manage.py sync_releases_to_shared_micro_gateway_parallel

1.4 灰度发布

• 初始时，金丝雀 deploy bk-apigateway-canary-apigateway 未创建 Pod
• 手动将金丝雀 deploy bk-apigateway-canary-apigateway 的 spec.replicas 改为 1，创建 1 个 Pod
• 手动将金丝雀 ingress bk-apigateway-canary-apigateway metadata.annotations."nginx.ingress.kubernetes.io/canary-weight" 改为 10，灰度 10% 的流量。请通过请求流水观察 API 网关服务是否正常
• 手动将金丝雀 deploy bk-apigateway-canary-apigateway 的 spec.replicas 改为 3，创建 3 个 Pod
• 手动将金丝雀 ingress bk-apigateway-canary-apigateway metadata.annotations."nginx.ingress.kubernetes.io/canary-weight" 改为 20，灰度 20% 的流量
• [可选] 浏览器中打开网关管理端，手动在 Cookies 中设置 canary=always，测试管理端功能
• 按正常流程发布原 Release bk-apigateway。待原 Release 更新成功后，调整 ingress bk-apigateway-canary-apigateway，将 canary-weight 调整为 0
• 检查 bk-apigateway-canary-bk-esb-<xxx>、bk-apigateway-canary-apigateway-<xxx> 中是否仍有流量
• 如上一步检查，bk-apigateway-canary 中 apigateway、bk-esb 无业务流量，则可以删除金丝雀 Release，灰度结束

参考指令：

# 编辑 deploy
kubectl edit deploy bk-apigateway-canary-apigateway -n blueking

# 编辑 ingress
kubectl edit ingress bk-apigateway-canary-apigateway -n blueking

# 检查 bk-esb pod 是否有流量
kubectl logs bk-apigateway-canary-bk-esb-<xxx> --tail 20 -f -n blueking
# 检查 apigateway 是否有流量
kubectl exec -it bk-apigateway-canary-apigateway-<xxx> -- bash -n blueking
tail -f /usr/local/apisix/logs/access.log

# 删除金丝雀 Release
helm uninstall bk-apigateway-canary -n blueking

feat: API网关-资源版本

Description

API网关-资源版本

API 网关版本升级依赖关系

升级依赖关系：

0.4.x -> 1.12.x -> 1.13.x -> 1.14.x及更高版本

注意，严格按照顺序进行升级，不可跳过中间版本

• 0.4.x -> 1.12.x 参考 #189
• 1.12.x -> 1.13.x 直接升级即可，会自动进行数据迁移；并且会自动打版本/发布
• 1.13.x -> 1.14.x 直接升级即可，会删除不用的模块，去掉一批兼容逻辑等

API 网关：如何手动更新配置类组件（confapis）

Description

目前 API 网关支持的组件中，组件系统 JOB、NODEMAN 等官方组件，以配置类组件方案维护组件配置。系统方如 JOB，维护组件的 yaml 配置，交付给 API 网关管理员，API 网关管理员将其打包发布。

在配置类组件 API 的测试阶段，为了更快地更新、测试组件 API，也可手动更新配置类组件，不需要 API 网关打包发布。

容器化版本

1. 准备待更新的组件 yaml 配置

2. 将 yaml 拷贝到 esb 的一个容器，指令示例：

   # 组件 yaml 配置在容器内目录 /app/components/confapis 下，不同组件系统的 yaml 文件名和目录不同，请登录容器查看；
   # 下例以 job 为例
   kubectl cp job.yaml blueking/bk-apigateway-bk-esb-<xxx>:/app/components/confapis/jobv3/job.yaml -c bk-esb
   

3. 登录 esb 容器，执行 django command，将组件数据同步到 db

   # 进入容器
   kubectl exec -it bk-apigateway-bk-esb-<xxx> -n blueking -- bash
   
   # 执行 django command，将 yaml 数据同步到 db
   python manage.py sync_data_at_deploy
   

4. 将组件数据，同步到 API 网关 bk-esb

   # 进入 dashboard 容器
   kubectl exec -it bk-apigateway-dashboard-<xxx> -n blueking -- bash
   
   # 将组件谁，同步到 API 网关 bk-esb；此指令耗时 2 ~ 5 分钟，请等待
   python manage.py sync_to_gateway_and_release
   

5. 验证 bk-esb 组件。登录网关管理端 http://apigw.__bk_domain__，进入网关 bk-esb 管理页

   • 基本设置 => 资源管理，检查网关 bk-esb 中是否包含待更新的资源

6. 测试组件

   • 更新 2 分钟后，测试组件访问是否正常

二进制版本

二进制版本，默认使用的 open-paas/esb 版本，请检查是否使用此版本。

1. 准备待更新的组件 yaml 配置

2. 进入二进制版本的”中控机“，通过”中控机“将组件配置文档分发到 open-paas/esb 服务部署服务器

   • 进入中控机的 /data/src/open_paas/esb/ 目录，配置类组件放置在 components/confapis 目录下
   • 将组件 yaml 拷贝到合适位置（不同系统的目录、文件名不同）
   • 执行指令，将组件 yaml 配置，同步到部署 open-paas/esb 的服务器，如：/data/src/open_paas/esb/ 下

     # 中控机执行
     /data/install/bkcli sync paas

3. 登录所有部署 open-paas/esb 的服务器，同步组件配置到项目安装目录，并重启 open-paas/esb（更新 yaml 配置，重启 open-paas/esb，每台部署此服务的机器都需执行）

   如何登录 open-paas/esb 服务器

   # 中控机执行(登录其中一台)
   source /data/install/utils.fc
   ssh $BK_PAAS_IP
   
   # 获取所有部署 open-paas/esb 的服务器（如果只有一台，执行上面的指令即可登录部署 open-paas/esb 的服务器）
   grep paas /data/install/install.config
   ssh <ip>

   在部署 open-paas/esb 的服务器上，同步组件 yaml 配置到部署目录

   # 具体目录路径请以实际为准
   bk_src_dir=/data/src
   bk_install_path=/data/bkce
   pcmd -m paas "rsync -a --delete --exclude=media $bk_src_dir/open_paas/esb/ $bk_install_path/open_paas/esb/"
   /data/install/bkcli render paas

   在部署 open-paas/esb 的服务器上，重启 open-paas/esb 服务

   pcmd -m paas "systemctl restart bk-paas-esb.service"

4. 登录一台 open-paas/esb 服务器，执行 django command，将组件数据同步到 db （仅需执行一次）

   # 中控机执行
   source /data/install/utils.fc
   # 进入部署 open-paas/esb 的服务器
   ssh $BK_PAAS_IP
   
   # 部署 open-paas/esb 的服务器执行
   bk_install_path=/data/bkce
   workon open_paas-esb
   export BK_ENV=production
   export BK_FILE_PATH=$bk_install_path/open_paas/cert/saas_priv.txt
   python manage.py sync_data_at_deploy

bug: 【api网关】权限管理-应用权限导出的应用权限，在Excel内中文显示乱码

Current Behavior

如图，应用权限导出后，在excel中打开，中文会乱码。在txt或者wps中打开是正常的

Expected Behavior

No response

Error Logs

No response

Steps to Reproduce

1、进入到API网关-应用权限
2、导出

Version and Environment

• 蓝鲸版本号 (the version of BlueKing platform): V1.10.0-beta.4
• 容器化部署还是二进制部署 (deployed on Kubernetes or using binary files):容器化
• 二进制部署请提供网关版本号 (the version of bk-apigateway, required for binary distribution):
• 容器化部署请提供 (provide the following information, required for Kubernetes helm chart distribution):
  • bk-apigateway helm chart version:bk-apigateway-1.10.0-beta.5-cw
  • values.yaml 中是否做了修改 (whether you have modified the values.yaml): 否
  • values.yaml 中的配置, 注意去除敏感信息 (the contents of the values.yaml file, remember to remove any sensitive information):

feat: API网关-插件管理

Description

API网关-插件管理

doc: 网关协作开发交付规范

develop & self-testing

• 每个开发都要有一套完整的开发环境
• 修改helm charts之后, 必须dry-run确认, 并且在开发环境部署验证, 避免低级错误, 避免在后面的环节才发现问题返工
• 各自功能提 PR 前, 必须做好自测(可以构建dev镜像顶掉目标pod, 验证完整逻辑), 避免低级问题出现
• 重要: commit message必须符合规范, 清晰, 关联对应的issue; 会直接用于生成 release log

PR

• 需要填写 PR 对应的变更点, 以便让reviewer更好理解和处理, 方便后续追溯
• 涉及功能修改的 PR 必须包含单元测试
• PR 的所有检查及单元测试必须通过
• PR 的代码风格检查必须通过

Code review

• 一个 PR 需要两个 reviewer approved
• 所有conversation必须resolved
• conversation 点 resolve的时候, 必须填评论, 已修改可以填done, 不修改需要给到理由 => 不要直接点resolve (这样可能有的问题就沉掉了)