Deploying ParallelCluster API with Terraform - Amazon ParallelCluster
Define a Terraform projectDeploy the APIRequired permissions
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).

Deploying ParallelCluster API with Terraform

In this tutorial, you will define a simple Terraform project to deploy a ParallelCluster API.

Prerequisites

  • Terraform v1.5.7+ is installed.

  • IAM role with the permissions to deploy the ParallelCluster API. See Required permissions.

Define a Terraform project

  1. Create a directory called my-pcluster-api.

    All files that you create will be within this directory.

  2. Create the file provider.tf to configure the Amazon provider.

    provider "aws" {
  region  = var.region
  profile = var.profile
}

  3. Create the file main.tf to define the resources using the ParallelCluster module.

    module "parallelcluster_pcluster_api" {
  source = "aws-tf/parallelcluster/aws//modules/pcluster_api"
  version = "1.0.0"

  region                = var.region
  api_stack_name        = var.api_stack_name
  api_version           = var.api_version
  deploy_pcluster_api   = true
  parameters = {
    EnableIamAdminAccess = "true"
  }
}

  4. Create the file variables.tf to define the variables that can be injected for this project.

    variable "region" {
  description = "The region the ParallelCluster API is deployed in."
  type        = string
  default     = "us-east-1"
}

variable "profile" {
  type        = string
  description = "The AWS profile used to deploy the clusters."
  default     = null
}

variable "api_stack_name" {
  type        = string
  description = "The name of the CloudFormation stack used to deploy the ParallelCluster API."
  default     = "ParallelCluster"
}

variable "api_version" {
  type        = string
  description = "The version of the ParallelCluster API."
}

  5. Create the file terraform.tfvars to set arbitrary values for the variables.

    The file below deploys a ParallelCluster API 3.10.0 in us-east-1 using the stack name MyParallelClusterAPI-310. You'll be able to reference this ParallelCluster API deployment using its stack name. 

    region = "us-east-1"
api_stack_name = "MyParallelClusterAPI-310"
api_version = "3.10.0"

  6. Create the file outputs.tf to define the outputs returned by this project.

    output "pcluster_api_stack_outputs" {
  value = module.parallelcluster_pcluster_api.stack_outputs
}

    The project directory is:

    my-pcluster-api
├── main.tf - Terraform entrypoint to define the resources using the ParallelCluster module.
├── outputs.tf - Defines the outputs returned by Terraform.
├── providers.tf - Configures the AWS provider.
├── terraform.tfvars - Set the arbitrary values for the variables, i.e. region, PCAPI version, PCAPI stack name
└── variables.tf - Defines the variables, e.g. region, PCAPI version, PCAPI stack name.

Deploy the API

To deploy the API, run the standard Terraform commands in order.

  1. Build the project:

    terraform init

  2. Define the deployment plan:

    terraform plan -out tfplan

  3. Deploy the plan:

    terraform apply tfplan

Required permissions

You need the following permissions to deploy the ParallelCluster API with Terraform:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "cloudformation:DescribeStacks",
                "cloudformation:GetTemplate"
            ],
            "Resource": "arn:PARTITION:cloudformation:REGION:ACCOUNT:stack/*",
            "Effect": "Allow",
            "Sid": "CloudFormationRead"
        },
        {
            "Action": [
                "cloudformation:CreateStack",
                "cloudformation:DeleteStack",
                "cloudformation:CreateChangeSet"
            ],
            "Resource": "arn:PARTITION:cloudformation:REGION:ACCOUNT:stack/MyParallelClusterAPI*",
            "Effect": "Allow",
            "Sid": "CloudFormationWrite"
        },
        {
            "Action": [
                "cloudformation:CreateChangeSet"
            ],
            "Resource": [
                "arn:PARTITION:cloudformation:REGION:aws:transform/Include",
                "arn:PARTITION:cloudformation:REGION:aws:transform/Serverless-2016-10-31"
            ],
            "Effect": "Allow",
            "Sid": "CloudFormationTransformWrite"
        },
        {
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:PARTITION:s3:::*-aws-parallelcluster/parallelcluster/*/api/ParallelCluster.openapi.yaml",
                "arn:PARTITION:s3:::*-aws-parallelcluster/parallelcluster/*/layers/aws-parallelcluster/lambda-layer.zip"
            ],
            "Effect": "Allow",
            "Sid": "S3ParallelClusterArtifacts"
        },
        {
            "Action": [
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:GetRole",
                "iam:CreatePolicy",
                "iam:DeletePolicy",
                "iam:GetPolicy",
                "iam:GetRolePolicy",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:ListPolicyVersions"
            ],
            "Resource": [
                "arn:PARTITION:iam::ACCOUNT:role/*",
                "arn:PARTITION:iam::ACCOUNT:policy/*"
            ],
            "Effect": "Allow",
            "Sid": "IAM"
        },
        {
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:PARTITION:iam::ACCOUNT:role/ParallelClusterLambdaRole-*",
                "arn:PARTITION:iam::ACCOUNT:role/APIGatewayExecutionRole-*"
            ],
            "Effect": "Allow",
            "Sid": "IAMPassRole"
        },
        {
            "Action": [
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:GetFunction",
                "lambda:PublishLayerVersion",
                "lambda:DeleteLayerVersion",
                "lambda:GetLayerVersion",
                "lambda:TagResource",
                "lambda:UntagResource"
            ],
            "Resource": [
                "arn:PARTITION:lambda:REGION:ACCOUNT:layer:PCLayer-*",
                "arn:PARTITION:lambda:REGION:ACCOUNT:function:*-ParallelClusterFunction-*"
            ],
            "Effect": "Allow",
            "Sid": "Lambda"
        },
        {
            "Action": [
                "logs:CreateLogGroup",
                "logs:DeleteLogGroup",
                "logs:DescribeLogGroups",
                "logs:PutRetentionPolicy",
                "logs:TagLogGroup",
                "logs:UntagLogGroup"
            ],
            "Resource": [
                "arn:PARTITION:logs:REGION:ACCOUNT:log-group:/aws/lambda/*-ParallelClusterFunction-*"
            ],
            "Effect": "Allow",
            "Sid": "Logs"
        },
        {
            "Action": [
                "apigateway:DELETE",
                "apigateway:GET",
                "apigateway:PATCH",
                "apigateway:POST",
                "apigateway:PUT",
                "apigateway:UpdateRestApiPolicy"
            ],
            "Resource": [
                "arn:PARTITION:apigateway:REGION::/restapis",
                "arn:PARTITION:apigateway:REGION::/restapis/*",
                "arn:PARTITION:apigateway:REGION::/tags/*"
            ],
            "Effect": "Allow",
            "Sid": "APIGateway"
        }
    ]
}