本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS ParallelCluster API
在本教學課程中，您會使用 [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 和 anCloudFormation 範本建置和測試 API。 AWS ParallelCluster CloudFormation 然後，您可以使用 GitHub 上可用的範例用戶端來使用 API。如需如何使用 API 的詳細資訊，請參閱 [AWS ParallelCluster API](api-reference-v3.md)。
如需詳細資訊，請參閱 *EC2 * [ Image Builder 使用者指南中的使用映像建置器建立自訂元件](https://docs.aws.amazon.com/imagebuilder/latest/userguide/create-component.html)。
使用 AWS ParallelCluster 命令列界面 (CLI) 或 API 時，您只需為建立或更新 AWS ParallelCluster 映像和叢集時建立 AWS 的資源付費。如需詳細資訊，請參閱[AWS 使用的 服務 AWS ParallelCluster](aws-services-v3.md)。
**先決條件**
+ AWS CLI 會在您的運算環境中[安裝](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)和設定 。
+ AWS ParallelCluster 安裝在虛擬環境中。如需詳細資訊，請參閱[AWS ParallelCluster 在虛擬環境中安裝 （建議）](install-v3-virtual-environment.md)。
+ 您有 [Amazon EC2 金鑰對](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)。
+ 您有一個 IAM 角色，具有執行 CLI [`pcluster`](pcluster-v3.md) 所需的[許可](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-example-user-policies)。
## 步驟 1：使用 Amazon API Gateway 建置 API
**保留在您的主要使用者目錄中並啟用您的虛擬環境：**
1. 安裝實用的 JSON 命令列處理器。
```
$ sudo yum groupinstall -y "Development Tools"
sudo yum install -y jq python3-devel
```
1. 執行下列命令以取得您的 AWS ParallelCluster 版本，並將其指派給 環境變數。
```
$ PCLUSTER_VERSION=$(pcluster version | jq -r '.version')
echo "export PCLUSTER_VERSION=${PCLUSTER_VERSION}" |tee -a ~/.bashrc
```
1. 建立環境變數，並將您的區域 ID 指派給該變數。
```
$ export AWS_DEFAULT_REGION="us-east-1"
echo "export AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION}" |tee -a ~/.bashrc
```
1. 執行下列命令來部署 API。
```
API_STACK_NAME="pc-api-stack"
echo "export API_STACK_NAME=${API_STACK_NAME}" |tee -a ~/.bashrc
```
```
aws cloudformation create-stack \
--region ${AWS_DEFAULT_REGION} \
--stack-name ${API_STACK_NAME} \
--template-url https://${AWS_DEFAULT_REGION}-aws-parallelcluster.s3.${AWS_DEFAULT_REGION}.amazonaws.com/parallelcluster/${PCLUSTER_VERSION}/api/parallelcluster-api.yaml \
--capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
--parameters ParameterKey=EnableIamAdminAccess,ParameterValue=true
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/my-api-stack/abcd1234-ef56-gh78-ei90-1234abcd5678"
}
```
程序完成後，請繼續下一個步驟。
## 步驟 2：在 Amazon API Gateway 主控台中測試 API
1. 登入 AWS 管理主控台。
1. 導覽至 [Amazon API Gateway 主控台](https://console.aws.amazon.com/apigateway/home)。
1. 選擇您的 API 部署。
![\[Amazon API Gateway 主控台，其中包含您可以選擇的閘道清單。\]](http://docs.aws.amazon.com/zh_tw/parallelcluster/latest/ug/images/gateway_choose.png)
1. 選擇**階段**並選取階段。
![\[您可以從中選擇的階段的主控台檢視。您也可以檢視 API Gateway 為您的 API 提供的 URL。\]](http://docs.aws.amazon.com/zh_tw/parallelcluster/latest/ug/images/gateway_address.png)
1. 請注意 API Gateway 提供用來存取或叫用 API 的 URL。它以藍色反白顯示。
1. 選擇**資源**，然後選取 **`GET`**下的 **`/clusters`**。
1. 選擇**測試**圖示，然後向下捲動並選擇**測試**圖示。
![\[API 資源和測試機制的主控台檢視。\]](http://docs.aws.amazon.com/zh_tw/parallelcluster/latest/ug/images/gateway_test.png)
您的 回應`/clusters GET`隨即出現。
![\[API 資源、測試機制和測試請求回應的主控台檢視。\]](http://docs.aws.amazon.com/zh_tw/parallelcluster/latest/ug/images/gateway.png)
## 步驟 3：準備並測試範例用戶端以叫用 API
將 AWS ParallelCluster 原始程式碼複製到 `cd` `api`目錄，然後安裝 Python 用戶端程式庫。
1.
```
$ git clone -b v${PCLUSTER_VERSION} https://github.com/aws/aws-parallelcluster aws-parallelcluster-v${PCLUSTER_VERSION}
cd aws-parallelcluster-v${PCLUSTER_VERSION}/api
```
```
$ pip3 install client/src
```
1. 導覽回您的主要使用者目錄。
1. 匯出用戶端在執行時所使用的 API Gateway 基本 URL。
```
$ export PCLUSTER_API_URL=$( aws cloudformation describe-stacks --stack-name ${API_STACK_NAME} --query 'Stacks[0].Outputs[?OutputKey==`ParallelClusterApiInvokeUrl`].OutputValue' --output text )
echo "export PCLUSTER_API_URL=${PCLUSTER_API_URL}" |tee -a ~/.bashrc
```
1. 匯出用戶端用來建立叢集的叢集名稱。
```
$ export CLUSTER_NAME="test-api-cluster"
echo "export CLUSTER_NAME=${CLUSTER_NAME}" |tee -a ~/.bashrc
```
1. 執行下列命令來存放範例用戶端用來存取 API 的登入資料。
```
$ export PCLUSTER_API_USER_ROLE=$( aws cloudformation describe-stacks --stack-name ${API_STACK_NAME} --query 'Stacks[0].Outputs[?OutputKey==`ParallelClusterApiUserRole`].OutputValue' --output text )
echo "export PCLUSTER_API_USER_ROLE=${PCLUSTER_API_USER_ROLE}" |tee -a ~/.bashrc
```
## 步驟 4：複製用戶端程式碼指令碼並執行叢集測試
1. 將下列範例用戶端程式碼複製到主使用者目錄中`test_pcluster_client.py`的 。用戶端程式碼會發出執行下列動作的請求：
+ 建立 叢集
+ 描述叢集。
+ 列出叢集。
+ 描述運算機群。
+ 描述叢集執行個體。
```
# Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Author: Evan F. Bollig (Github: bollig)
import time, datetime
import os
import pcluster_client
from pprint import pprint
from pcluster_client.api import (
cluster_compute_fleet_api,
cluster_instances_api,
cluster_operations_api
)
from pcluster_client.model.create_cluster_request_content import CreateClusterRequestContent
from pcluster_client.model.cluster_status import ClusterStatus
region=os.environ.get("AWS_DEFAULT_REGION")
# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = pcluster_client.Configuration(
host = os.environ.get("PCLUSTER_API_URL")
)
cluster_name=os.environ.get("CLUSTER_NAME")
# Enter a context with an instance of the API client
with pcluster_client.ApiClient(configuration) as api_client:
cluster_ops = cluster_operations_api.ClusterOperationsApi(api_client)
fleet_ops = cluster_compute_fleet_api.ClusterComputeFleetApi(api_client)
instance_ops = cluster_instances_api.ClusterInstancesApi(api_client)
# Create cluster
build_done = False
try:
with open('cluster-config.yaml', encoding="utf-8") as f:
body = CreateClusterRequestContent(cluster_name=cluster_name, cluster_configuration=f.read())
api_response = cluster_ops.create_cluster(body, region=region)
except pcluster_client.ApiException as e:
print("Exception when calling create_cluster: %s\n" % e)
build_done = True
time.sleep(60)
# Confirm cluster status with describe_cluster
while not build_done:
try:
api_response = cluster_ops.describe_cluster(cluster_name, region=region)
pprint(api_response)
if api_response.cluster_status == ClusterStatus('CREATE_IN_PROGRESS'):
print('. . . working . . .', end='', flush=True)
time.sleep(60)
elif api_response.cluster_status == ClusterStatus('CREATE_COMPLETE'):
print('READY!')
build_done = True
else:
print('ERROR!!!!')
build_done = True
except pcluster_client.ApiException as e:
print("Exception when calling describe_cluster: %s\n" % e)
# List clusters
try:
api_response = cluster_ops.list_clusters(region=region)
pprint(api_response)
except pcluster_client.ApiException as e:
print("Exception when calling list_clusters: %s\n" % e)
# DescribeComputeFleet
try:
api_response = fleet_ops.describe_compute_fleet(cluster_name, region=region)
pprint(api_response)
except pcluster_client.ApiException as e:
print("Exception when calling compute fleet: %s\n" % e)
# DescribeClusterInstances
try:
api_response = instance_ops.describe_cluster_instances(cluster_name, region=region)
pprint(api_response)
except pcluster_client.ApiException as e:
print("Exception when calling describe_cluster_instances: %s\n" % e)
```
1. 建立叢集組態。
```
$ pcluster configure --config cluster-config.yaml
```
1. API 用戶端程式庫會自動偵測來自您環境變數 （例如 `AWS_ACCESS_KEY_ID`、 `AWS_SECRET_ACCESS_KEY`或 `AWS_SESSION_TOKEN`) 或 的組態詳細資訊`$HOME/.aws`。下列命令會將您目前的 IAM 角色切換為指定的 ParallelClusterApiUserRole。
```
$ eval $(aws sts assume-role --role-arn ${PCLUSTER_API_USER_ROLE} --role-session-name ApiTestSession | jq -r '.Credentials | "export AWS_ACCESS_KEY_ID=\(.AccessKeyId)\nexport AWS_SECRET_ACCESS_KEY=\(.SecretAccessKey)\nexport AWS_SESSION_TOKEN=\(.SessionToken)\n"')
```
**要監看的錯誤：**
如果您看到類似以下的錯誤，表示您已假設 ParallelClusterApiUserRole且您的 `AWS_SESSION_TOKEN` 已過期。
```
An error occurred (AccessDenied) when calling the AssumeRole operation:
User: arn:aws:sts::XXXXXXXXXXXX:assumed-role/ParallelClusterApiUserRole-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/ApiTestSession
is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::XXXXXXXXXXXX:role/ParallelClusterApiUserRole-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
```
捨棄角色，然後重新執行 `aws sts assume-role`命令以使用 ParallelClusterApiUserRole。
```
$ unset AWS_SESSION_TOKEN
unset AWS_SECRET_ACCESS_KEY
unset AWS_ACCESS_KEY_ID
```
若要為 API 存取提供目前的使用者許可，您必須[展開資源政策](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)。
1. 執行下列命令來測試範例用戶端。
```
$ python3 test_pcluster_client.py
{'cluster_configuration': 'Region: us-east-1\n'
'Image:\n'
' Os: alinux2\n'
'HeadNode:\n'
' InstanceType: t2.micro\n'
' Networking . . . :\n'
' SubnetId: subnet-1234567890abcdef0\n'
' Ssh:\n'
' KeyName: adpc\n'
'Scheduling:\n'
' Scheduler: slurm\n'
' SlurmQueues:\n'
' - Name: queue1\n'
' ComputeResources:\n'
' - Name: t2micro\n'
' InstanceType: t2.micro\n'
' MinCount: 0\n'
' MaxCount: 10\n'
' Networking . . . :\n'
' SubnetIds:\n'
' - subnet-1234567890abcdef0\n',
'cluster_name': 'test-api-cluster'}
{'cloud_formation_stack_status': 'CREATE_IN_PROGRESS',
'cloudformation_stack_arn': 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-api-cluster/abcd1234-ef56-gh78-ij90-1234abcd5678',
'cluster_configuration': {'url': 'https://parallelcluster-021345abcdef6789-v1-do-not-delete...},
'cluster_name': 'test-api-cluster',
'cluster_status': 'CREATE_IN_PROGRESS',
'compute_fleet_status': 'UNKNOWN',
'creation_time': datetime.datetime(2022, 4, 28, 16, 18, 47, 972000, tzinfo=tzlocal()),
'last_updated_time': datetime.datetime(2022, 4, 28, 16, 18, 47, 972000, tzinfo=tzlocal()),
'region': 'us-east-1',
'tags': [{'key': 'parallelcluster:version', 'value': '3.1.3'}],
'version': '3.1.3'}
.
.
.
. . . working . . . {'cloud_formation_stack_status': 'CREATE_COMPLETE',
'cloudformation_stack_arn': 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-api-cluster/abcd1234-ef56-gh78-ij90-1234abcd5678',
'cluster_configuration': {'url': 'https://parallelcluster-021345abcdef6789-v1-do-not-delete...},
'cluster_name': 'test-api-cluster',
'cluster_status': 'CREATE_COMPLETE',
'compute_fleet_status': 'RUNNING',
'creation_time': datetime.datetime(2022, 4, 28, 16, 18, 47, 972000, tzinfo=tzlocal()),
'head_node': {'instance_id': 'i-abcdef01234567890',
'instance_type': 't2.micro',
'launch_time': datetime.datetime(2022, 4, 28, 16, 21, 46, tzinfo=tzlocal()),
'private_ip_address': '172.31.27.153',
'public_ip_address': '52.90.156.51',
'state': 'running'},
'last_updated_time': datetime.datetime(2022, 4, 28, 16, 18, 47, 972000, tzinfo=tzlocal()),
'region': 'us-east-1',
'tags': [{'key': 'parallelcluster:version', 'value': '3.1.3'}],
'version': '3.1.3'}
READY!
```
## 步驟 5：複製用戶端程式碼指令碼並刪除叢集
1. 將下列範例用戶端程式碼複製到 `delete_cluster_client.py`。用戶端程式碼會發出刪除叢集的請求。
```
# Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Author: Evan F. Bollig (Github: bollig)
import time, datetime
import os
import pcluster_client
from pprint import pprint
from pcluster_client.api import (
cluster_compute_fleet_api,
cluster_instances_api,
cluster_operations_api
)
from pcluster_client.model.create_cluster_request_content import CreateClusterRequestContent
from pcluster_client.model.cluster_status import ClusterStatus
region=os.environ.get("AWS_DEFAULT_REGION")
# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = pcluster_client.Configuration(
host = os.environ.get("PCLUSTER_API_URL")
)
cluster_name=os.environ.get("CLUSTER_NAME")
# Enter a context with an instance of the API client
with pcluster_client.ApiClient(configuration) as api_client:
cluster_ops = cluster_operations_api.ClusterOperationsApi(api_client)
# Delete the cluster
gone = False
try:
api_response = cluster_ops.delete_cluster(cluster_name, region=region)
except pcluster_client.ApiException as e:
print("Exception when calling delete_cluster: %s\n" % e)
time.sleep(60)
# Confirm cluster status with describe_cluster
while not gone:
try:
api_response = cluster_ops.describe_cluster(cluster_name, region=region)
pprint(api_response)
if api_response.cluster_status == ClusterStatus('DELETE_IN_PROGRESS'):
print('. . . working . . .', end='', flush=True)
time.sleep(60)
except pcluster_client.ApiException as e:
gone = True
print("DELETE COMPLETE or Exception when calling describe_cluster: %s\n" % e)
```
1. 執行下列命令來刪除叢集。
```
$ python3 delete_cluster_client.py
{'cloud_formation_stack_status': 'DELETE_IN_PROGRESS',
'cloudformation_stack_arn': 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-api-cluster/abcd1234-ef56-gh78-ij90-1234abcd5678',
'cluster_configuration': {'url': 'https://parallelcluster-021345abcdef6789-v1-do-not-delete...},
'cluster_name': 'test-api-cluster',
'cluster_status': 'DELETE_IN_PROGRESS',
'compute_fleet_status': 'UNKNOWN',
'creation_time': datetime.datetime(2022, 4, 28, 16, 50, 47, 943000, tzinfo=tzlocal()),
'head_node': {'instance_id': 'i-abcdef01234567890',
'instance_type': 't2.micro',
'launch_time': datetime.datetime(2022, 4, 28, 16, 53, 48, tzinfo=tzlocal()),
'private_ip_address': '172.31.17.132',
'public_ip_address': '34.201.100.37',
'state': 'running'},
'last_updated_time': datetime.datetime(2022, 4, 28, 16, 50, 47, 943000, tzinfo=tzlocal()),
'region': 'us-east-1',
'tags': [{'key': 'parallelcluster:version', 'value': '3.1.3'}],
'version': '3.1.3'}
.
.
.
. . . working . . . {'cloud_formation_stack_status': 'DELETE_IN_PROGRESS',
'cloudformation_stack_arn': 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-api-cluster/abcd1234-ef56-gh78-ij90-1234abcd5678',
'cluster_configuration': {'url': 'https://parallelcluster-021345abcdef6789-v1-do-not-delete...},
'cluster_name': 'test-api-cluster',
'cluster_status': 'DELETE_IN_PROGRESS',
'compute_fleet_status': 'UNKNOWN',
'creation_time': datetime.datetime(2022, 4, 28, 16, 50, 47, 943000, tzinfo=tzlocal()),
'last_updated_time': datetime.datetime(2022, 4, 28, 16, 50, 47, 943000, tzinfo=tzlocal()),
'region': 'us-east-1',
'tags': [{'key': 'parallelcluster:version', 'value': '3.1.3'}],
'version': '3.1.3'}
. . . working . . . DELETE COMPLETE or Exception when calling describe_cluster: (404)
Reason: Not Found
.
.
.
HTTP response body: {"message":"Cluster 'test-api-cluster' does not exist or belongs to an incompatible ParallelCluster major version."}
```
1. 測試完成後，請取消設定環境變數。
```
$ unset AWS_SESSION_TOKEN
unset AWS_SECRET_ACCESS_KEY
unset AWS_ACCESS_KEY_ID
```
## 步驟 6：清除
您可以使用 AWS 管理主控台 或 AWS CLI 來刪除您的 API。
1. 從 CloudFormation 主控台選擇 API 堆疊，然後選擇**刪除**。
1. 如果使用 ，請執行下列命令 AWS CLI。
使用 CloudFormation。
```
$ aws cloudformation delete-stack --stack-name ${API_STACK_NAME}
```