本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS ParallelCluster Python 库 API 从 3.5.0 AWS ParallelCluster 版本开始，你可以使用 AWS ParallelCluster Python 库 AWS ParallelCluster 进行访问。您可以在自己的`pcluster`环境中或在 AWS Lambda 运行时中访问该 AWS ParallelCluster 库。了解如何使用 AWS ParallelCluster Python 库访问 AWS ParallelCluster 该 API。P AWS ParallelCluster ython 库提供的功能与 AWS ParallelCluster API 提供的功能相同。 AWS ParallelCluster Python 库的操作和参数在转换为不`snake_case`使用大写字母时会反映 API 参数的操作和参数。 **Topics** + [AWS ParallelCluster Python 库授权](#pc-py-lib-auth) + [安装 AWS ParallelCluster Python 库](#pc-py-lib-install) + [集群 API 操作](pc-py-lib-api-cluster.md) + [计算实例集 API 操作](pc-py-lib-api-fleet.md) + [集群和堆栈日志操作](pc-py-lib-api-logs-cluster-stack.md) + [映像 API 操作](pc-py-lib-api-image.md) + [映像和堆栈日志操作](pc-py-lib-api-logs-image-stack.md) + [示例](pc-py-lib-api-examples.md) + [AWS Lambda 用于 AWS ParallelCluster Python 库](#lambda-py-v3) ## AWS ParallelCluster Python 库授权 使用对 boto3 有效的任何标准方式指定凭证。有关更多信息，请参阅 [boto3 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration)。 ## 安装 AWS ParallelCluster Python 库 1. 按照[设置 AWS ParallelCluster](install-v3.md) 中的说明安装 `pcluster` CLI 版本 3.5.0 或更高版本。 1. 导入 `pcluster` 模块并开始使用库，如以下示例所示： ``` import pcluster.lib as pc pc.create_cluster(cluster_name="mycluster", cluster_configuration="config.yaml" ``` # 集群 API 操作 **Topics** + [`list_clusters`](pc-py-lib-api-cluster-list.md) + [`create_cluster`](pc-py-lib-api-cluster-create.md) + [`delete_cluster`](pc-py-lib-api-cluster-delete.md) + [`describe_cluster`](pc-py-lib-api-cluster-describe.md) + [`update_cluster`](pc-py-lib-api-cluster-update.md) # `list_clusters` ``` list_clusters(region, next_token, cluster_status) ``` 检索现有集群的列表。参数： **`region`** 列出部署到给定对象的集群 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 **`cluster_status`** 按集群状态筛选。默认为列出所有集群。 有效值：`CREATE_IN_PROGRESS` \$1 `CREATE_FAILED` \$1 `CREATE_COMPLETE` \$1 `DELETE_IN_PROGRESS` \$1 `DELETE_FAILED` \$1 `UPDATE_IN_PROGRESS` \$1 `UPDATE_COMPLETE` \$1 `UPDATE_FAILED` # `create_cluster` ``` create_cluster(cluster_name, cluster_configuration, region, suppress_validators, validation_failure_level, dry_run, rollback_on_failure, wait) ``` 在指定区域内创建集群。参数： **`cluster_name`（必需）** 集群名称。 **`cluster_configuration`（必需）** 作为 Python 数据类型的集群配置。 **`region`** 集群 AWS 区域。 **`suppress_validators`** 标识一个或多个要禁止的集群配置验证器。 格式：`(ALL | type:[A-Za-z0-9]+)` **`validation_failure_level`** 导致集群创建失败的最低验证级别。默认值为 `ERROR`。 有效值：`INFO` \$1 `WARNING` \$1 `ERROR`。 **`dry_run`** 执行请求验证而不创建任何资源。您可以使用此参数来验证集群配置。默认值为 `False`。 **`rollback_on_failure`** 如果设置为`True`，则在 AWS ParallelCluster 出现故障时自动启动集群堆栈回滚。默认值为 `True`。 **`wait`** 如果设置为 `True`，则 AWS ParallelCluster 等待操作完成。默认值为 `False`。 # `delete_cluster` ``` delete_cluster(cluster_name, region, wait) ``` 删除指定区域中的集群。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 **`wait`** 如果设置为 `True`，则等待操作完成。默认值为 `False`。 # `describe_cluster` ``` describe_cluster(cluster_name, region) ``` 获取有关现有集群的详细信息。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 # `update_cluster` ``` update_cluster(cluster_name, cluster_configuration, suppress_validators, validation_failure_level, region, force_update, dry_run, wait) ``` 更新指定区域中的集群。参数： **`cluster_name`（必需）** 集群名称。 **`cluster_configuration`（必需）** 作为 Python 数据类型的集群配置。 **`suppress_validators`** 标识一个或多个要禁止的集群配置验证器。 格式：`(ALL | type:[A-Za-z0-9]+)` **`validation_failure_level`** 导致集群更新失败的最低验证级别。默认值为 `ERROR`。 有效值：`INFO` \$1`WARNING` \$1`ERROR` **`region`** 集群 AWS 区域。 **`dry_run`** 执行请求验证而不创建或更新任何资源。您可以使用此参数来验证集群配置。默认值为 `False`。 **`force_update`** 如果设置为 `True`，则通过忽略更新验证错误强制更新。默认值为 `False`。 **`wait`** 如果设置为 `True`，则等待操作完成。默认值为 `False`。 # 计算实例集 API 操作 **Topics** + [`describe_compute_fleet`](pc-py-lib-api-fleet-describe.md) + [`update_compute_fleet`](pc-py-lib-api-fleet-update.md) + [`delete_cluster_instances`](pc-py-lib-api-fleet-delete.md) + [`describe_cluster_instances`](pc-py-lib-api-fleet-describe-instances.md) # `describe_compute_fleet` ``` describe_compute_fleet(cluster_name, region) ``` 描述指定集群的集群计算实例集的状态。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 描述部署到给定集群的计算队列状态 AWS 区域。 # `update_compute_fleet` ``` update_compute_fleet(cluster_name, status, region) ``` 更新集群计算实例集的状态。参数： **`cluster_name`（必需）** 集群名称。 **`status`（必需）** 要更新到的状态。 有效值：`START_REQUESTED` \$1 `STOP_REQUESTED` \$1 `ENABLED` \$1 `DISABLED` **`region`** 集群 AWS 区域。 # `delete_cluster_instances` ``` delete_cluster_instances(cluster_name, region, force) ``` 开始强制终止所有集群计算节点。此操作不支持 AWS Batch 集群。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 **`force`** 如果设置为 `True`，则在找不到具有指定 `cluster_name` 的集群时强制删除。默认值为 `False`。 # `describe_cluster_instances` ``` describe_cluster_instances(cluster_name, region, next_token, node_type, queue_name) ``` 描述集群的实例。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 **`node_type`** 按 `node_type` 筛选实例。 有效值：`HeadNode` \$1 `ComputeNode` **`queue_name`** 按队列名称筛选实例。 # 集群和堆栈日志操作 **Topics** + [`list_cluster_log_streams`](pc-py-lib-api-logs-cluster-stack-log-streams.md) + [`get_cluster_log_events`](pc-py-lib-api-logs-cluster-stack-log-events.md) + [`get_cluster_stack_events`](pc-py-lib-api-logs-cluster-stack-log-stack-events.md) # `list_cluster_log_streams` ``` list_cluster_log_streams(cluster_name, region, filters, next_token) ``` 列出指定集群的日志流。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 **`filters`** 筛选集群日志流。 格式：`'Name=a,Values=1 Name=b,Values=2,3'` **接受的筛选器：** **code-dns-name** 实例私有 DNS 名称的短格式；例如 `ip-10-0-0-101`。 **node-type** 节点类型。 有效值：`HeadNode` **`next_token`** 用于获取下一组结果的令牌。 # `get_cluster_log_events` ``` get_cluster_log_events(cluster_name, log_stream_name, region, next_token, start_from_head, limit, start_time, end_time) ``` 获取指定集群和日志流的日志事件。参数： **`cluster_name`（必需）** 集群名称。 **`log_stream_name`（必需）** 日志流名称。 **`region`** 集群 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 **`start_from_head`** 如果设置为`True`，则首先 AWS ParallelCluster 返回最早的日志事件。如果设置为 `False`，则最先返回最新的日志事件。默认值为 `False`。 **`limit`** 返回的日志事件的最大数目。如果不指定值，则最大值为 1 MB 的响应大小所能容纳的日志数量，最多可达 10000 个日志事件。 **`start_time`** 日志事件时间范围的开始时间，以 ISO 8601 格式表示，例如 `'2021-01-01T20:00:00Z'`。包括时间戳等于或晚于该时间的事件。 **`end_time`** 日志事件时间范围的结束时间，以 ISO 8601 格式表示，例如 `'2021-01-01T20:00:00Z'`。不包括时间戳等于或晚于该时间的事件。 # `get_cluster_stack_events` ``` get_cluster_stack_events(cluster_name, region, next_token) ``` 获取指定集群的堆栈事件。参数： **`cluster_name`（必需）** 集群名称。 **`region`** 集群 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 # 映像 API 操作 **Topics** + [`list_images`](pc-py-lib-api-image-list.md) + [`build_image`](pc-py-lib-api-image-build.md) + [`delete_image`](pc-py-lib-api-image-delete.md) + [`describe_image`](pc-py-lib-api-image-describe.md) # `list_images` ``` list_images(image_status, region, next_token) ``` 检索现有映像的列表。参数： **`image_status`（必需）** 按映像状态筛选。 有效值：`AVAILABLE` \$1`PENDING` \$1`FAILED` **`region`** 列出在指定 AWS 区域中构建的映像。 **`next_token`** 用于获取下一组结果的令牌。 # `build_image` ``` build_image(image_configuration, image_id, suppress_validators, validation_failure_level, dry_run, rollback_on_failure, region) ``` 在给定区域创建自定义 AWS ParallelCluster 镜像。参数： **`image_configuration`（必需）** 作为 Python 数据的映像配置。 **`image_id`（必需）** 映像 ID。 **`suppress_validators`** 标识一个或多个要禁止的映像配置验证器。 格式：`(ALL | type:[A-Za-z0-9]+)` **`validation_failure_level`** 导致映像创建失败的最低验证级别。默认值为 `ERROR`。 有效值：`INFO` \$1`WARNING` \$1`ERROR` **`dry_run`** 如果设置为`True`，则在不创建任何资源的情况下 AWS ParallelCluster 执行请求验证。您可以使用此参数来验证映像配置。默认值为 `False`。 **`rollback_on_failure`** 如果设置为`True`，则在 AWS ParallelCluster 出现故障时自动启动映像堆栈回滚。默认值为 `False`。 **`region`** 映像 AWS 区域。 # `delete_image` ``` delete_image(image_id, region, force) ``` 删除指定区域中的映像。参数： **`image_id`（必需）** 映像 ID。 **`region`** 映像 AWS 区域。 **`force`** 如果设置为`True`，则如果实例正在使用 AMI 或 AMI 已共享，则 AWS ParallelCluster 强制删除。默认值为 `False`。 # `describe_image` ``` describe_image(image_id, region) ``` 获取有关现有映像的详细信息。参数： **`image_id`（必需）** 映像 ID。 **`region`** 映像 AWS 区域。 # 映像和堆栈日志操作 **Topics** + [`list_image_log_streams`](pc-py-lib-api-logs-image-stack-log-streams.md) + [`get_image_log_events`](pc-py-lib-api-logs-image-stack-log-events.md) + [`get_image_stack_events`](pc-py-lib-api-logs-image-stack-log-stack-events.md) + [`list_official_images`](pc-py-lib-api-logs-list-official-images.md) # `list_image_log_streams` ``` list_image_log_streams(image_id, region, next_token) ``` 列出映像的日志流。参数： **`image_id`（必需）** 映像 ID。 **`region`** 映像 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 # `get_image_log_events` ``` get_image_log_events(image_id, log_stream_name, region, next_token, start_from_head, limit, start_time, end_time) ``` 获取指定映像和日志流的日志事件。参数： **`image_id`（必需）** 映像 ID。 **`log_stream_name`（必需）** 日志流名称。 **`region`** 映像 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 **`start_from_head`** 如果设置为`True`，则首先 AWS ParallelCluster 返回最早的日志事件。如果设置为 `False`，则最先返回最新的日志事件。默认值为 `False`。 **`limit`** 返回的日志事件的最大数目。如果不指定值，则最大值为 1 MB 的响应大小所能容纳的日志数量，最多可达 10000 个日志事件。 **`start_time`** 日志事件时间范围的开始时间，以 ISO 8601 格式表示，例如 `'2021-01-01T20:00:00Z'`。包括时间戳等于或晚于该时间的事件。 **`end_time`** 日志事件时间范围的结束时间，以 ISO 8601 格式表示，例如 `'2021-01-01T20:00:00Z'`。不包括时间戳等于或晚于该时间的事件。 # `get_image_stack_events` ``` get_image_stack_events(image_id, region, next_token) ``` 获取指定映像的堆栈事件。参数： **`image_id`（必需）** 映像 ID。 **`region`** 映像 AWS 区域。 **`next_token`** 用于获取下一组结果的令牌。 # `list_official_images` ``` list_official_images(region,os, architecture) ``` 检索官方 AWS ParallelCluster 图片列表。参数： **`region`** 映像 AWS 区域。 **`os`** 按操作系统分发进行筛选。默认为不筛选。 **`architecture`** 按架构筛选。默认为不筛选。 # 示例 **Topics** + [创建集群](#pc-py-lib-api-examples-create-cluster) ## 创建集群 当您运行以下示例脚本时，在将指定的输入存储在您的环境中后，您就会创建一个集群。集群配置是根据[集群配置文档](cluster-configuration-file-v3.md)作为一种 Python 数据类型创建的。 ``` import os import pprint import pcluster.lib as pc pp = pprint.PrettyPrinter() HEAD_NODE_SUBNET = os.environ["HEAD_NODE_SUBNET"] COMPUTE_NODE_SUBNET = os.environ["HEAD_NODE_SUBNET"] KEY_NAME = os.environ["KEY_NAME"] CONFIG = {'Image': {'Os': 'alinux2'}, 'HeadNode': {'InstanceType': 't2.large', 'Networking': {'SubnetId': HEAD_NODE_SUBNET}, 'Ssh': {'KeyName': KEY_NAME}}, 'Scheduling': {'Scheduler': 'slurm', 'SlurmQueues': [{'Name': 'queue0', 'ComputeResources': [{'Name': 'queue0-i0', 'InstanceType': 't2.micro', 'MinCount': 0, 'MaxCount': 10}], 'Networking': {'SubnetIds': [COMPUTE_NODE_SUBNET]}}]}} pp.pprint(pc.create_cluster(cluster_name="mycluster", cluster_configuration=CONFIG)) ``` **输出**： ``` {'cluster': {'cloudformationStackArn': 'arn:aws:cloudformation:us-east-2:123456789012:stack/mycluster/00000000-aaaa-1111-999-000000000000', 'cloudformationStackStatus': 'CREATE_IN_PROGRESS', 'clusterName': 'mycluster', 'clusterStatus': 'CREATE_IN_PROGRESS', 'region': 'us-east-2', 'scheduler': {'type': 'slurm'}, 'version': '3.15.0'}} ``` ## AWS Lambda 用于 AWS ParallelCluster Python 库 您可以部署 Lambda 层和运行时来访问 Pyth AWS ParallelCluster on 库。我们托管 AWS ParallelCluster zip 文件，您可以按照以下步骤中的说明输入指向 zip 文件的链接来使用这些文件。Lambda 使用 zip 文件来准备运行时系统环境，以支持对 Python 库的访问。 AWS ParallelCluster Python 库是在 3.5.0 AWS ParallelCluster 版本中添加的。您只能对版本 3.5.0 和更高版本使用该库。 托管的 zip 文件 URL 的格式为：`s3://aws-region-id-aws-parallelcluster/parallelcluster/3.15.0/layers/aws-parallelcluster/lambda-layer.zip`。（*3.15.0*替换为下一步中要使用的 AWS ParallelCluster 版本。） ### 使用以下命令开始访问 P AWS ParallelCluster ython 库 AWS Lambda **创建 Lambda 层** 1. 登录 AWS 管理控制台 并导航到 AWS Lambda 控制台。 1. 在导航窗格中选择**层**，然后选择**创建层**。 1. 输入层的名称，然后选择**从 Amazon S3 上传文件**。 1. 输入 zip 文件的 URL：s3://*aws-region-id*-aws-parallelcluster/parallel *3.15.0* cluster//-layer.zip。layers/aws-parallelcluster/lambda 1. 对于**兼容架构**，选择 **x86\$164** 架构。 1. 对于**兼容运行时**，请选择 **Python 3.12** 运行时。 1. 选择**创建**。 **使用 Lambda 层** 1. 在 Lambda 控制台导航窗格中，依次选择**函数**、**创建函数**。 1. 输入您的函数的名称。 1. 在 “**运行时**” 中，选择 **Python 3.12** 运行时。 1. 对于**架构**，选择 **x86\$164** 架构。 1. 选择**创建函数**。 1. 创建函数后，选择**层**，然后选择**添加层**。 1. 选择**自定义层**，然后选择您在之前的步骤中创建的层。 1. 选择层版本。 1. 选择**添加**。 1. 您的 Lambda 需要权限才能管理使用创建的集群。 AWS ParallelCluster创建具有[基本 AWS ParallelCluster `pcluster` 用户策略](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-base-user-policy)中所列权限的 Lambda 角色。 现在，您可以 AWS ParallelCluster 从 Python 库中进行访问，如中所述[AWS ParallelCluster Python 库 API](#pc-py-library-v3)。