使用 GitHub 管理你的 NGINX 配置

软件设置、选项和配置有多种不同的形式。 一方面是流畅、反应灵敏的 GUI，旨在直观地提供针对无效状态的保护。 另一端：文本文件。 虽然文本文件因其清晰度、自动化潜力和最低限度的使用要求（您可能打开了几个终端窗口，对吗？）而受到工程师和 DevOps 团队的称赞，但使用它们配置软件也有明显的缺点。 例如，尝试寻找一位未能通过错误配置文本文件而导致软件包崩溃的 Linux 用户。

NGINX 作为唯一的一体化软件代理、负载均衡器、Web 服务器和 API 网关，是现代互联网基础设施的关键组件。 大多数情况下，基础设施都是基于 Linux 内核的操作系统。 为了适应这个生态系统和支持它的专业人士，NGINX 严重依赖基于文本的配置。

F5 NGINX 实例管理器模块长期以来一直是 NGINX 相关配置编排的首选。 它通过直观的用户界面和 API 提供远程批量配置管理的高级功能，并提供支持文档和护栏。 然而，单个 NGINX 配置文件与代码非常相似，并且软件团队已经拥有一个出色的代码管理工具： Git。 Git 为开发人员和运营团队提供了一系列旨在管理文本文件工作流的功能。

Instance Manager 与 Git 和其他外部系统的新集成实现了版本控制、分散贡献、审批工作流程和团队协调等功能。 GitHub 和 GitLab 等平台通过基于 Web 的用户界面将此功能集扩展到持续集成/持续部署 (CI/CD)、协作、问题跟踪和其他有价值的功能。

在这篇博文中，我们说明了如何使用 GitHub 来管理 NGINX 配置，并在发生更改时自动将其推送到实例。

实例管理器 API

实例管理器提供了一组丰富的 REST API 来补充其 Web 用户界面。 API 的一个主要优点是它能够更新管理下的数据平面实例的配置文件。 最近，我们通过启用将配置更新与文件的特定版本绑定的功能来扩展此功能。 在 Git 存储库中进行管理时，可以使用 Git 提交哈希来标记配置。 此外，我们在实例管理器中为外部管理配置实现了新的状态，警告潜在的文件编辑者配置处于外部管理之下。

GitHub 操作

GitHub 允许开发人员使用名为Actions的功能在其存储库中创建自定义部署管道。 用户可以选择定义自己的操作或通过YAML 定义调用现有脚本。 这些管道可以通过多种方式触发，例如当使用提交或拉取请求合并更新存储库时。

在此博客的示例中，我们依赖开箱即用的 GitHub Actions 和 Linux 命令。 您将学习如何使用它们通过实例管理器 API 更新 NGINX 实例上由 GitHub 管理的 NGINX 配置文件。首先，请按照GitHub 文档中的以下步骤创建一个新的 YAML 来在您的存储库中运行操作。

设置操作秘密

实例管理器支持多种形式的身份验证。 在示例中，我们使用基本身份验证方法，但我们建议在生产环境中配置 OIDC 身份验证。

GitHub 允许您将机密定义为存储库变量，而不是将实例管理器凭据存储在存储库中。 这些变量可以通过 Actions 环境访问，但隐藏在日志中。 按照以下步骤将实例管理器用户名和密码密钥存储为机密，以便您可以使用它们来验证您的 API 调用。

在这里，我们将这些变量设置为NMS_USERNAME和NMS_PASSWORD 。

设置操作变量

类似地，与其在 YAML 中定义常量变量，不如将它们分解出来在 GitHub 用户界面中进行管理。 在变量页面上，您可以找到有关如何定义跨所有存储库操作的变量的说明。 在示例中，我们利用这个机会定义实例管理器 FQDN 或 IP（ NMS_HOSTNAME ）、运行 NGINX 的系统的标识符（ SYSTEM_ID ）以及要更新的特定 NGINX 实例的标识符（ INSTANCE_ID ）。

