引言
ADC (APISIX Declarative CLI) 是 API7.ai 推出的声明式配置工具,为用户实施 GitOps 提供了便利的工具包。用户可以轻松将其集成到自己的 CI/CD 管道实现 API 生命周期管理,完成 API 的升级和发布。自上次 0.7 版本公开报告发布以来,ADC 已发布 0.8、0.9 和 0.10 三个新版本,在功能、性能和操作体验等方面进行了优化和更新。
ADC 新版本功能介绍
Differ 资源变化检测机制改进
在 0.8 和 0.9 版本引入
我们引入了 Differ(资源变化检测器)的新版本 v3,它在功能和代码质量方面都有很大提升。
新版 Differ 为本地资源引入了默认值合并机制,确保服务器端默认值不会干扰 ADC 的资源变化检查。
当客户端向 API7 企业版或 APISIX Admin API 发送请求创建资源时,服务器端会对提交的请求进行 Schema 校验,在这个过程中一些在 Schema 中标记了默认值但客户端未发送的字段将被自动添加到提交的资源中,因此当我们再次从 API 中读取资源时,它们与最初提交的并不一样。
之前的 ADC 版本将这些资源列为 “已修改” 的资源,进而发送更新 API 请求到 Admin API。该行为为 ADC 带来了一些不确定性,我们已通过这个 Differ 机制解决了这个问题。
默认值合并机制已在 API7 后端上实施,它确保了只有用户修改了本地 YAML 配置时资源差异才被视为修改。
细化 Differ 检测粒度:当前 ADC 将在资源主体和插件维度分别执行资源变化检查,有助于减少检查中的异常行为。
优化了代码质量,简化了冗余代码以提高可理解性。同时修复了一些错误。
资源过滤器
我们添加了两种资源过滤器机制,分别基于资源标签和资源类型。它们可用于在执行获取、差异检查、同步排除不需要的资源。
资源标签过滤器
在 0.8 版本引入
该过滤器根据资源上的 labels 字段进行过滤。用户可通过在命令行上使用 --label-selector key=value
模式的参数开启过滤器。它支持配置多个过滤条件,只有同时符合这些规则的远程资源才会被视为存在,而本地资源将被自动添加上这些标签。
这可以确保我们在一个小范围内进行资源检查和同步,有助于拆分 CI/CD 管道中执行的任务,防止意外的同步导致一些不需要修改的资源被破坏。
资源类型过滤器
在 0.9 版本引入
我们添加了两个新的命令行参数 --include-resource-type <type>
和 --exclude-resource-type <type>
,可以对这两个参数进行多次配置,但需注意 include 和 exclude 这两个参数之间是互斥的。
通过这两个参数,我们可以从当前的操作中过滤特定的资源类型,例如使用 include-resource-type
可以用于设置白名单,选择被纳入操作的资源类型;而 exclude-resource-type
将决定被排除操作的资源类型。
这有助于我们更好地处理不需要频繁变更的资源,例如插件元数据和全局插件规则等。
命令行改进
在 0.9 版本引入
添加 TLS 证书配置
我们向命令行中添加一系列与 TLS 相关的参数项,例如:
--ca-cert-file
用于指定服务器的 CA 证书文件--tls-skip-verify
用于关闭 TLS 服务器证书验证--tls-client-cert-file
和--tls-client-key-file
用于指定 mTLS 客户端证书文件
这些参数有助于 ADC 建立安全加密连接,防止中间人攻击。
添加超时控制字段
我们添加了用于控制 API 调用超时时间的参数 --timeout <duration>
,它支持使用类似 1m30s 的时间长度语法。当某个 Admin API 调用耗时过长或陷入阻塞时,超时机制将会生效,阻止它无限期地等待。
调试模式改进
在 0.9 版本引入
ADC 内部执行资源操作时,需要调用大量的 API。有时我们可能需要查看这些 API 调用以分析它们是否被正确发送,或检查服务器返回的响应是否符合预期。虽然可以通过抓包的方式来实现这一点,但操作起来并不方便,而且在开启 TLS 时还会面临很大困难。
因此我们为 ADC 添加了内置的调试模式,通过 --verbose <integer>
参数可以开启,当设置为 2 时,ADC 会打印内部每一个 API 调用的请求和响应部分以帮助调试。
同时该参数也可以用于隐藏日志,将该值设置为 0 时,它将隐藏除错误外的全部一般日志。
强化远程资源处理逻辑
在 0.9 版本引入
由于 ADC 并非唯一配置服务、路由等资源的方式,用户也可以使用 API7 企业版提供的管理控制台通过简单的操作来实现。这衍生出了一个问题:控制台上的操作会使用随机生成的资源 ID;而 ADC 为了精准定位某个资源,它使用 YAML 配置中的资源名称生成固定的资源 ID。
这意味着如果用户在控制台创建了某个资源,ADC 将无法通过资源 ID 定位到它。ADC 无法修改和删除控制台创建的资源,但是这些资源会一直出现在资源变化检查的变化中,但无法被正确操作。
因此我们优化了API7 后端 ADC 的相关逻辑,如果远程和本地均包含相同名称的资源,但 ID 无法匹配时,ADC 可以正确地删除远程资源,并根据本地配置创建新资源,此时 ID 将是 ADC 根据资源名称生成的,可用于后续的资源查找。API7 控制台的用户将不会受到任何影响,由 ADC 创建的资源仍可以在控制台上查看。
OpenAPI 转换器支持 ADC 扩展字段
在 0.10 版本引入
若想构建 OpenAPI - ADC - API7 的连贯流水线,则需要 OpenAPI 转换器根据我们的需求向 ADC YAML 配置文件中注入所需的字段。
以修改服务中上游的 pass_host 字段为例,之前只能手动使用转换器,将 OpenAPI 转换为 ADC 配置文件,并人工修改 pass_host 字段,再将修改后的文件提交到 Git 仓库,让 CI/CD 管道执行 ADC 同步。这个过程是不连贯的,需要很多人工介入。
现在,通过引入的 x-adc
系列扩展,用户只需要在 OpenAPI 文档中的特定位置写入扩展字段,ADC 就能正确地在生成的配置文件中写入这些字段。借助这些扩展,用户可以直接在 OpenAPI 上修改 ADC 配置中的任何内容,例如添加标签、添加插件、覆盖服务/上游/路由的默认配置。
由此一来,只需要维护一份 OpenAPI 文件,便可一站式地实施 OpenAPI - ADC - API7 流水线,大幅简化了 API 网关配置上的 GitOps 工作流。
总结
由 API7.ai 推出的声明式配置工具 ADC 能帮助企业实现 API 网关的 GitOps 管理,在新版本 0.8、0.9 和 0.10 中,进行了功能优化升级,增加了资源变化监测、过滤等功能,为用户的 API 生命周期管理注入了新动力。这些新特性使得 ADC 能更好地满足企业对 API 网关 GitOps 管理的需求,提高了 API 管理的效率和灵活性。