使用 AWS CDK 与 GitLab 在 Amazon ECS Anywhere 上为混合工作负载设置 CI/CD 管线 - AWS Prescriptive Guidance
摘要先决条件和限制架构工具最佳实践操作说明故障排除相关资源

使用 AWS CDK 与 GitLab 在 Amazon ECS Anywhere 上为混合工作负载设置 CI/CD 管线

Rahul Sharad Gaikwad 博士，Amazon Web Services

摘要

注意：AWS CodeCommit 现已不再向新客户提供。AWS CodeCommit 的现有客户可以继续正常使用该服务。了解更多

Amazon ECS Anywhere 是 Amazon Elastic Container Service (Amazon ECS) 的扩展。它支持将外部实例（例如本地服务器或虚拟机 (VM)）注册到 Amazon ECS 集群。该功能有助于降低成本并减轻复杂的本地容器编排和操作。您可以使用 ECS Anywhere 在本地和云环境中部署和运行容器应用程序。它使您的团队无需学习多个域和技能组合，也无需自行管理复杂的软件。

此模式描述了使用 Amazon Web Services (AWS) 的 AWS Cloud Development Kit (AWS CDK) 堆栈预调配具有 Amazon ECS Anywhere 实例的 Amazon ECS 集群的分步方法。然后，您可使用 AWS CodePipeline 设置持续集成和持续部署 (CI/CD) 管线。然后，您将您的 GitLab 代码存储库复制至 AWS CodeCommit，然后在 Amazon ECS 集群上部署您的容器化应用程序。

此模式旨在帮助那些使用本地基础设施运行容器应用程序并使用 GitLab 管理应用程序代码库的用户。您可使用 Amazon Web Services Cloud 服务管理这些工作负载，而不会干扰您现有的本地基础设施。

先决条件和限制

先决条件

  • 一个有效的 Amazon Web Services account。

  • 在本地基础设施上运行的容器应用程序。

  • GitLab 存储库，用于管理应用程序代码库。有关更多信息，请参阅存储库 (GitLab)。

  • 已安装和配置 AWS 命令行界面（AWS CLI）。有关更多信息，请参阅安装或更新最新版本的 AWS CLI（AWS CLI 文档）。

  • AWS CDK Toolkit，已安装并全局配置。有关更多信息，请参阅安装 AWS CDK（AWS CDK 文档）。

  • npm，已在 TypeScript 中为 AWS CDK 安装并配置。有关更多信息，请参阅下载和安装 Node.js 和 npm（npm 文档）。

限制

产品版本

  • AWS CDK Toolkit 版本 2.27.0 或更高版本

  • npm 版本 7.20.3 或更高版本

  • Node.js 版本 16.6.1 或更高版本

架构

目标技术堆栈

  • AWS CDK

  • AWS CloudFormation

  • AWS CodeBuild

  • AWS CodeCommit

  • AWS CodePipeline

  • Amazon ECS Anywhere

  • Amazon Elastic Container Registry (Amazon ECR)

  • AWS Identity and Access Management (IAM)

  • AWS Systems Manager

  • GitLab 存储库

目标架构

设置 Amazon ECS 集群和 CI/CD 管线架构图。

