As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usando a AWS ParallelCluster API
Neste tutorial, você cria e testa a API com o [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) e um AWS ParallelCluster CloudFormation modelo. Em seguida, você usa o cliente de exemplo disponível GitHub para usar a API. Para obter mais informações sobre como usar a API, consulte a [AWS ParallelCluster API](api-reference-v3.md).
Para obter mais informações, consulte [Criar um componente personalizado com o Image Builder](https://docs.aws.amazon.com/imagebuilder/latest/userguide/create-component.html) no *Guia do usuário do EC2 Image Builder*.
Ao usar a interface de linha de AWS ParallelCluster comando (CLI) ou a API, você paga apenas pelos AWS recursos criados ao criar ou atualizar AWS ParallelCluster imagens e clusters. Para obter mais informações, consulte [AWS serviços usados por AWS ParallelCluster](aws-services-v3.md).
**Pré-requisitos**
+ O AWS CLI é [instalado](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e configurado em seu ambiente computacional.
+ AWS ParallelCluster é instalado em um ambiente virtual. Para obter mais informações, consulte [Instalar AWS ParallelCluster em um ambiente virtual (recomendado)](install-v3-virtual-environment.md).
+ Você tem um [par de EC2 chaves da Amazon](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html).
+ Você tem um perfil do IAM com as [permissões](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-example-user-policies) necessárias para executar a [`pcluster`](pcluster-v3.md) CLI.
## Etapa 1: criar a API com o Amazon API Gateway
**Fique no seu diretório de usuários domésticos e ative seu ambiente virtual:**
1. Instale um processador de linha de comando JSON útil.
```
$ sudo yum groupinstall -y "Development Tools"
sudo yum install -y jq python3-devel
```
1. Execute o comando a seguir para obter sua AWS ParallelCluster versão e atribuí-la a uma variável de ambiente.
```
$ PCLUSTER_VERSION=$(pcluster version | jq -r '.version')
echo "export PCLUSTER_VERSION=${PCLUSTER_VERSION}" |tee -a ~/.bashrc
```
1. Crie uma variável de ambiente e atribua seu ID de região a ela.
```
$ export AWS_DEFAULT_REGION="us-east-1"
echo "export AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION}" |tee -a ~/.bashrc
```
1. Execute o comando a seguir para implantar a 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"
}
```
Depois que o processo estiver concluído, avance para a próxima etapa.
## Etapa 2: testar a API no console do Amazon API Gateway
1. Faça login no Console de gerenciamento da AWS.
1. Vá até o [console do Amazon API Gateway](https://console.aws.amazon.com/apigateway/home).
1. Escolha sua implantação de API.
![\[Console do Amazon API Gateway com uma lista dos seus gateways que você pode escolher.\]](http://docs.aws.amazon.com/pt_br/parallelcluster/latest/ug/images/gateway_choose.png)
1. Escolha **Stages** e selecione um estágio.
![\[Uma visão de console dos estágios que você pode escolher. Você também pode ver o URL que o Gateway de API fornece para sua API.\]](http://docs.aws.amazon.com/pt_br/parallelcluster/latest/ug/images/gateway_address.png)
1. Observe a URL que o Gateway de API fornece para acessar ou invocar sua API. Está destacado em azul.
1. Escolha **Recursos** e selecione **`GET`** em**`/clusters`**.
1. Escolha o ícone de **TESTE** e, em seguida, role para baixo e escolha o ícone de **TESTE**.
![\[Uma visão de console dos recursos da API e dos mecanismos de teste.\]](http://docs.aws.amazon.com/pt_br/parallelcluster/latest/ug/images/gateway_test.png)
A resposta à sua `/clusters GET` aparece.
![\[Uma visão de console dos recursos da API, dos mecanismos de teste e da resposta da sua solicitação de teste.\]](http://docs.aws.amazon.com/pt_br/parallelcluster/latest/ug/images/gateway.png)
## Etapa 3: preparar e testar um cliente de exemplo para invocar a API
Clone o AWS ParallelCluster código-fonte `cd` até o `api` diretório e instale as bibliotecas de cliente do 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. Navegue de volta ao seu diretório de usuário inicial.
1. Exporte a URL base do Gateway de API que o cliente usa durante a execução.
```
$ 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. Exporte um nome de cluster que o cliente usa para criar um cluster.
```
$ export CLUSTER_NAME="test-api-cluster"
echo "export CLUSTER_NAME=${CLUSTER_NAME}" |tee -a ~/.bashrc
```
1. Execute os comandos a seguir para armazenar as credenciais que o cliente de exemplo usa para acessar a 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
```
## Etapa 4: copiar o script do código do cliente e executar testes de cluster
1. Copie o seguinte exemplo de código de cliente para o `test_pcluster_client.py` no seu diretório de usuário inicial. O código do cliente faz solicitações para fazer o seguinte:
+ Crie o cluster.
+ Descrever o cluster.
+ Listar os clusters.
+ Descrever a frota de computação.
+ Descrever as instâncias do cluster.
```
# 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. Criar uma configuração do cluster.
```
$ pcluster configure --config cluster-config.yaml
```
1. A biblioteca de cliente da API detecta automaticamente os detalhes da configuração de suas variáveis de ambiente (por exemplo `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, ou `AWS_SESSION_TOKEN`) ou `$HOME/.aws`. O comando a seguir muda seu perfil atual do IAM para o ParallelClusterApiUserRole designado.
```
$ 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"')
```
**Erro a ser observado:**
Se você vir um erro semelhante ao seguinte, você já presumiu que o ParallelClusterApiUserRole e o seu `AWS_SESSION_TOKEN` expiraram.
```
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
```
Elimine a função e execute novamente o comando `aws sts assume-role` para usar o ParallelClusterApiUserRole.
```
$ unset AWS_SESSION_TOKEN
unset AWS_SECRET_ACCESS_KEY
unset AWS_ACCESS_KEY_ID
```
Para fornecer suas permissões de usuário atuais para acesso à API, você deve [expandir a Política de Recursos](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html).
1. Execute o seguinte comando para testar o cliente de exemplo.
```
$ 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!
```
## Etapa 5: copiar o script do código do cliente e excluir cluster
1. Copie o seguinte código de cliente de exemplo para `delete_cluster_client.py`. O código do cliente faz uma solicitação para excluir o cluster.
```
# 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. Execute o comando a seguir para excluir o cluster.
```
$ 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. Depois de terminar o teste, desfaça a definição das variáveis de ambiente.
```
$ unset AWS_SESSION_TOKEN
unset AWS_SECRET_ACCESS_KEY
unset AWS_ACCESS_KEY_ID
```
## Etapa 6: limpar
Você pode usar o Console de gerenciamento da AWS ou AWS CLI para excluir sua API.
1. No CloudFormation console, escolha a pilha de API e, em seguida, escolha **Excluir**.
1. Se estiver usando o AWS CLI, execute o comando a seguir.
Usando CloudFormation.
```
$ aws cloudformation delete-stack --stack-name ${API_STACK_NAME}
```