笔记： 我们设置了这些变量来简化我们的示例，但您可以选择以其他方式管理实例管理器、系统和 NGINX 识别信息。 例如，您可以选择在存储库中创建包含特定于不同实例的配置的目录，并使用系统或实例 ID 命名这些目录。 然后，您可以修改 YAML 或 Action 脚本来读取目录名称并更新相应实例上的配置文件。

用于更新 NGINX 配置的实例管理器 REST API 调用剖析

实例管理器配置更新REST API 调用需要几个关键组件才能工作。 您的 YAML 将需要定义每个参数并以正确的格式将它们打包到 API 调用中。

在示例中，我们使用 API 调用来更新单个实例。 但是，也可以在实例管理器中配置实例组。 这样做使您能够在从 GitHub 推送新配置时更新组中的所有实例。 欲了解更多信息，请参阅我们的发布配置操作指南。

以下是实例管理器配置更新REST API 调用的细分：

<a href="https://{INSTANCE">https://{实例</a>管理器主机名}/api/platform/v1/systems/{系统 ID}/instances/{实例 ID}/config'
--header“接受：应用/json”
--header "授权： 基本{登录凭据}”
--header'内容类型：应用/json'
- 数据 '{
“配置文件”：'{
“rootDir”：“/etc/nginx”，
“文件”：[{
“内容”：“{NGINX 配置文件}”，
“name”：“{系统配置文件路径}”
}]
}，
"externalIdType": "{配置来源}",
"externalId": "{提交哈希}",
“更新时间”：“{时间戳}”
'}'

URI 参数

• 系统标识符——标识 NGINX 所运行系统的唯一键。 在我们的示例中，该数据在 GitHub Actions Variables 界面中定义。
• NGINX 实例标识符 –用于标识系统上特定 NGINX 实例的唯一键。 在我们的示例中，该数据在 GitHub Actions Variables 界面中定义。

标头参数

• 授权 –实例管理器用于验证 API 调用的授权方法和 Base64 编码凭证。 在示例中，您将使用基本授权和来自存储库中设置的机密的凭证数据。

JSON 数据参数

• configFiles –正在更新的配置文件的 Base64 编码内容，以及它们在运行 NGINX 的系统上的位置。您还需要提供 NGINX 配置文件根目录的路径，最常见的配置为： /etc/nginx 。
• externalIdType –用于向实例管理器标识配置文件来源的标签。 可能的值是git或其他。 在我们的示例中，我们将此参数硬编码为git 。
• externalId – Git 提交安全哈希算法 (SHA)，用于标识对配置文件的更改。
• updateTime –包含当前日期和时间的字符串，格式为%Y-%m-%dT%H:%M:%SZ 。

Base64 编码

为了适应 Instance Manager 的 API 规范，您必须将某些数据编码为 Base64 格式进行转换。 虽然现有的 GitHub Actions 没有原生的方法来实现这一点，但我们可以依赖从 YAML 访问的 Linux 工具。

实例管理器凭证

首先引用之前定义为机密的实例管理器登录凭据并将它们连接起来。 然后，将字符串转换为 Base64，将其作为 Linux 变量 ( NMS_LOGIN ) 回显，并将结果附加到 Actions 运行器可访问的预定义环境变量 ( GITHUB_ENV )。

运行：echo“NMS_LOGIN =`echo -n”${{ secrets.NMS_USERNAME } }：${{ secrets.NMS_PASSWORD } }" | base64`" >> $GITHUB_ENV

时间戳

实例管理器 API 要求使用某些 API 有效负载发送特定格式的时间戳。 您可以使用 Linux日期命令构建该格式的时间戳。 与前面的例子类似，将构造的字符串作为变量附加到Linux环境中。

运行：echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

NGINX 配置

接下来，将您计划管理的 NGINX 配置添加到存储库中。 有很多方法可以将文件添加到 GitHub 存储库。 有关更多信息，请遵循 GitHub 文档中的本指南。 为了遵循我们的示例，您可以在 GitHub 存储库中创建一个与实例相同的目录结构。

下面的 YAML 条目从您的存储库读取配置文件，将其内容编码为 Base64，并将结果添加到环境变量，就像以前一样。

运行：echo “NGINX_CONF_CONFIG_FILE=`cat nginx-server/etc/nginx/nginx.conf | base64 -w 0`” >> $GITHUB_ENV