此图表示此模式中描述的两个主要工作流，即预调配 Amazon ECS 集群并设置用于设置和部署 CI/CD 管线的 CI/CD 管线，如下所示：

  1. 预调配 Amazon ECS 集群

    1. 当您部署第一个 AWS CDK 堆栈，它会在 AWS 上创建一个 CloudFormation 堆栈。

    2. 此 CloudFormation 堆栈预调配 Amazon ECS 集群和相关 AWS 资源。

    3. 要将外部实例注册到 Amazon ECS 集群，您必须在虚拟机上安装 AWS Systems Manager Agent (SSM Agent) 并将该虚拟机注册为 AWS Systems Manager 托管实例。 

    4. 在您的虚拟机上，您还必须安装 Amazon ECS 容器代理和 Docker，以将其注册为 Amazon ECS 集群的外部实例。

    5. 当外部实例注册并配置到 Amazon ECS 集群时，它可以在注册为外部实例的虚拟机上运行多个容器。

    6. Amazon ECS 集群处于活动状态，可通过容器运行应用程序工作负载。Amazon ECS Anywhere 容器实例在本地环境中运行，但与云 Amazon ECS 集群关联。

  2. 设置和部署 CI/CD 管线

    1. 当您部署第二个 AWS CDK 堆栈时，它会在 AWS 上创建另一个 CloudFormation 堆栈。

    2. 此 CloudFormation 堆栈在 CodePipeline 中预调配管线和相关 AWS 资源。

    3. 您可将应用程序代码更改推送并合并至本地 GitLab 存储库。 

    4. GitLab 存储库会自动复制到 CodeCommit 存储库。

    5. CodeCommit 存储库更新会自动启动 CodePipeline。 

    6. CodePipeline 从 CodeCommit 中复制代码，然后在 CodeBuild 中创建可部署应用程序版本。

    7. CodePipeline 创建 CodeBuild 构建环境的 Docker 映像，并将其推送到 Amazon ECR 存储库。

    8. CodePipeline 会启动 CodeDeploy 操作，从 Amazon ECR 存储库中提取容器映像。

    9. CodePipeline 可在 Amazon ECS 集群上部署容器映像。

自动化和扩缩

此模式使用 AWS CDK 作为基础设施即代码（IaC）工具来配置和部署此架构。AWS CDK 可帮助您编排 AWS 资源，并设置 Amazon ECS Anywhere 和 CI/CD 管线。

工具

Amazon Web Services

其他工具

  • Node.js 是事件驱动的 JavaScript 运行时环境，专为构建可扩展网络应用程序而设计。

  • npm 是在 Node.js 环境中运行的软件注册表，用于共享或借用软件包以及管理私有软件包的部署。

  • Vagrant 是一个开源实用程序，用于构建和维护便携式虚拟软件开发环境。出于演示目的，此模式使用 Vagrant 创建本地虚拟机。

代码存储库

此示例代码适用于 GitHub 使用 AWS CDK 的 Amazon ECS Anywhere 的 CI/CD 管线存储库。

最佳实践

部署此模式时，请考虑以下最佳实践：

操作说明

任务描述所需技能

验证 AWS CDK 版本。

通过输入以下命令验证 AWS CDK Toolkit 的版本。

cdk --version

此模式需要版本 2.27.0 或更高版本。如果您拥有早期版本，请按照 AWS CDK 文档中的说明对其进行更新。

DevOps 工程师

验证 npm 版本。

通过输入以下命令验证 npm 的版本。

npm --version

此模式需要版本 7.20.3 或更高版本。如果您拥有早期版本，请按照 npm 文档中的说明对其进行更新。

DevOps 工程师

设置 AWS 凭证。

通过输入 aws configure 命令并按照提示进行操作设置凭证。

$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:
DevOps 工程师
任务描述所需技能

克隆 AWS CDK 代码存储库。

  1. 输入以下命令，使用此模式的使用 AWS CDK 的 Amazon ECS Anywhere 的 CI/CD 管线存储库。

    git clone https://github.com/aws-samples/amazon-ecs-anywhere-cicd-pipeline-cdk-sample.git

  2. 通过输入以下命令导航到克隆的目录。

    cd amazon-ecs-anywhere-cicd-pipeline-cdk-sample
DevOps 工程师

引导环境。

通过输入以下命令将 CloudFormation 模板部署至您要使用的账户和 AWS 区域。

cdk bootstrap <account-number>/<Region>

有关更多信息，请参阅 AWS CDK 文档中的引导。

DevOps 工程师
任务描述所需技能

安装程序包依赖项并编译 TypeScript 文件。

