使用 GitHub Actions 和 Terragrunt 创建由 API 驱动的资源编排框架 - AWS Prescriptive Guidance
摘要先决条件和限制架构工具最佳实践操作说明相关资源其他信息

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 GitHub Actions 和 Terragrunt 创建由 API 驱动的资源编排框架

Tamilselvan P、Abhigyan Dandriyal、Sandeep Gawande 和 Akash Kumar，Amazon Web Services

摘要

这种模式利用 Ac GitHub tions 工作流程通过标准化的 JSON 负载自动配置资源，无需手动配置。这个自动化管道管理着完整的部署生命周期，并且可以与各种前端系统无缝集成，从自定义用户界面组件到 ServiceNow。该解决方案的灵活性允许用户通过其首选接口与系统进行交互，同时保持标准化流程。

可以调整可配置的流水线架构，以满足不同的组织需求。示例实现侧重于亚马逊虚拟私有云（亚马逊 VPC）和亚马逊简单存储服务（Amazon S3）的配置。该模式通过标准化整个组织的请求并提供一致的集成点，有效地解决了常见的云资源管理难题。这种方法使团队可以更轻松地请求和管理资源，同时确保标准化。

先决条件和限制

先决条件

  • 活跃的 AWS 账户

  • 有权访问已配置存储库的活跃 GitHub 账户

限制

  • 新资源需要手动将terragrunt.hcl文件添加到存储库配置中。

  • 有些 AWS 服务 并非全部可用 AWS 区域。有关区域可用性，请参阅按地区划分的AWS 服务。有关特定终端节点，请参阅服务终端节点和配额，然后选择服务的链接。

架构

下图显示了此模式的组件和工作流程。

使用 GitHub 操作和 Terraform 自动配置资源的工作流程。

架构图显示了以下操作：

  1. 用户向 GitHub 操作提交 JSON 有效负载，从而触发自动化管道。

  2. GitHub 操作管道根据有效载荷规格从 Terragrunt 和 Terraform 存储库中检索所需的资源代码。

  3. 管道使用指定 AWS 账户 ID 担任相应的 AWS Identity and Access Management (IAM) 角色。然后，管道将资源部署到目标，并使用特定于账户的 Amazon S3 存储桶 AWS 账户 和 Amazon DynamoDB 表管理 Terraform 状态。

每个角色都 AWS 账户 包含用于安全访问的 IAM 角色、一个用于 Terraform 状态存储的 Amazon S3 存储桶和一个用于状态锁定的 DynamoDB 表。这种设计可实现可控、自动化的资源部署 AWS 账户。部署过程通过每个账户中的专用 Amazon S3 存储桶和 IAM 角色来维护适当的状态管理和访问控制。

工具

AWS 服务

其他工具

  • GitHub A@@ c tions 是一个持续集成和持续交付 (CI/CD) 平台，与 GitHub 存储库紧密集成。您可以使用 GitHub Actions 来自动执行构建、测试和部署管道。

  • Terraform 是一款基础设施即代码 (IaC) 工具 HashiCorp ，可帮助您创建和管理云和本地资源。

  • Terragrunt 是一款编排工具，它扩展了 Terraform 和 OpenTofu Terraform 的功能。它管理通用基础设施模式的应用方式，从而更轻松地扩展和维护大型基础设施资产。

代码存储库

此模式的代码可在 GitHub sample-aws-orchestration-pipeline-terraform 存储库中找到。

最佳实践

  • 使用存储 GitHub 库密钥存储 AWS 凭证和敏感数据，以实现安全访问。

  • 将 OpenID Connect (OIDC) 提供程序配置为 GitHub 操作代入 IAM 角色，避免使用静态证书。

  • 遵循最低权限原则，授予执行任务所需的最低权限。有关更多信息，请参阅 IAM 文档中的授予最低权限和安全最佳实践。

操作说明

Task描述所需技能

初始化 GitHub 存储库。

要初始化 GitHub 存储库，请使用以下步骤：

  1. 创建一个新的GitHub 存储库来托管管道代码。

  2. 导入位于deployment.yml源存储库 .github/workflows 文件夹中的和workflow-trigger.yml文件。

DevOps 工程师

配置 IAM 角色和权限。

要配置 IAM 角色和权限，请使用以下步骤：

  1. 创建一个 IAM 角色，该角色具有GitHub 操作与 AWS使用 OpenID Connect (OIDC) 身份提供商 (IdP) 中的操作关联所需的信任关系。

  2. 向 IAM 角色授予创建后端所需的权限和所需资源。有关更多信息，请参阅使用亚马逊 VPC 以及后端 Amazon S3 存储桶和 DynamoDB 表创建 VPC 的示例策略。

DevOps 工程师

设置 GitHub 机密和变量。

有关如何在存储库中设置存储库密钥和变量的说明，请参阅 GitHub 文档中的为仓库创建配置变量。 GitHub 配置以下变量：

  • 存储库机密

    • PAT_TOKEN— 您的个人访问令牌，具有执行 GitHub 操作的权限

  • 存储库变量

DevOps 工程师

创建存储库结构。

