本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 构建自定义 Amazon ParallelCluster AMI
使用 Amazon ParallelCluster 命令行界面 (CLI) 或 API 时，您只需为创建或更新 Amazon ParallelCluster 映像和集群时创建的 Amazon 资源付费。有关更多信息，请参阅 [Amazon 使用的服务 Amazon ParallelCluster](aws-services-v3.md)。
**重要**
如果构建自定义 AMI，则必须重复执行用于随每个新的 Amazon ParallelCluster 版本创建自定义 AMI 的步骤。
在进一步阅读之前，我们建议您首先查看[自定义引导操作](custom-bootstrap-actions-v3.md)一节。确定未来 Amazon ParallelCluster 版本是否可以脚本化并支持您要进行的修改。
尽管通常构建自定义 AMI 并不理想，但在某些特定场景中，需要 Amazon ParallelCluster 为其构建自定义 AMI。本教程介绍如何为这些场景构建自定义 AMI。
**先决条件**
+ Amazon ParallelCluster [已安装](install-v3-parallelcluster.md)。
+ Amazon CLI [已安装并配置。](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html)
+ 您有一个 [Amazon EC2 密钥对](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/ec2-key-pairs.html)。
+ 您拥有具有运行 [`pcluster`](pcluster-v3.md) CLI 和构建映像所需的[权限](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-example-user-policies)的 IAM 角色。
## 如何自定义 Amazon ParallelCluster AMI
有两种方法可以构建自定义 Amazon ParallelCluster AMI。这两种方法之一是使用 CLI 构建新 AM Amazon ParallelCluster I。另一种方法需要进行手动修改以构建可在您的 Amazon Web Services 账户下使用的新 AMI。
## 构建自定义 Amazon ParallelCluster AMI
如果您有自定义 AMI 和软件，则可以在其 Amazon ParallelCluster 上应用所需的更改。 Amazon ParallelCluster 依靠 EC2 Image Builder 服务进行自定义构建 AMIs。有关更多信息，请参阅 [Image Builder User Guide](https://docs.amazonaws.cn/imagebuilder/latest/userguide/what-is-image-builder.html)。
关键点：
+ 该过程需要 1 小时左右的时间。如果在构建时需要安装其他[`Build`](Build-v3.md)/[`Components`](Build-v3.md#Build-v3-Components)，则此时间可能会有所不同。
+ AMI 标有主要组件的版本。其中包括内核、调度器和 [EFA](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/efa.html) 驱动程序。还会在 AMI 描述中报告一部分组件版本。
+ 从 Amazon ParallelCluster 3.0.0 开始，可以使用一组新的 CLI 命令来管理映像的生命周期。这包括 [`build-image`](pcluster.build-image-v3.md)、[`list-images`](pcluster.list-images-v3.md)、[`describe-image`](pcluster.describe-image-v3.md) 和 [`delete-image`](pcluster.delete-image-v3.md)。
+ 这种方法是可重复的。您可以重新运行它以保持 AMIs 更新（例如，操作系统更新），然后在更新现有集群时使用它们。
**注意**
如果你 Amazon 在中国分区中使用这种方法，你可能会遇到网络错误。例如，当`pcluster build-image`命令从操作系统存储库 GitHub 或从操作系统存储库下载软件包时，您可能会看到这些错误。如果发生这种情况，我们建议使用以下替代方法之一：
按照[修改 Amazon ParallelCluster AMI](#modify-an-aws-parallelcluster-ami-v3) 方法绕过此命令。
在另一个分区和区域（例如）中构建映像`us-east-1`，然后 store/restore 将其移动到中国区域。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[使用 S3 存储和还原 AMI](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/ami-store-restore.html)。
步骤：
1. 配置您的 Amazon Web Services 账户 证书，以便 Amazon ParallelCluster 客户端可以代表您调用 Amazon API 操作。有关所需权限的列表，请参阅[Amazon Identity and Access Management 中的权限 Amazon ParallelCluster](iam-roles-in-parallelcluster-v3.md)。
1. 创建基本的*构建映像* 配置文件。为此，请指定用于构建映像以及 [`ParentImage`](Build-v3.md#yaml-build-image-Build-ParentImage) 的 [`InstanceType`](Build-v3.md#yaml-build-image-Build-InstanceType)。这些步骤用作创建 AMI 的起点。有关可选构建参数的更多信息，请参阅[映像配置](image-builder-configuration-file-v3.md)。
```
Build:
InstanceType:
ParentImage:
```
1. 使用 CLI 命令[`pcluster build-image`](pcluster.build-image-v3.md)从您作为基础提供的 AMI 开始构建 AMI。 Amazon ParallelCluster
```
$ pcluster build-image --image-id IMAGE_ID --image-configuration IMAGE_CONFIG.yaml --region REGION
{
"image": {
"imageId": "IMAGE_ID",
"imageBuildStatus": "BUILD_IN_PROGRESS",
"cloudformationStackStatus": "CREATE_IN_PROGRESS",
"cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/IMAGE_ID/abcd1234-ef56-gh78-ij90-1234abcd5678",
"region": "us-east-1",
"version": "3.15.0"
}
}
```
**警告**
`pcluster build-image` 使用默认 VPC。如果您使用 Amazon Control Tower 或 Amazon 着陆区删除默认 VPC，则必须在映像配置文件中指定子网 ID。有关更多信息，请参阅 [`SubnetId`](HeadNode-v3.md#yaml-HeadNode-Networking-SubnetId)。
有关其他参数的列表，请参阅 [`pcluster build-image`](pcluster.build-image-v3.md) 命令参考页面。前面命令的结果如下所述：
+ 堆 CloudFormation 栈是根据映像配置创建的。该堆栈包括构建所需的所有 EC2 Image Builder 资源。
+ 创建的资源包括可以向其添加自定义 Image Builder Amazon ParallelCluster 组件的官方 Image Builder 组件。有关更多信息，请参阅 *EC2 Image Builder 用户指南中的使用 Image Builder* [创建自定义组件](https://docs.amazonaws.cn/imagebuilder/latest/userguide/create-component.html)。
+ EC2 Image Builder 启动构建实例、应用说明 Amazon ParallelCluster 书、安装 Amazon ParallelCluster 软件堆栈并执行必要的配置任务。 Amazon ParallelCluster 这本食谱用于构建和引导 Amazon ParallelCluster。
+ 停止该实例，并在其基础上创建新的 AMI。
+ 从新创建的 AMI 启动另一个实例。在测试阶段，EC2 Image Builder 会运行 Image Builder 组件中定义的测试。
+ 如果构建成功，则会删除堆栈。如果构建失败，则会保留堆栈以供检查。
1. 您可以通过运行以下命令来监控构建过程的状态。构建完成后，您可以运行该 AMI 以便检索响应中给出的 AMI ID。
```
$ pcluster describe-image --image-id IMAGE_ID --region REGION
# BEFORE COMPLETE
{
"imageConfiguration": {
"url": "https://parallelcluster-1234abcd5678efgh-v1-do-not-delete.s3.amazonaws.com/parallelcluster/3.15.0/images/IMAGE_ID-abcd1234efgh5678/configs/image-config.yaml?...",
},
"imageId": "IMAGE_ID",
"imagebuilderImageStatus": "BUILDING",
"imageBuildStatus": "BUILD_IN_PROGRESS",
"cloudformationStackStatus": "CREATE_IN_PROGRESS",
"cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/IMAGE_ID/abcd1234-ef56-gh78-ij90-1234abcd5678",
"region": "us-east-1",
"version": "3.15.0",
"cloudformationStackTags": [
{
"value": "3.15.0",
"key": "parallelcluster:version"
},
{
"value": "IMAGE_ID",
"key": "parallelcluster:image_name"
},
...
],
"imageBuildLogsArn": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/imagebuilder/ParallelClusterImage-IMAGE_ID",
"cloudformationStackCreationTime": "2022-04-05T21:36:26.176Z"
}
# AFTER COMPLETE
{
"imageConfiguration": {
"url": "https://parallelcluster-1234abcd5678efgh-v1-do-not-delete.s3.us-east-1.amazonaws.com/parallelcluster/3.15.0/images/IMAGE_ID-abcd1234efgh5678/configs/image-config.yaml?Signature=..."
},
"imageId": "IMAGE_ID",
"imageBuildStatus": "BUILD_COMPLETE",
"region": "us-east-1",
"ec2AmiInfo": {
"amiName": "IMAGE_ID 2022-04-05T21-39-24.020Z",
"amiId": "ami-1234stuv5678wxyz",
"description": "Amazon ParallelCluster AMI for alinux2, kernel-4.14.238-182.422.amzn2.x86_64, lustre-2.10.8-5.amzn2.x86_64, efa-1.13.0-1.amzn2.x86_64, dcv-2021.1.10598-1.el7.x86_64, slurm-20-11-8-1",
"state": "AVAILABLE",
"tags": [
{
"value": "2021.3.11591-1.el7.x86_64",
"key": "parallelcluster:dcv_version"
},
...
],
"architecture": "x86_64"
},
"version": "3.15.0"
}
```
1. 要创建集群，请在集群配置内的 [`CustomAmi`](Scheduling-v3.md#yaml-Scheduling-SlurmQueues-Image-CustomAmi) 字段中输入该 AMI ID。
**对 AMI 创建过程进行故障排除和监控**
映像创建将在大约一个小时后完成。您可以通过运行 [`pcluster describe-image`](pcluster.describe-image-v3.md) 命令或日志检索命令来监控该过程。
```
$ pcluster describe-image --image-id IMAGE_ID --region REGION
```
该[`build-image`](pcluster.build-image-v3.md)命令使用构建映像所需的所有 Amazon EC2 资源创建一个 CloudFormation 堆栈，并启动 EC2 Image Builder 流程。
运行该[`build-image`](pcluster.build-image-v3.md)命令后，可以使用来检索 CloudFormation 堆栈事件[`pcluster get-image-stack-events`](pcluster.get-image-stack-events-v3.md)。您可以使用 `--query` 参数来筛选结果，以查看最新事件。有关更多信息，请参阅《*Amazon Command Line Interface 用户指南》*中的[筛选 Amazon CLI 输出](https://docs.amazonaws.cn/cli/latest/userguide/cli-usage-filter.html)。
```
$ pcluster get-image-stack-events --image-id IMAGE_ID --region REGION --query "events[0]"
{
"eventId": "ParallelClusterImage-CREATE_IN_PROGRESS-2022-04-05T21:39:24.725Z",
"physicalResourceId": "arn:aws:imagebuilder:us-east-1:123456789012:image/parallelclusterimage-IMAGE_ID/3.15.0/1",
"resourceStatus": "CREATE_IN_PROGRESS",
"resourceStatusReason": "Resource creation Initiated",
"resourceProperties": "{\"InfrastructureConfigurationArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:infrastructure-configuration/parallelclusterimage-abcd1234-ef56-gh78-ij90-1234abcd5678\",\"ImageRecipeArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:image-recipe/parallelclusterimage-IMAGE_ID/3.15.0\",\"DistributionConfigurationArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:distribution-configuration/parallelclusterimage-abcd1234-ef56-gh78-ij90-1234abcd5678\",\"Tags\":{\"parallelcluster:image_name\":\"IMAGE_ID\",\"parallelcluster:image_id\":\"IMAGE_ID\"}}",
"stackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/IMAGE_ID/abcd1234-ef56-gh78-ij90-1234abcd5678",
"stackName": "IMAGE_ID",
"logicalResourceId": "ParallelClusterImage",
"resourceType": "AWS::ImageBuilder::Image",
"timestamp": "2022-04-05T21:39:24.725Z"
}
```
大约 15 分钟后，堆栈事件将出现在与 Image Builder 创建相关的日志事件条目中。您现在可以使用 [`pcluster list-image-log-streams`](pcluster.list-image-log-streams-v3.md) 和 [`pcluster get-image-log-events`](pcluster.get-image-log-events-v3.md) 命令列出映像日志流并监控 Image Builder 步骤。
```
$ pcluster list-image-log-streams --image-id IMAGE_ID --region REGION \
--query 'logStreams[*].logStreamName'
"3.15.0/1"
]
$ pcluster get-image-log-events --image-id IMAGE_ID --region REGION \
--log-stream-name 3.15.0/1 --limit 3
{
"nextToken": "f/36295977202298886557255241372854078762600452615936671762",
"prevToken": "b/36295977196879805474012299949460899222346900769983430672",
"events": [
{
"message": "ExecuteBash: FINISHED EXECUTION",
"timestamp": "2022-04-05T22:13:26.633Z"
},
{
"message": "Document arn:aws:imagebuilder:us-east-1:123456789012:component/parallelclusterimage-test-abcd1234-ef56-gh78-ij90-1234abcd5678/3.15.0/1",
"timestamp": "2022-04-05T22:13:26.741Z"
},
{
"message": "TOE has completed execution successfully",
"timestamp": "2022-04-05T22:13:26.819Z"
}
]
}
```
继续使用 [`describe-image`](pcluster.describe-image-v3.md) 命令进行检查，直到看到 `BUILD_COMPLETE` 状态。
```
$ pcluster describe-image --image-id IMAGE_ID --region REGION
{
"imageConfiguration": {
"url": "https://parallelcluster-1234abcd5678efgh-v1-do-not-delete.s3.us-east-1.amazonaws.com/parallelcluster/3.15.0/images/IMAGE_ID-abcd1234efgh5678/configs/image-config.yaml?Signature=..."
},
"imageId": "IMAGE_ID",
"imageBuildStatus": "BUILD_COMPLETE",
"region": "us-east-1",
"ec2AmiInfo": {
"amiName": "IMAGE_ID 2022-04-05T21-39-24.020Z",
"amiId": "ami-1234stuv5678wxyz",
"description": "Amazon ParallelCluster AMI for alinux2, kernel-4.14.238-182.422.amzn2.x86_64, lustre-2.10.8-5.amzn2.x86_64, efa-1.13.0-1.amzn2.x86_64, dcv-2021.1.10598-1.el7.x86_64, slurm-20-11-8-1",
"state": "AVAILABLE",
"tags": [
{
"value": "2021.3.11591-1.el7.x86_64",
"key": "parallelcluster:dcv_version"
},
...
],
"architecture": "x86_64"
},
"version": "3.15.0"
}
```
如果您需要排查自定义 AMI 创建问题，请按照以下步骤所述创建映像日志存档。
可以将日志存档到 Amazon S3 存储桶或本地文件中，具体取决于 `--output` 参数。
```
$ pcluster export-image-logs --image-id IMAGE_ID --region REGION \
--bucket BUCKET_NAME --bucket-prefix BUCKET_FOLDER
{
"url": "https://BUCKET_NAME.s3.us-east-1.amazonaws.com/BUCKET-FOLDER/IMAGE_ID-logs-202209071136.tar.gz?AWSAccessKeyId=..."
}
$ pcluster export-image-logs --image-id IMAGE_ID \
--region REGION --bucket BUCKET_NAME --bucket-prefix BUCKET_FOLDER --output-file /tmp/archive.tar.gz
{
"path": "/tmp/archive.tar.gz"
}
```
该档案包含与 Image Builder 进程和 Amazon CloudFormation 堆栈事件相关的 CloudWatch 日志流。该命令的运行可能需要几分钟才能完成。
**管理自定义 AMIs**
从 Amazon ParallelCluster 3.0.0 开始，CLI 中添加了一组用于构建、监控和管理映像生命周期的新命令。有关这些命令的更多信息，请参阅 [pcluster 命令](pcluster-v3.md)。
## 修改 Amazon ParallelCluster AMI
此方法包括通过在官方 Amazon ParallelCluster AMI 上添加自定义来修改官方 AMI。基础版 Amazon ParallelCluster AMIs 已更新为新版本。它们 AMIs 具有安装和配置后运行所需 Amazon ParallelCluster 的所有组件。您可以以其中一个 AMI 作为起点。
关键点：
+ 此方法比 [`build-image`](pcluster.build-image-v3.md) 命令快。但它是一个手动过程，不会自动重复。
+ 使用此方法，您无权使用通过 CLI 提供的日志检索和映像生命周期管理命令。
步骤：
------
#### [ New Amazon EC2 console ]
1. 找到与您使用的具体内容相对应 Amazon Web Services 区域 的 AMI。要找到它，请使用带有`--region`参数的[`pcluster list-official-images`](pcluster.list-official-images-v3.md)命令来选择特定的 Amazon Web Services 区域 和`--os`和`--architecture`参数，筛选出具有您要使用的操作系统和架构的所需 AMI。从输出中检索 Amazon EC2 映像 ID。
1. 登录 Amazon Web Services 管理控制台 并打开 Amazon EC2 控制台，网址为[https://console.aws.amazon.com/ec2/](https://console.amazonaws.cn/ec2/)。
1. 在导航窗格中，选择 “**图像**”，然后**AMIs**。搜索检索到的 EC2 映像 ID，选择 AMI，然后选择**从 AMI 启动实例**。
1. 向下滚动并选择您的**实例类型**。
1. 选择您的**密钥对**，然后选择**启动实例**。
1. 使用操作系统用户和您的 SSH 密钥登录您的实例。
1. 手动自定义实例以满足您的要求。
1. 运行以下命令以准备实例来创建 AMI。
```
sudo /usr/local/sbin/ami_cleanup.sh
```
1. 在控制台中，选择**实例状态**和**停止实例**。
导航到**实例**，选择新实例，然后依次选择**实例状态**和**停止实例**。
1. 使用 Amazon EC2 控制台或 Amazon CLI [创建映像从实例创建](https://docs.amazonaws.cn/cli/latest/reference/ec2/create-image.html)新 AMI。
**在 Amazon EC2 控制台中**
1. 在导航窗格中选择**实例**。
1. 选择您创建和修改的实例。
1. 在**操作**中，依次选择**映像**和**创建映像**。
1. 选择**创建映像**。
1. 在集群配置内的 [`CustomAmi`](Scheduling-v3.md#yaml-Scheduling-SlurmQueues-Image-CustomAmi) 字段中输入新 AMI ID，并创建集群。
------
#### [ Old Amazon EC2 console ]
1. 找到与您使用的具体内容相对应 Amazon Web Services 区域 的 Amazon ParallelCluster AMI。要找到它，你可以使用带有`--region`参数的[`pcluster list-official-images`](pcluster.list-official-images-v3.md)命令来选择特定的 Amazon Web Services 区域 和`--os`和`--architecture`参数，然后根据你想要使用的操作系统和架构筛选出所需的 AMI。您可以从输出中检索 Amazon EC2 映像 ID。
1. 登录 Amazon Web Services 管理控制台 并打开 Amazon EC2 控制台，网址为[https://console.aws.amazon.com/ec2/](https://console.amazonaws.cn/ec2/)。
1. 在导航窗格中，选择 “**图像**”，然后**AMIs**。针对**公有映像**设置筛选器并搜索检索到的 EC2 映像 ID，选择 AMI，然后选择**启动**。
1. 选择您的实例类型，然后选择**下一步：配置实例详细信息**或**查看并启动**以启动您的实例。
1. 选择**启动**，选择您的**密钥对**，然后选择**启动实例**。
1. 使用操作系统用户和您的 SSH 密钥登录您的实例。有关更多信息，请导航至**实例**，选择新实例，然后选择**连接**。
1. 手动自定义实例以满足您的要求。
1. 运行以下命令以准备实例来创建 AMI：
```
sudo /usr/local/sbin/ami_cleanup.sh
```
1. 在 Amazon EC2 控制台中，从导航窗格中选择**实例**，选择您的新实例，然后依次选择**操作**、**实例状态**和**停止**。
1. 使用 Amazon EC2 控制台或 Amazon CLI [创建映像从实例创建](https://docs.amazonaws.cn/cli/latest/reference/ec2/create-image.html)新 AMI。
**在 Amazon EC2 控制台中**
1. 在导航窗格中选择**实例**。
1. 选择您创建和修改的实例。
1. 在**操作**中，依次选择**映像**和**创建映像**。
1. 选择**创建映像**。
1. 在集群配置内的 [`CustomAmi`](Scheduling-v3.md#yaml-Scheduling-SlurmQueues-Image-CustomAmi) 字段中输入新 AMI ID，并创建集群。
------