你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

使用 APIOps CLI 自动执行 API 管理配置

Azure API 管理
Azure DevOps
Azure Pipelines
GitHub

APIOps 是一种将 GitOps 和 DevOps 的概念应用于 API 部署的方法。 此体系结构演示如何使用 APIOps CLI 通过基于 Git 的工作流提取、查看和提升Azure API 管理配置。 使用此方法管理 API 生命周期、提高 API 质量并维护已批准的更改的可审核记录。

体系结构

下图演示了高级 APIOps CLI 配置提升工作流。 团队先在 Git 中审查 API 管理工件,然后由持续集成和持续交付(CI/CD)管道将已批准的配置部署到目标 API 管理环境。

APIOps 提升工作流关系图,其中提取工件或代码优先工件作为 Git 的输入,之后依次进行审查、CI/CD 试运行,并部署到目标 API Management 环境。

下载此架构的Visio 文件

Workflow

API 管理配置可以通过提取现有的 API 管理配置开始,也可以通过编写与 CLI 兼容的 API 管理项目文件开始。 该操作流程从这两种工件输入中的任意一种开始。 这两个路径都会导致相同的拉取请求、验证、审批和部署过程:

  • (A)先提取: API 运维人员针对现有的 API Management 实例运行 apiops extract,以在其本地 Git 检出分支中创建 API Management 构件文件。 操作员使用这些工件来提出基线或记录已获批准的配置更改。

  • (B)代码优先:API 开发人员在其本地 Git 检出分支中编写或更新与 APIOps CLI 兼容的 API 规范、信息文件、策略以及相关的 API 管理工件。

使用以下任一输入的生命周期:

  1. 创建配置更改。 在首次签入提取工件或代码优先创建的工件后,API 配置存储库将成为 API Management 配置工件的权威事实来源。 存储库维护每个部署的版本历史记录和审核记录。 若要进行更改,API 操作员或开发人员从 API 配置存储库中的受保护分支创建分支,并创建一个与 API 相关的逻辑更改。

  2. 查看并验证更改。 操作员或开发人员创建一个拉取请求,以将自己的分支合并到受保护分支中。 API 合同、策略和 API 管理配置的指定负责人和审阅者会对拉取请求进行审查。 CI/CD 系统运行以下检查和测试:

    • API 规范静态检查
    • 根据已批准的协定检测中断性变更
    • 规范和存储库内容的安全扫描
    • 用于验证预期行为、身份验证、策略效果和后端依赖项的 API 测试

    这些检查不需要Microsoft工具。 团队使用任何合适的工具来满足其组织的支持、安全性和许可要求。

  3. 批准不可变的部署输入。 所需的所有者或审阅者批准拉取请求,经过授权的存储库维护者会在所有必需的检查和评审通过后合并已审核的更改。 合并的不可变提交及其受保护的分支项目将成为存储库的可审核事实来源。

    团队保护受保护的存储库分支免受直接推送,需要对敏感目标进行环境或服务连接批准,并使用单独的最小特权标识进行提取和发布。 他们记录已批准的提交及其拉取请求、评审和验证结果,以便实现可审核性。

  4. 预览部署情况。 CI/CD 管道使用相同的目标和 覆盖文件,针对已批准的提交运行 apiops publish --dry-run,而不进行发布。 发布审批者审查试运行所创建、更新、删除或跳过的资源。 团队将成功的试运行视为部署入口,而不是自动 API 测试的替代方法。

  5. 发布并推广。 在试运行通过验证后,CI/CD 管道使用 apiops publish 来发布同一个经过审核的提交。 针对多个环境,平台团队会保持共享构件的稳定性,并使用经过审查的覆盖配置文件来设置后端 URL、资源 ID 和密钥引用等值。 团队先在非生产环境中提升提交,然后再提升到生产环境,并阻止多个管道同时写入同一目标。

    注释

    该配置支持 工作区子级覆盖项,但在发布时不会应用这些覆盖项。 发布操作仅将覆盖设置应用于工作区容器本身。 不要依赖工作区子级覆盖配置来提升特定于环境的工作区 API、后端、命名值或其他子资源。 验证这些资源的替代提升方法,或将提升操作推迟到 工作区范围的覆盖属性未应用 这一已知问题得到解决之后。

  6. 在部署后验证和协调。 发布后,运营团队将运行自动冒烟和回归测试、监视 API 管理和后端运行状况,并将部署的结果与批准的提交进行比较。 团队通过拉取请求调查并解决意外变更,而不是直接修改生产环境。

    如果 API 操作员直接在 API 管理中进行了批准的紧急更改,则操作员必须在 Git 签出中运行提取、查看和提交其分支上的项目更改、推送分支并打开拉取请求。 所需的所有者或审阅者必须评审和批准拉取请求,并且授权的存储库维护者必须将其合并,以便存储库保持权威性。

