本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS ParallelCluster API
**什么是 AWS ParallelCluster API？**
AWS ParallelCluster API 是一种无服务器应用程序，一旦部署到您的应用程序 AWS 账户，便可通过 API 提供对 AWS ParallelCluster 功能的编程访问。
AWS ParallelCluster API 以独立[CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)模板的形式分发，其中包括一个公开 AWS ParallelCluster 功能的 [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 终端节点和一个负责处理所调用[AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)功能的函数。
下图显示了 AWS ParallelCluster API 基础架构的高级架构图。
![\[a high-level architecture diagram of the ParallelCluster API infrastructure\]](http://docs.aws.amazon.com/zh_cn/parallelcluster/latest/ug/images/API-Architecture-r2.png)
## AWS ParallelCluster API 文档
描述该 API 的 OpenAPI 规范文件可以从以下网址下载： AWS ParallelCluster
```
https://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/ParallelCluster.openapi.yaml
```
从 OpenAPI 规范文件开始，你可以使用 [Swagger UI 或 Redoc 等众多可用工具中的一个来生成 API](https://swagger.io/tools/swagger-ui/) [的文档](https://github.com/Redocly/redoc)。 AWS ParallelCluster
**如何部署 AWS ParallelCluster API**
要部署 AWS ParallelCluster API，你需要成为 API 的管理员 AWS 账户。
用于部署 API 的模板可在以下 URL 中找到：
```
https://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/parallelcluster-api.yaml
```
哪里``是需要部署 API AWS 区域 的地方，``是 AWS ParallelCluster 版本（例如 3.15.0）。
AWS Lambda 使用带有 Lambda 层接口[AWS ParallelCluster Python 库 API](pc-py-library-v3.md)来处理 API 调用的功能。
**警告**
中任何有权访问我们的 AWS 账户 Amazon API Gateway 服务的用户都会自动继承管理 AWS ParallelCluster API 资源的权限。 AWS Lambda
# 使用以下方式部署 AWS ParallelCluster API AWS CLI
在本节中，您将学习如何使用进行部署 AWS CLI。
如果您尚未配置要与 CLI 一起使用的 AWS 凭证，请执行此操作。
```
$ aws configure
```
运行以下命令以部署 API：
```
$ REGION=
$ API_STACK_NAME= # This can be any name
$ VERSION=3.15.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}
```
**自定义部署**
您可以使用模板公开的 CloudFormation 参数来自定义 API 部署。要在通过 CLI 部署时配置参数的值，可以使用以下选项：`--parameters ParameterKey=KeyName,ParameterValue=Value`。
以下参数可选：
+ **区域**-使用`Region`参数指定 API 是能够控制全部资源 AWS 区域 （默认）还是单个资源 AWS 区域。将此值设置 AWS 区域 为要部署的 API 以限制访问权限。
+ **ParallelClusterFunctionRole**-这会覆盖分配给实现 AWS ParallelCluster 功能的 AWS Lambda 函数的 IAM 角色。该参数接受 IAM 角色的 ARN。需要将此角色配置为 AWS Lambda 作为 IAM 委托人。此外，由于此角色将取代 API Lambda 函数的默认角色，因此它必须至少具有 API 所需的默认权限，如中所列。[AWS ParallelCluster `pcluster`用户策略示例](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-example-user-policies)
+ **ParallelClusterFunctionAdditionalPolicies**-要附加到 AWS ParallelCluster API 函数角色的其他 IAM 策略的 ARN。只能指定一个策略。
+ **CustomDomainName，CustomDomainCertificate，CustomDomainHostedZoneId**-使用这些参数为 Amazon API Gateway 终端节点设置自定义域。 `CustomDomainName`是要使用的域名，`CustomDomainCertificate`是该域名的 AWS 托管证书的 ARN，`CustomDomainHostedZoneId`也是您要在其中创建记录的 A [mazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) 托管区域的 ID。
**警告**
您可以配置自定义域设置，以对 API 强制使用最低版本的传输层安全性协议 (TLS)。有关更多信息，请参阅[在 API Gateway 中为自定义域选择最低 TLS 版本](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-custom-domain-tls-version.html)。
+ **EnableIamAdminAccess**-默认情况下，处理 AWS ParallelCluster API 操作的 AWS Lambda 函数配置为阻止任何特权 IAM 访问的 IAM 角色 (`EnableIamAdminAccess=false`)。这使得 API 无法处理需要创建 IAM 角色或策略的操作。因此，只有在资源配置过程中提供 IAM 角色作为输入时，才能成功创建集群或自定义映像。
当设置`EnableIamAdminAccess`为`true`时， AWS ParallelCluster API 将获得管理部署集群或生成自定义集群所需的 IAM 角色创建的权限 AMIs。
**警告**
如果将其设置为 true，则会向处理 AWS ParallelCluster 操作的 AWS Lambda 函数授予 IAM 管理员权限。
有关启用此模式时可以解锁的功能的更多详细信息，请参阅。[AWS ParallelCluster 用于管理 IAM 资源的用户示例策略](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-user-policy-manage-iam)
+ **PermissionsBoundaryPolicy**-此可选参数接受现有 IAM 策略 ARN，该策略将被设置为 PC API 基础设施创建的所有 IAM 角色的权限边界，并设置为管理 IAM 权限的条件，因此 PC API 只能创建具有此策略的角色。
有关此模式施加的限制的更多详细信息，请参阅 [`PermissionsBoundary` 模式](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-permissionsboundary-mode)。
+ **CreateApiUserRole**-默认情况下， AWS ParallelCluster API 的部署包括创建 IAM 角色，该角色被设置为唯一有权调用 API 的角色。 Amazon API Gateway 终端节点配置了基于资源的策略，仅向创建的用户授予调用权限。 要更改此设置，请设置`CreateApiUserRole=false`并向选定的 IAM 用户授予 API 访问权限。有关更多信息，请参阅 *Amazon API Gateway 开发者指南中的控制调用 API* [的访问权限](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html)。
**警告**
如果`CreateApiUserRole=true`对 API 终端节点的访问不受到 Amazon API Gateway 资源策略的限制，则所有拥有不受限制`execute-api:Invoke`权限的 IAM 角色都可以访问 AWS ParallelCluster 功能。有关更多信息，请参阅《API Gat [eway *开发者指南》中的使用 API Gateway 资源策略控制 API* 的访问权限](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)。
**警告**
`ParallelClusterApiUserRole` 有权调用所有 AWS ParallelCluster API 操作。要限制对一部分 API 资源的访问，请参阅《API [Gateway *开发者指南》中的使用 IAM 策略控制谁可以调用 API Gateway API* 方法](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-who-can-invoke-an-api-method-using-iam-policies)。
+ **IAMRoleAndPolicyPrefix**-此可选参数接受一个最多包含 10 个字符的字符串，该字符串将用作作为 PC API 基础设施一部分创建的 IAM 角色和策略的前缀。
# 更新 API
在本节中，您将学习如何使用两个可用选项之一来更新 API。
**升级到新 AWS ParallelCluster 版本**
选项 1：要移除现有 API，请删除相应的 CloudFormation 堆栈并部署新的 API，如上所示。
选项 2：要更新现有 API，请运行以下命令：
```
$ REGION=
$ API_STACK_NAME= # This needs to correspond to the existing API stack name
$ VERSION=3.15.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}
```
# 正在调用 API AWS ParallelCluster
AWS ParallelCluster Amazon API Gateway 终端节点配置了[`AWS_IAM`授权类型](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html#api-gateway-control-access-iam-permissions-model-for-calling-api)，要求所有请求都必须使用有效的 IAM 凭证进行 Sigv4 签名（[API 参考：发出 http 请求](https://docs.aws.amazon.com/apigateway/api-reference/making-http-requests/)）。
使用默认设置进行部署时，API 调用权限仅授予给使用 API 创建的默认 IAM 用户。
要检索默认 IAM 用户的 ARN，请运行：
```
$ REGION=
$ API_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](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/assume-role.html) 命令。
要检索 AWS ParallelCluster API 端点，请运行以下命令：
```
$ REGION=
$ API_STACK_NAME=
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiInvokeUrl'].OutputValue" --output text
```
该 AWS ParallelCluster API 可以由任何符合 OpenAPI 规范的 HTTP 客户端调用，可以在此处找到：
```
https://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/ParallelCluster.openapi.yaml
```
请求必须按照[此处](https://docs.aws.amazon.com/apigateway/api-reference/signing-requests)所述进行 SigV4 签名。
目前，我们不提供任何官方 API 客户端实现。但是，您可以使用 [OpenAPI 生成器](https://openapi-generator.tech/)轻松地从 OpenAPI 模型生成 API 客户端。生成客户端后，如果没有开箱即用，则需要添加 Sigv4 签名。
可以在 [AWS ParallelCluster 存储库](https://github.com/aws/aws-parallelcluster/tree/develop/api/client/src)中找到 Python API 客户端的参考实现。要详细了解如何使用 Python API 客户端，请参阅[使用 AWS ParallelCluster API](tutorials_06_API_use.md) 教程。
[要实施更高级的访问控制机制，例如亚马逊 Cognito 或 Lambda 授权者，或者要使用或 API 密钥进一步保护 API，请按照 Amazon API Gateway 文档进行 AWS WAF 操作。](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html)
**警告**
有权调用 AWS ParallelCluster API 的 IAM 用户可以间接控制 AWS ParallelCluster 中管理的所有 AWS 资源 AWS 账户。这包括创建由于用户 IAM 策略的限制而导致用户无法直接控制的 AWS 资源。例如，根据集群的配置，创建 AWS ParallelCluster 集群可能包括部署 Amazon EC2 实例、Amazon Route 53、Amazon Elastic File System FSx 文件系统、Amazon 文件系统、IAM 角色以及用户可能无法直接控制的其他 AWS 服务 资源。 AWS ParallelCluster
**警告**
使用配置中`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://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/parallelcluster-api.yaml
```
将策略添加在 `ArnLike/iam:PolicyARN` 部分中。
不要在配置文件`AdditionalIamPolicies`中为指定策略，而是手动将策略添加到集群内创建的 AWS ParallelCluster 实例角色中。
# 访问 API 日志和数据记录
API 日志发布到亚马逊 CloudWatch ，保留期为 30 天。要检索与 API 部署关联的 LogGroup 名称，请运行以下命令：
```
$ REGION=
$ API_STACK_NAME=
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaLogGroup'].OutputValue" --output text
```
也可以通过 Lambda 控制台访问 Lambda 数据记录、日志和 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) 跟踪日志。要检索与 API 部署关联的 Lambda 函数的 ARN，请运行以下命令：
```
$ REGION=
$ API_STACK_NAME=
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaArn'].OutputValue" --output text
```