在我们的示例中，我们对 GitHub 存储库中的每个配置文件重复此操作。

综合起来

最后，您可以使用 GitHub 的示例参考实现将您所学到的知识拼凑成一个可行的 YAML 文件。 根据文件中的定义，每当用户通过提交或拉取请求更新存储库时，所有相关的 GitHub Actions 脚本都会运行。 YAML 中的最后一个条目将运行一个curl命令，该命令将进行适当的 API 调用，其中包含实例管理器更新所有相关配置文件所需的数据。

笔记： 使用 YAML 中的多行运行条目 ( run:| ) 来运行curl命令，因为这会指示 YAML 解释器将冒号“:”视为条目参数部分中的文本。

姓名： 使用 GitHub 和 GitHub Actions 管理 NGINX 配置 # 控制工作流程何时运行： # 在推送或拉取请求事件上触发工作流程，但仅限于“主”分支 push: branchs: [ "main" ] pull_request: branchs: [ "main" ] # 允许您从 Actions 选项卡手动运行此工作流程 working_dispatch: # 工作流程运行由一个或多个可以按顺序或并行运行的作业组成 jobs: # 此工作流程包含一个名为“build”的作业 build: # 作业将在其上运行的运行器类型 runs-on: ubuntu-latest # 步骤表示将作为作业的一部分执行的一系列任务 steps: # 在 $GITHUB_WORKSPACE 下检出您的存储库，以便您的作业可以访问它 - uses: action/checkout@v4 - name: 为 NMS API登录凭据设置环境变量运行：echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME } }：${{ secrets.NMS_PASSWORD } }“ | base64`” >> $GITHUB_ENV - 名称： 为 NMS API 时间戳运行设置环境变量：echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV - name: 为 base64 编码的配置文件运行设置环境变量：echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV - name: 为 base64 编码的配置文件运行设置环境变量：echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV - name: 为 base64 编码的配置文件运行设置环境变量：echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV - name: 为 base64 编码的配置文件运行设置环境变量：echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV - name: 对实例管理器运行的 API 调用：| curl --location 'https://${{ vars.NMS_HOSTNAME } /api/平台/v1/系统/${{ vars.SYSTEM_ID } }/实例/${{ vars.INSTANCE_ID } }/config'--header“接受：application/json”--header“授权： 基本的${{ env.NMS_LOGIN }}“ --header'Content-Type：application/json'--data'{“configFiles”：{“rootDir”：“/etc/nginx”，“files”：[{“contents”：“${{ env.NGINX_CONF_CONFIG_FILE } }“，”名称“：”/etc/nginx/nginx.conf“}，{”内容“：”${{ env.MIME_TYPES_CONFIG_FILE } }“，”名称“：”/etc/nginx/mime.types“}，{“内容”：“${{ env.DEFAULT_CONF_CONFIG_FILE } }“，”名称“：”/etc/nginx/conf.d/default.conf“}，{”内容“：”${{ env.SSL_CONF_CONFIG_FILE } }“，”名称“：”/etc/nginx/conf.d/ssl.conf“}]}，“externalIdType”：”git“，”externalId“：”${{ github.sha } }","更新时间": "${{ env.NMS_TIMESTAMP } “' 

NGINX 参考实现

在文件更改后执行配置更新API 调用可以通过不同的方式实现。 虽然 GitHub Actions 对于使用 GitHub 的人来说是最方便的方法，但它不适用于 GitLab 或独立的 Git 实现。 为了解决这些用例，我们开发了一个配套的 shell 脚本参考实现，可以从命令行触发或从自定义脚本调用。

总之，我们对实例管理器 API 的新扩展提供了一个强大的工具，可以以现代、分散的方式管理配置更新、回滚和版本历史记录。 将扩展与第三方文本文件和代码管理平台（如 GitHub）结合起来，可以通过直观的基于 Web 的用户界面实现额外的工作流程、CI/CD、协作和问题跟踪功能。

我们很乐意听到您的想法！ 尝试一下，然后在评论中或加入我们的NGINX 社区 Slack 频道告诉我们您的想法。