组件

  • API 管理 是一种托管服务,可为后端服务创建一致的 API 网关。 在此体系结构中,它提供 APIOps CLI 提取的源配置,以及 CLI 发布批准的 API 定义、策略、产品、诊断、命名值和其他受支持的配置的目标环境。

  • APIOps CLI 是一个开源项目,为有意见的 APIOps 方法提供工具。 在此体系结构中,它将 API 管理配置提取到项目文件、将项目发布到 API 管理,并且可以搭建 CI/CD 工作流基架。

  • Git 存储库存储 API 管理项目,并在适用的情况下存储 API 合同。 它提供管道部署的评审历史记录和已批准的真相来源。

  • CI/CD 系统使用工作负载标识或其他受支持的非交互式凭据来运行验证、提取和发布流程。 在此体系结构中,GitHub Actions或Azure Pipelines定义 CI/CD 工作流。

备选方法

您可以根据工作负载的功能性和非功能性要求,使用其他 Azure 服务或方法来替代或补充此架构。 请考虑以下替代方案和权衡。

Bicep或 Terraform 和 APIOps 可以为同一解决方案的不同部分提供服务。 拥有 API 管理配置和基础结构的团队可以使用基础结构即代码(IaC)来预配 API 管理服务及其支持基础结构,并使用同一 IaC 管道来管理 API 管理配置。 当基础结构和配置更改并一起部署,以及何时参数可以表达环境之间的差异时,请选择此方法。

当 API 定义、策略和相关配置具有独立于服务基础结构的独立所有者或发布生命周期时,请使用 APIOps 模式。 如果需要提取现有配置、查看以 API 为中心的项目,或者跨多个环境或 API 管理实例提升相同的已批准配置,APIOps 也适用。 更频繁的 API 和策略更改或更多环境会增加此专用工作流的价值。

这些因素没有固定阈值。 应主要根据所有权、评审要求和部署边界来做出决定。 对于具有较低更改率的较小 API 资产,请从手动拉取请求工作流开始,并在建立存储库基线和审批过程后添加提取计划或部署自动化。

方案详细信息

APIOps 使用版本控制来管理 API,并创建 API 定义、策略、产品、诊断和其他 API 管理配置的更改的审核线索。 提前和更频繁地查看更改有助于团队在部署之前识别与 API 标准的偏差。 随着更多 API 使用相同的过程,团队可以提高其 API 资产的一致性。

此工作流将 API 管理配置部署到 API 管理实例。 它不会部署 API 后端、应用程序计算或数据资源、网络或 API 管理服务基础结构。 使用单独的受治理的 IaC 和应用程序管道来部署这些层。

此解决方案可帮助团队:

  • 掌握环境和 API 管理实例的概况。
  • 跟踪对 API 和策略的关键更改。
  • 为已批准的部署创建审核线索。
  • 协调源自存储库外部的已批准更改。

选择构件来源和所有权

