View a markdown version of this page

Invoking Amazon ParallelCluster API - Amazon ParallelCluster
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Invoking Amazon ParallelCluster API

The Amazon ParallelCluster Amazon API Gateway endpoint is configured with AWS_IAM authorization type, and requires all requests to be SigV4 signed with valid IAM credentials (API reference: making http requests).

When deployed with default settings, API invoke permissions are only granted to the default IAM user created with the API.

To retrieve the ARN of the default IAM user, run: 

$ 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

To obtain temporary credentials for the default IAM user, run the  STS AssumeRole command.

To retrieve the Amazon ParallelCluster API endpoint run the following command: 

$ 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

The Amazon ParallelCluster API can be invoked by any HTTP client that complies with the OpenAPI specifications that can be found here: 

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

Requests need to be SigV4 signed as documented here.

At this time, we do not offer any official API client implementation. However, you can use the OpenAPI Generator to easily generate API clients from the OpenAPI model. Once the client is generated, SigV4 signing needs to be added if not provided out of the box.

A reference implementation for a Python API client can be found in the Amazon ParallelCluster repository. To learn more about how you can use the Python API client, see the Using the Amazon ParallelCluster API tutorial.

To implement more advanced access control mechanisms, such as Amazon Cognito or Lambda Authorizers, or to further protect the API with Amazon WAF or API keys, follow the Amazon API Gateway documentation.

Warning

An IAM user that is authorized to invoke the Amazon ParallelCluster API, can indirectly control all Amazon resources managed by Amazon ParallelCluster in the Amazon Web Services account. This includes the creation of Amazon resources that the user can't control directly due to restrictions on the user IAM policy. For example, the creation of a Amazon ParallelCluster cluster, depending on its configuration, might include the deployment of Amazon EC2 instances, Amazon Route 53, Amazon Elastic File System file systems, Amazon FSx file systems, IAM roles, and resources from other Amazon Web Services services used by Amazon ParallelCluster that the user might not have direct control over.

Warning

When you create a cluster with AdditionalIamPolicies specified in the configuration, the additional policies must match one of the following patterns:

- !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

If you need other additional policies, you can do one of the following:

  • Edit the DefaultParallelClusterIamAdminPolicy in:

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

    Add the policy in the ArnLike/iam:PolicyARN section.

  • Don't specify policies for AdditionalIamPolicies in the configuration file and manually add policies to the Amazon ParallelCluster Instance Role created within the cluster.