本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS ParallelCluster API
**什麼是 AWS ParallelCluster API？**
AWS ParallelCluster API 是一種無伺服器應用程式，一旦部署到您的 AWS 帳戶，即可透過 API 以程式設計方式存取 AWS ParallelCluster 功能。
AWS ParallelCluster API 是以包含 [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 端點的獨立[CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)範本進行分佈，該端點會公開 AWS ParallelCluster 功能和 [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_tw/parallelcluster/latest/ug/images/API-Architecture-r2.png)
## AWS ParallelCluster API 文件
描述 AWS ParallelCluster API 的 OpenAPI 規格檔案可從下列位置下載：
```
https://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/ParallelCluster.openapi.yaml
```
從 OpenAPI 規格檔案開始，您可以使用 [ Swagger UI ](https://swagger.io/tools/swagger-ui/)或 [Redoc](https://github.com/Redocly/redoc) 等許多可用工具之一來產生 AWS ParallelCluster API 的文件。
**如何部署 AWS ParallelCluster API**
若要部署 AWS ParallelCluster 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 layer 界面搭配 [AWS ParallelCluster Python 程式庫 API](pc-py-library-v3.md)來處理 API 調用的功能。
**警告**
中 AWS 帳戶具有 AWS Lambda 或 Amazon API Gateway 服務權限的任何使用者，會自動繼承管理 AWS ParallelCluster API 資源的許可。
# 使用 部署 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 Lambda 函數的 AWS ParallelCluster 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` 此網域名稱的 受管憑證 ARN AWS ，以及 `CustomDomainHostedZoneId` 您要建立記錄的 [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) 託管區域 ID。
**警告**
您可以設定自訂網域設定，以強制執行 API 的最低版本 Transport Layer Security (TLS)。如需詳細資訊，請參閱[在 API Gateway 中選擇自訂網域的最低 TLS 版本](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-custom-domain-tls-version.html)。
+ **EnableIamAdminAccess** - 根據預設， AWS Lambda 處理 AWS ParallelCluster API 操作的函數會設定 IAM 角色，以防止任何特殊權限的 IAM 存取 (`EnableIamAdminAccess=false`)。這使得 API 無法處理需要建立 IAM 角色或政策的操作。因此，只有在資源組態中提供 IAM 角色做為輸入時，才能成功建立叢集或自訂映像。
當 `EnableIamAdminAccess` 設定為 `true` API 時， AWS ParallelCluster 會授予許可，以管理部署叢集或產生自訂 AMIs 所需的 IAM 角色建立。
**警告**
將此設為 true 時，它會將 IAM 管理員權限授予處理 AWS ParallelCluster 操作的 AWS Lambda 函數。
如需啟用此模式時可解除鎖定功能[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` API 存取權，然後授予選取的 IAM 使用者。如需詳細資訊，請參閱《*Amazon API Gateway * [ 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 Gateway 開發人員指南》中的使用 API Gateway 資源政策控制對 API 的存取](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)。 **
**警告**
具有叫用所有 AWS ParallelCluster API `ParallelClusterApiUserRole` 操作的許可。若要限制對 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}
```
# 叫用 AWS ParallelCluster API
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
```
符合 OpenAPI 規格的任何 HTTP 用戶端都可以叫用 AWS ParallelCluster API，可在這裡找到：
```
https://-aws-parallelcluster.s3..amazonaws.com/parallelcluster//api/ParallelCluster.openapi.yaml
```
請求需要 SigV4 簽署，如[此處](https://docs.aws.amazon.com/apigateway/api-reference/signing-requests)所述。
目前，我們不提供任何官方 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)教學課程。
若要實作更進階的存取控制機制，例如 Amazon Cognito 或 Lambda 授權方，或使用 AWS WAF 或 API 金鑰進一步保護 API，請遵循 [Amazon API Gateway 文件](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 檔案系統、Amazon FSx 檔案系統、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 日誌會發佈至 Amazon 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 指標、日誌和[AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)追蹤日誌也可以透過 Lambda 主控台存取。若要擷取與 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
```