Amazon ParallelCluster API - Amazon ParallelCluster
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

Amazon ParallelCluster API

什么是 Amazon ParallelCluster API?

Amazon ParallelCluster API 是一种无服务器应用程序,一旦部署到您的 Amazon Web Services 账户,便可通过 API 以编程方式访问 Amazon ParallelCluster 功能。

Amazon ParallelCluster API 以独立 Amazon CloudFormation 模板的形式分发,其中包括一个公开 Amazon ParallelCluster 功能的 Amazon API Gateway 端点和一个负责处理所调用功能的 Amazon Lambda 函数。

下图显示了 Amazon ParallelCluster API 基础架构的高级架构图。

Amazon ParallelCluster API 文档

描述 Amazon ParallelCluster API 的 OpenAPI 规范文件可以从以下地址下载:

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/ParallelCluster.openapi.yaml

从 OpenAPI 规范文件开始,您可以使用 Swagger UIRedoc 等众多可用工具之一生成 Amazon ParallelCluster API 的文档。

如何部署 Amazon ParallelCluster API

要部署 Amazon ParallelCluster API,您必须是 Amazon Web Services 账户的管理员。

用于部署 API 的模板可在以下 URL 中找到:

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/parallelcluster-api.yaml

其中,<REGION> 是需要部署 API 的 Amazon Web Services 区域,<VERSION> 是 Amazon ParallelCluster 版本(例如 3.7.0)。

Amazon Lambda 通过使用具有 Amazon ParallelCluster Python 库 API 的 Lambda 层界面来处理 API 调用的功能。

警告

Amazon Web Services 账户中对 Amazon Lambda 或 Amazon API Gateway 服务具有访问特权的任何用户将会自动继承管理 Amazon ParallelCluster API 资源的权限。

使用 Amazon CLI 进行部署

配置用于 CLI 的 Amazon 凭证(如果尚未配置)。

$ aws configure

运行以下命令以部署 API:

$ REGION=<region> $ API_STACK_NAME=<stack-name>  # This can be any name $ VERSION=3.7.0 $ aws cloudformation create-stack \   --region ${REGION} \   --stack-name ${API_STACK_NAME} \   --template-url https://${REGION}-aws-parallelcluster.s3.${REGION}.amazonaws.com/parallelcluster/${VERSION}/api/parallelcluster-api.yaml \   --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND $ aws cloudformation wait stack-create-complete --stack-name ${API_STACK_NAME} --region ${REGION}

自定义部署

您可以使用模板公开的 Amazon CloudFormation 参数自定义 API 部署。在通过 CLI 进行部署时,要配置某个参数的值,可以使用以下选项:--parameters ParameterKey=KeyName,ParameterValue=Value

以下参数为可选参数:

  • Region - 使用 Region 参数指定 API 是能够控制全部 Amazon Web Services 区域中的资源(默认)还是单个 Amazon Web Services 区域中的资源。将此值设置为要部署 API 的 Amazon Web Services 区域以限制访问权限。

  • ParallelClusterFunctionRole-这会覆盖分配给实现Amazon LambdaAmazon ParallelCluster功能的函数的 IAM 角色。该参数接受 IAM 角色的 ARN。此类角色需要配置为具有 Amazon Lambda 作为 IAM 主体。

  • CustomDomainName,CustomDomainCertificate,CustomDomainHostedZoneId-使用这些参数为 Amazon API Gateway 终端节点设置自定义域。 CustomDomainName是要使用的域名,CustomDomainCertificate是该域名的Amazon托管证书的 ARN,CustomDomainHostedZoneId也是您要在其中创建记录的 A mazon Route 53 托管区域的 ID。

    警告

    您可以配置自定义域设置,以对 API 强制使用最低版本的传输层安全性协议 (TLS)。有关更多信息,请参阅在 API Gateway 中为自定义域选择最低 TLS 版本

  • EnableIamAdminAccess-默认情况下,Amazon Lambda函数处理 Amazon ParallelCluster API 操作配置为阻止任何特权 IAM 访问的 IAM 角色 (EnableIamAdminAccess=false)。这使得 API 无法处理需要创建 IAM 角色或策略的操作。因此,只有在资源配置过程中提供 IAM 角色作为输入时,才能成功创建集群或自定义映像。

    EnableIamAdminAccess 设置为 true 时,Amazon ParallelCluster API 将获得相应的权限来管理某些操作,例如创建部署集群或生成自定义 AMI 所需的 IAM 角色。

    警告

    将其设置为 true 将为处理 Amazon ParallelCluster 操作的 Amazon Lambda 函数授予 IAM 管理员权限。

    有关启用此模式后可以解锁的功能的更多详细信息,请参阅用于管理 IAM 资源的 Amazon ParallelCluster 用户示例策略

  • PermissionsBoundaryPolicy-此可选参数接受现有 IAM 策略 ARN,该策略将被设置为 PC API 基础设施创建的所有 IAM 角色的权限边界,并设置为管理 IAM 权限的条件,因此 PC API 只能创建具有此策略的角色。

    有关此模式施加的限制的更多详细信息,请参阅 PermissionsBoundary 模式

  • CreateApiUserRole-默认情况下,Amazon ParallelClusterAPI 的部署包括创建 IAM 角色,该角色被设置为唯一有权调用 API 的角色。 Amazon API Gateway 终端节点配置了基于资源的策略,仅向创建的用户授予调用权限。 要更改此设置,请设置CreateApiUserRole=false并向选定的 IAM 用户授予 API 访问权限。有关更多信息,请参阅 Amazon API Gateway 开发人员指南 中的针对调用 API 的访问控制

    警告

    当 API 端点的 CreateApiUserRole=true 访问不受 Amazon API Gateway 资源策略限制时,拥有不受限制的 execute-api:Invoke 权限的所有 IAM 角色都可以访问 Amazon ParallelCluster 功能。有关更多信息,请参阅 API Gateway 开发人员指南 中的使用 API Gateway 资源策略控制对 API 的访问

    警告

    ParallelClusterApiUserRole 有权调用所有 Amazon ParallelCluster API 操作。要限制对一部分 API 资源的访问,请参阅 API Gateway 开发人员指南 中的控制谁可以使用 IAM 策略调用 API Gateway API 方法

  • IAM RoleAndPolicyPrefix-此可选参数接受最多 10 个字符的字符串,该字符串将用作作为 PC API 基础设施一部分创建的 IAM 角色和策略的前缀。