通过输入以下命令安装程序包依赖项并编译 TypeScript 文件。

$cd EcsAnywhereCdk
$npm install
$npm fund

这些命令安装示例存储库内的所有软件包。有关更多信息，请参阅 npm 文档中的 npm ci 和 npm 安装。如果在输入这些命令时出现任何关于丢失程序包的错误，请参阅此模式的故障排除部分。

DevOps 工程师

构建 项目。

要构建项目代码，请输入以下命令。

npm run build

有关构建和部署项目的更多信息，请参阅 AWS CDK 文档中的您的第一个 AWS CDK 应用程序。

DevOps 工程师

部署 Amazon ECS Anywhere 基础设施堆栈。

  1. 通过输入以下命令列出堆栈。

    $cdk list

  2. 确认输出是否返回了 EcsAnywhereInfraStack 和 ECSAnywherePipelineStack 堆栈。

  3. 通过输入以下命令部署 EcsAnywhereInfraStack 堆栈。

    $cdk  deploy EcsAnywhereInfraStack
DevOps 工程师

验证堆栈创建和输出。

  1. 登录 AWS 管理控制台 并在 https://console.aws.amazon.com/cloudformation/ 上打开 CloudFormation 控制台。

  2. 在堆栈页面，选择 EcsAnywhereInfraStack 堆栈。

  3. 确认堆栈状态为 CREATE_IN_PROGRESS 或 CREATE_COMPLETE。

    设置 Amazon ECS 集群可能需要一定的时间。在堆栈创建完成前，请勿继续。

DevOps 工程师
任务描述所需技能

设置您的虚拟机。

通过从 Vagrantfile 所在的根目录中输入 vagrant up 命令来创建 Vagrant 虚拟机。有关更多信息，请参阅 Vagrant 文档。

DevOps 工程师

将您的虚拟机注册为外部实例。

  1. 使用 vagrant ssh 命令登录 Vagrant 虚拟机。有关更多信息，请参阅 Vagrant 文档。

  2. 按照 AWS CLI 安装说明并输入以下命令，在虚拟机上安装 AWS CLI。 

    $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" \
> -o "awscliv2.zip"
$sudo apt install unzip
$unzip awscliv2.zip
$sudo ./aws/install
$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:

  1. 创建激活码和 ID，您可以使用该激活码和 ID 在 AWS Systems Manager 注册虚拟机并激活外部实例。此命令输出包括激活 ID 和激活码值。

    aws ssm create-activation \
> --iam-role EcsAnywhereInstanceRole \
> | tee ssm-activation.json

    如果您在运行此命令时收到错误，请参阅故障排除部分。

  2. 导出激活 ID 与代码值。

    export ACTIVATION_ID=<activation-ID>
export ACTIVATION_CODE=<activation-code>

  3. 下载安装脚本至虚拟机。

    curl --proto "https" -o "ecs-anywhere-install.sh" \
> "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh"

  4. 在您的虚拟机上运行安装脚本。

    sudo bash ecs-anywhere-install.sh \
--cluster EcsAnywhereCluster \
--activation-id $ACTIVATION_ID \
--activation-code $ACTIVATION_CODE \
--region <region-name>

这会将您的虚拟机设置为 Amazon ECS Anywhere 外部实例，并将该实例注册至 Amazon ECS 集群。有关更多信息，请参阅 Amazon ECS 文档中的向集群注册外部实例。如果您遇到任何问题，请参阅故障排除部分。

DevOps 工程师

验证 Amazon ECS Anywhere 和外部虚拟机状态。

要验证您的虚拟机是否已连接到 Amazon ECS 控制面板并正在运行，请使用以下命令。

$aws ssm describe-instance-information
$aws ecs list-container-instances --cluster $CLUSTER_NAME
DevOps 工程师
任务描述所需技能

在 CodeCommit 存储库中创建分支。

通过为仓库创建第一个提交，在 CodeCommit 存储库中创建名为 main 的分支。您可按照 AWS 文档中的说明在 CodeCommit 中创建提交。以下命令是一个示例。