要创建存储库结构，请使用以下步骤：

  1. 在main分支中创建一个新文件夹来存储terragrunt.hcl文件以及资源创建后的输出和变更日志。

  2. 根据要通过文件夹置备的资源类型，使用小写命名文件夹。稍后将在负载中按原样使用该文件夹。有关更多信息，请参阅存储库中的 Amazon S3 和 Amazon VPC 的示例结构。

DevOps 工程师
Task描述所需技能

使用 curl 执行管道。

要使用 curl 执行管道，请按以下步骤操作：

  1. 在您的本地目录中创建一个 payload.json 文件。遵循为有效载荷文件定义的结构，并在提交请求之前对其进行字符串化。有关更多信息，请参阅存储库中的负载示例。

  2. 使用 GitHub API 在您的终端上提交请求，如以下示例所示：

    curl -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -d @payload.json \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/workflow-trigger.yml/dispatches

    在示例中，为以下内容提供您自己的值：

    • YOUR_GITHUB_TOKEN使用您的 GitHub 个人访问令牌

    • OWNER以存储库所有者的名字命名

    • REPO带有存储库名称

有关管道执行过程的更多信息，请参阅其他信息。

DevOps 工程师

验证管道执行结果

要验证结果，请使用以下步骤：

  1. 在仓库的 “ GitHub 操作” 选项卡中监控操作工作流程的执行情况。

  2. 成功执行工作流程后，使用以下方法验证资源创建： AWS Management Console

    1. 对于亚马逊 VPC：

      • 导航到指定的 Amazon VPC 服务 AWS 区域。

      • 检查带有与您的请求参数匹配的标签的新 VPC。

      • 验证 CIDR 块和其他配置。

    2. 对于 Amazon S3：

      • 导航至 Amazon S3 存储桶。

      • 在通用存储桶中，检查是否有与您的请求参数匹配的新存储桶。

      • 验证 S3 存储桶名称和其他配置。

您还可以使用在存储库中创建的文件（该output.json文件与terragrunt.hcl文件位于同一资源内）来交叉验证已创建的资源。

DevOps 工程师
Task描述所需技能

提交清理请求。

要删除不再需要的资源，请执行以下步骤：

  1. 使用相同的 API 端点提交删除请求，但按如下方式修改有效负载：

    • 在. delete 中RequestType更改为RequestParameters。

    • 保持所有其他参数与create请求相同。

  2. 在 “ GitHub 操作” 中监控删除过程。

  3. 工作流程完成后，验证资源文件夹内的changelog.json文件是否显示状态deleted。

  4. 使用验证资源移除情况 AWS Management Console。

DevOps 工程师

相关资源

AWS 博客

AWS 服务 文档

GitHub resources

其他信息

管道执行流程

以下是管道执行的步骤：

  1. 验证 JSON 负载格式-确保传入的 JSON 配置结构正确且包含所有必需的参数

  2. 担任指定的 IAM 角色-进行身份验证并担任操作所需的 IAM 角色 AWS

  3. 下载所需的 Terraform 和 Terragrunt 代码-检索指定版本的资源代码和依赖关系

  4. 执行资源部署-应用配置以在目标环境中部署或更新 AWS 资源

用于创建 VPC 的示例负载

以下是创建 Terraform 后端状态存储桶的示例代码：

state_bucket_name = "${local.payload.ApplicationName}-${local.payload.EnvironmentId}-tfstate"
lock_table_name = "${local.payload.ApplicationName}-${local.payload.EnvironmentId}-tfstate-lock"

以下是使用 Amazon VPC 创建 VPC 的有效负载示例，其中vpc_cidr定义了 VPC 的 CIDR 区块规范。Terraform 状态存储桶映射到文件中定义的terraform变量。该ref参数包含要执行的代码的分支名称。

{
    "ref": "main",
    "inputs": {
        "RequestParameters": {
            "RequestId": "1111111",
            "RequestType": "create",
            "ResourceType": "vpc",
            "AccountId": "1234567890",
            "AccountAlias": "account-alias",
            "RegionId": "us-west-2",
            "ApplicationName": "myapp",
            "DivisionName": "division-name",
            "EnvironmentId": "dev",
            "Suffix": "poc"
        },
        "ResourceParameters": [
            {
                "VPC": {
                    "vpc_cidr": "10.0.0.0/16"
                }
            }
        ]
    }
}

RequestParameters用于跟踪管道部分中的请求状态，并tfstate基于此信息创建。以下参数包含元数据和控件信息：

  • RequestId— 请求的唯一标识符

  • RequestType— 操作类型（创建、更新或删除）

  • ResourceType— 要配置的资源类型

  • AccountId— AWS 账户 部署目标

  • AccountAlias— 的友好名称 AWS 账户

  • RegionId— AWS 区域 用于资源部署

  • ApplicationName— 应用程序的名称

  • DivisionName— 组织部门

  • EnvironmentId— 环境（例如，开发和生产）

  • Suffix— 资源的附加标识符

ResourceParameters包含特定于资源的配置，该配置映射到 Terraform 文件中定义的变量。任何需要传递给 Terraform 模块的自定义变量都应包含在中。ResourceParameters该参数对vpc_cidr于 Amazon VPC 来说是必需的。