使用 GitHub Actions 和 Terragrunt 创建由 API 驱动的资源编排框架 - AWS 规范指引
Summary先决条件和限制架构工具最佳实践操作说明相关资源附加信息

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

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

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

Summary

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

为满足不同的组织要求，我们可以调整这个可配置的管道架构。示例实施侧重于 Amazon Virtual Private Cloud（Amazon VPC）和 Amazon Simple Storage Service（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. 导入位于源存储库的 .github/workflows 文件夹中的 deployment.yml 和 workflow-trigger.yml 文件

DevOps 工程师

配置 IAM 角色和权限。

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

  1. 使用GitHub 操作与 AWS使用 OpenID Connect (OIDC) 身份提供商 (IdP) 中的操作关联的操作@@ 创建一个 IAM 角色。

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

DevOps 工程师

设置 GitHub 机密和变量。

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

  • 存储库密钥

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

  • 存储库变量

    • aws_role— IAM 角色 Amazon 资源名称 (ARN)，具有部署所需资源并将操作与中的 GitHub 操作关联的相应权限 AWS

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 管理控制台

    1. 对于 Amazon VPC：

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

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

      • 验证 CIDR 数据块和其他配置。

    2. 对于 Amazon S3：

      • 导航到 Amazon S3 存储桶。

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

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

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

DevOps 工程师
Task说明所需技能

提交清理请求。

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

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

    • 在 RequestParameters 中，将 RequestType 更改为 delete。

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

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

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

  4. 使用 AWS 管理控制台验证资源移除情况。

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对于 Amazon VPC，参数 vpc_cidr 是强制的。