在实现自动化部署之前,请从以下工件进入存储库的方式及其所有者中进行选择:

  • 先提取: 提取已知良好的 API 管理实例,以建立初始工件基线。 在将该存储库视为权威来源之前,请先检查已提交的生成产物。
  • 代码优先: 将 API 合约(例如 OpenAPI 描述)与应用程序源代码或 APIOps 存储库一并保存。 定义由谁将该契约转换为由管道发布的 API 管理工件。 使用非生产 API 管理实例验证预期的导入和工件工作流。 不要假定任意源布局可由 CLI 直接使用。
  • 共同责任: 确定对策略、产品、诊断、命名值和 API 定义的更改是由 API 开发人员、平台运营人员还是双方共同负责。 基线获批后,所有更改都应通过同一存储库和评审流程进行。

可能的用例

  • 开发和管理 API 的组织,包括那些仅通过 API Management 公开单个 API 的组织。

  • 高度管控的行业,如保险、银行、金融和政府,需要可追溯的审查和部署记录。

注意事项

这些注意事项实现 Azure Well-Architected 框架的支柱,这是一组指导原则,可用于提高工作负荷的质量。 有关详细信息,请参阅 Well-Architected Framework。

Reliability

可靠性有助于确保应用程序能够履行对客户的承诺。 有关详细信息,请参阅 可靠性设计评审清单。

对于非中断性 API 更改,请使用 API 管理修订 来部署和测试非当前修订,然后再使其保持最新状态。 如果在发布后验证失败,请还原以前的修订为当前版本。 使用 API 版本进行中断性合同更改,以便现有使用者可以继续使用早期版本。

使 API 管理配置变更与每个 API 后端的部署策略保持协调。 还原 APIOps 提交只会还原该提交所代表的配置。 它不会恢复不兼容或不可用的后端。 记录构成每个已知良好部署的 APIOps 提交、API 管理修订和后端版本。 在非生产环境中测试完整的回滚过程,包括策略、命名值、机密引用、依赖项和后端兼容性。

安全性

安全性为故意攻击和滥用有价值的数据和系统提供保证。 有关详细信息,请参阅 安全设计评审清单。

使用存储库和管道作为应用 API 管理更改的正常路径。 开发人员和操作员不需要对生产 API 管理实例进行持久写入访问。 仅在必要时授予提升的访问权限,并且仅在有限的时间内授予权限。 将由此产生的任何更改同步到存储库。

使用以下机制来保护存储 API 管理项目的 Git 存储库:

  • 拉取请求审查: 保护用于部署配置的分支,并要求由相应的审查者进行审查。
  • 凭据隔离: 如果可用,首选联合工作负荷标识。 将特定于环境的机密存储在已批准的机密存储或存储库环境中,而不是存储在项目或管道文件中。
  • 提交完整性: 要求提交带有签名,以验证提交来源。 配置分支保护以防止强制推送和分支删除,需要多重身份验证,以便用户批准或合并更改,并保留部署的提交和拉取请求历史记录。
  • 构件审查:检查提取输出和发布输入内容,查看其中是否包含机密信息、脱敏标记以及非预期的特定于环境的值。 验证更改是否不会扩大 API 访问或削弱策略。

将 APIOps CLI 作为存储库依赖项进行管理。 在 @azure-tools/apiops-cli 中将 固定为已经过测试的版本,提交锁定文件,并使用 npm ci。 在启用生产管道之前,请查看生成的标识设置、变量、触发器和保护规则。

成本优化

成本优化侧重于减少不必要的开支和提高运营效率的方法。 有关详细信息,请参阅 成本优化的设计评审清单。

APIOps CLI 是开源软件,但此方案会产生 API 管理实例和所选源代码管理和 CI/CD 平台的成本。 未提供单个固定估计值,因为 API 管理价格因区域、层、单位计数、容量模型、可用性区域或多区域配置和使用情况而异。 CI/CD 费用还取决于运行器类型、包含的分钟数、并发数、存储空间和保留期。

在Azure定价计算器中创建特定于方案的估计,并在体系结构决策中记录以下假设:

估计输入 待记录的假设
API 管理区域 每个开发、测试、暂存和生产实例的部署区域。
层级和容量 层级或 v2 层级、单元或网关的数量,以及每个环境的运行小时数。
复原能力 任何可用性区域或附加区域部署,包括每个位置中的单元。
基于使用情况的费用 预计的请求或操作,以及任何适用的工作区、自托管网关、网络、监控或数据传输费用。
CI/CD 平台 GitHub 托管、自托管或 Azure Pipelines 代理。 预期的管道运行次数、运行时长、并发数、存储,以及日志或制品保留期限。
源代码管理和许可证 用户数和任何付费GitHub或Azure DevOps计划功能。

使用当前的 API 管理定价详细信息 来选择适用的计费模型。 有关 CI/CD 和源代码管理假设,请参阅Azure DevOps定价和GitHub定价。 导出或捕获计算器估算、其货币、定价日期和所有假设,以便审阅者可以重现和更新它。 在部署前,以及区域、层级、单元数量、环境或管道使用情况发生变化时,重新计算。

卓越运营

卓越运营涵盖了部署应用程序并使其在生产环境中保持运行的运营流程。 有关详细信息,请参阅 针对卓越运营的设计评审清单。

APIOps 使部署可重复,并为更改后分析创建提交历史记录。 标记或以其他方式记录每个环境接收的提交版本,保留流水线日志,并在部署后监视 API 管理实例及其依赖的 API。

在多个环境中,将同一个经过审核的制品提交依次推进到开发、预发布和生产环境。 仅对必须因环境而异的值使用环境覆盖项,并以与构件相同的谨慎程度审查这些文件。 发布时不会应用工作区子级覆盖配置,因此不要将其用于环境提升。 在事件发生前测试回滚流程。 Git 还原仍需要验证和受控发布才能还原 API 管理。

有关 API 级验证以补充工件检查,请参阅 测试 Web API。

CLI 提供 init、extract 和 publish 命令,并可为 GitHub Actions 或 Azure DevOps 管道生成脚手架。 查看 APIOps CLI 文档中的命令详细信息。

从旧版 APIOps 工具包安全地迁移

如果 APIOps 进程使用旧版 APIOps 工具包,请计划升级。 该方法使用单独的提取器和发布器二进制文件以及流水线模板。 APIOps CLI 使用单个 Node.js CLI,但其项目格式旨在与现有工具包项目兼容。 将迁移视为一次受控切换,而不是对生产环境进行原地升级。

  1. 标记已知良好的工具包项目和管道,并将现有发布者保留为回滚选项。 不要更改旧版发布者并在同一部署中引入新发布者。

  2. 在迁移分支中,使用最新版本的 APIOps CLI,并在不使用apiops init的情况下运行--force。 该命令检测冲突的文件并退出,而不是覆盖它们。 比较并有意识地整合生成的管道、身份标识指南、筛选器和覆盖文件。

  3. 将工件与 apiops publish --dry-run和目标环境的覆盖配置结合使用,并应用于非生产 API Management 实例。 查看 CLI 将创建、更新或删除的资源。 测试一个受控的发布,并验证部署的 API、策略、命名值和依赖项。

  4. 不要将发布时不会应用的工作区子级覆盖配置用作迁移或提升设计的一部分。 验证受影响子资源的替代提升方法,或者推迟其迁移,直到未应用工作区范围的覆盖属性这一已知问题得到解决。

  5. 在切换时,仅允许一个发布者写入 API Management 实例。 在启用 CLI 发布器之前,禁用旧版发布器触发器。 部署已评审的提交并监视结果。 在新的工作流成功完成发布周期之前,请保留标记的工具包管道和项目基线。

有关兼容性详细信息和按命令命令迁移示例,请参阅 从 APIOps 工具包迁移。

部署此方案

按照 APIOps CLI GitHub存储库中的 APIOps CLI 文档进行操作。 从非生产 API 管理实例开始,并使用当前的 APIOps CLI 发布指南。 若要开始使用非生产环境,请参阅 如何使用 APIOps CLI 管理 API 管理配置。

贡献者

Microsoft维护本文。 以下贡献者撰写了本文。

主要作者:

若要查看非公开的领英个人资料,请登录领英。

后续步骤