aws codecommit put-file \
  --repository-name EcsAnywhereRepo \
  --branch-name main \
  --file-path README.md \
  --file-content "Test" \
  --name "Dev Ops" \
  --email "devops@example.com" \
  --commit-message "Adding README."
DevOps 工程师

设置存储库镜像。

您可将 GitLab 存储库镜像到外部源或从外部源镜像。您可选择哪个存储库作为源。分支、标签和提交自动同步。在托管应用程序的 GitLab 存储库和 CodeCommit 存储库间设置推送镜像。有关说明，请参阅设置从 GitLab 到 CodeCommit 的推送镜像（GitLab 文档）。

注意

默认情况下，镜像将自动同步存储库。如果要手动更新存储库，请参阅更新镜像（GitLab 文档）。

DevOps 工程师

部署 CI/CD 管线堆栈。

通过输入以下命令部署 EcsAnywherePipelineStack 堆栈。

$cdk  deploy EcsAnywherePipelineStack
DevOps 工程师

测试 CI/CD 管线。

  1. 更改应用程序代码并将其推送至源本地 GitLab 存储库。有关更多信息，请参阅推送选项（GitLab 文档）。例如，编辑 ../application/index.html 文件以更新应用程序版本值。

  2. 将代码复制至 CodeCommit 存储库时，这会启动 CI/CD 管线。请执行以下操作之一：

    • 如果您通过自动镜像将 GitLab 存储库与 CodeCommit 存储库同步，请继续执行下一步。

    • 如果您使用的是手动镜像，请按照更新镜像（GitLab 文档）中的说明将应用程序代码更改推送至 CodeCommit 存储库。

  3. 在您的本地计算机上，在 Web 浏览器中输入 http://localhost:80。打开 NGINX 网页，因为端口 80 被转发到 Vagrantfile 中的本地主机。确认您可查看更新的应用程序版本值。验证管线和映像部署。

  4. （可选）如果要在 AWS 管理控制台 中验证部署，请执行以下操作：

    1. 打开位于 https://console.aws.amazon.com/ecs/的 Amazon ECS 控制台。

    2. 从导航栏中，选择要使用的区域。

    3. 在导航窗格中，选择集群。

    4. 在集群页面上，选择 EcsAnywhereCluster 集群。

    5. 选择任务定义。

    6. 确认容器正在运行。

DevOps 工程师
任务描述所需技能

清理和删除资源。

完成此模式后，应移除您所创建的概念验证资源。要进行清理，请输入以下命令。

$cdk destroy EcsAnywherePipelineStack
$cdk destroy EcsAnywhereInfraStack
DevOps 工程师

故障排除

问题解决方案

安装程序包依赖项时，出现缺少程序包的错误。

输入下列命令之一，解决程序包缺失问题。

$npm ci

或

$npm install -g @aws-cdk/<package_name>

在虚拟机上运行 aws ssm create-activation 命令时，您将收到以下错误。

An error occurred (ValidationException) when calling the CreateActivation operation: Nonexistent role or missing ssm service principal in trust policy: arn:aws:iam::000000000000:role/EcsAnywhereInstanceRole

EcsAnywhereInfraStack 堆栈尚未完全部署，运行此命令所需 IAM 角色也尚未创建。在 CloudFormation 控制台检查堆栈状态。状态变为 CREATE_COMPLETE 后重试该命令。

Amazon ECS 运行状况检查返回 UNHEALTHY，您会在 Amazon ECS 控制台的集群的服务部分看到以下错误。

service EcsAnywhereService was unable to place a task because no container instance met all of its requirements. Reason: No Container Instances were found in your cluster.

输入以下命令，在 Vagrant 虚拟机重新启动 Amazon ECS 代理。

$vagrant ssh
$sudo systemctl restart ecs
$sudo systemctl status ecs

相关资源