更新 API

升级到较新的 Amazon ParallelCluster 版本

选项 1:通过删除相应的 Amazon CloudFormation 堆栈并按照上文所示部署新 API 来移除现有 API。

选项 2:通过运行以下命令更新现有 API:

$ REGION=<region> $ API_STACK_NAME=<stack-name>  # This needs to correspond to the existing API stack name $ VERSION=3.7.0 $ aws cloudformation update-stack \   --region ${REGION} \   --stack-name ${API_STACK_NAME} \   --template-url https://${REGION}-aws-parallelcluster.s3.${REGION}.amazonaws.com/parallelcluster/${VERSION}/api/parallelcluster-api.yaml \   --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND $ aws cloudformation wait stack-update-complete --stack-name ${API_STACK_NAME} --region ${REGION}

调用 Amazon ParallelCluster API

Amazon ParallelClusterAmazon API Gateway 端点配置了 AWS_IAM 授权类型,要求所有请求都必须使用有效的 IAM 凭证进行 SigV4 签名(API 参考:发出 http 请求)。

使用默认设置进行部署时,API 调用权限仅授予给使用 API 创建的默认 IAM 用户。

要检索默认 IAM 用户的 ARN,请运行:

$ REGION=<region> $ API_STACK_NAME=<stack-name> $ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiUserRole'].OutputValue" --output text

要获取默认 IAM 用户的临时证书,请运行 STS AssumeRole 命令。

您可以通过运行以下命令来检索 Amazon ParallelCluster API 端点:

$ REGION=<region> $ API_STACK_NAME=<stack-name> $ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiInvokeUrl'].OutputValue" --output text

符合 OpenAPI 规范的任何 HTTP 客户端都可以调用 Amazon ParallelCluster API,OpenAPI 规范可以在此处找到:

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/ParallelCluster.openapi.yaml

请求必须按照此处所述进行 SigV4 签名。

目前,我们不提供任何官方 API 客户端实现。不过,通过使用 OpenAPI Generator,可以从 OpenAPI 模型中轻松生成 API 客户端。生成客户端后,如果没有现成的签名,则需要添加 SigV4 签名。

可以在 Amazon ParallelCluster 存储库中找到 Python API 客户端的参考实现。要详细了解如何使用 Python API 客户端,请参阅使用 Amazon ParallelCluster API 教程。

要实施更高级的访问控制机制,例如 Amazon Cognito 或 Lambda Authorizer,或者要使用 Amazon WAF 或 API 密钥进一步保护 API,请按照 Amazon API Gateway 文档进行操作。

警告

有权调用 Amazon ParallelCluster API 的 IAM 用户可以间接控制由 Amazon Web Services 账户中的 Amazon ParallelCluster 管理的所有 Amazon 资源。这包括创建该用户由于用户 IAM 策略的限制而无法直接控制的 Amazon 资源。例如,根据配置,Amazon ParallelCluster 集群的创建可能包括部署 Amazon EC2 实例、Amazon Route 53、Amazon Elastic File System 文件系统、Amazon FSx 文件系统、IAM 角色以及来自 Amazon ParallelCluster 使用的其他 Amazon Web Services的资源,用户可能无法直接控制这些资源。

警告

使用配置中指定的 AdditionalIamPolicies 创建集群时,其他策略必须与以下模式之一匹配:

- !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster* - !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster/* - !Sub arn:${AWS::Partition}:iam::aws:policy/CloudWatchAgentServerPolicy - !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonSSMManagedInstanceCore - !Sub arn:${AWS::Partition}:iam::aws:policy/AWSBatchFullAccess - !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonS3ReadOnlyAccess - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSBatchServiceRole - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2SpotFleetTaggingRole - !Sub arn:${AWS::Partition}:iam::aws:policy/EC2InstanceProfileForImageBuilder - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

如果需要其他策略,则可以执行以下操作之一:

  • 在以下文件中编辑 DefaultParallelClusterIamAdminPolicy

    https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/parallelcluster-api.yaml

    将策略添加在 ArnLike/iam:PolicyARN 部分中。

  • 省略在配置文件中为 AdditionalIamPolicies 指定策略,并手动向在集群中创建的 Amazon ParallelCluster 实例角色添加策略。

访问 API 日志和数据记录

API 日志发布到亚马逊 CloudWatch ,保留期为 30 天。要检索与 API 部署关联的 LogGroup 名称,请运行以下命令:

$ REGION=<region> $ API_STACK_NAME=<stack-name> $ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaLogGroup'].OutputValue" --output text

也可以通过 Lambda 控制台访问 Lambda 数据记录、日志和 Amazon X-Ray 跟踪日志。要检索与 API 部署关联的 Lambda 函数的 ARN,请运行以下命令:

$ REGION=<region> $ API_STACK_NAME=<stack-name> $ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaArn'].OutputValue" --output text