Creating a custom AMI with Terraform
When using Amazon ParallelCluster, you only pay for the Amazon resources that are created when you create or update Amazon ParallelCluster images and clusters. For more information, see Amazon services used by Amazon ParallelCluster.
Prerequisites
-
Terraform v1.5.7+ is installed.
-
Amazon ParallelCluster API v3.8.0+ is deployed in your account. See Creating a cluster with Terraform.
-
IAM role with the permissions to invoke the ParallelCluster API. See Required permissions.
Define a Terraform project
In this tutorial, you will define a simple Terraform project to deploy a ParallelCluster custom AMI.
Create a directory called
my-amis
.All files that you create will be within this directory.
Create the file
terraform.tf
to import the ParallelCluster provider.terraform { required_version = ">= 1.5.7" required_providers { aws-parallelcluster = { source = "aws-tf/aws-parallelcluster" version = "1.0.0" } } }
Create the file
providers.tf
to configure the ParallelCluster and Amazon providers.provider "aws" { region = var.region profile = var.profile } provider "aws-parallelcluster" { region = var.region profile = var.profile api_stack_name = var.api_stack_name use_user_role = true }
Create the file
main.tf
to define the resources using the ParallelCluster module.To review the image properties that you can set within the
image_configuration
element, see Build image configuration files.To review the options that you can set for image creation, for example
image_id
androllback_on_failure
, see pcluster build-image.data "aws-parallelcluster_list_official_images" "parent_image" { region = var.region os = var.os architecture = var.architecture } resource "aws-parallelcluster_image" "demo01" { image_id = "demo01" image_configuration = yamlencode({ "Build":{ "InstanceType": "c5.2xlarge", "ParentImage": data.aws-parallelcluster_list_official_images.parent_image.official_images[0].amiId, "UpdateOsPackages": {"Enabled": false} } }) rollback_on_failure = false }
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." } variable "os" { type = string description = "The OS of the ParallelCluster image." } variable "architecture" { type = string description = "The architecture of the ParallelCluster image." }
Create the file
terraform.tfvars
to set you arbitrary values for the variables.With the file below deploys the custom AMI in
us-east-1
based on Amazon Linux 2 for x86_64 architecture, using the existing ParallelCluster API 3.10.0 which is already deployed inus-east-1
with stack nameMyParallelClusterAPI-310
.region = "us-east-1" api_stack_name = "MyParallelClusterAPI-310" api_version = "3.10.0" os = "alinux2" architecture = "x86_64"
Create the file
outputs.tf
to define the outputs returned by this project.output "parent_image" { value = data.aws-parallelcluster_list_official_images.parent_image.official_images[0] } output "custom_image" { value = aws-parallelcluster_image.demo01 }
The project directory is:
my-amis ├── main.tf - Terraform entrypoint where the ParallelCluster module is configured. ├── outputs.tf - Defines the cluster as a Terraform output. ├── providers.tf - Configures the providers: ParallelCluster and AWS. ├── terraform.tf - Import the ParallelCluster provider. ├── terraform.tfvars - Defines values for variables, e.g. region, PCAPI stack name. └── variables.tf - Defines the variables, e.g. region, PCAPI stack name.
Deploy the AMI
To deploy the AMI, run the standard Terraform commands in order.
Build the project:
terraform init
Define the deployment plan:
terraform plan -out tfplan
Deploy the plan:
terraform apply tfplan
Required permissions
You need the following permissions to deploy a custom AMI with Terraform:
-
assume the ParallelCluster API role, which is in charge of interacting with the ParallelCluster API
-
describe the Amazon CloudFormation stack of the ParallelCluster API, to verify it exists and retrieve its parameters and outputs
{ "Version": "2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Resource": "arn:
PARTITION
:iam::ACCOUNT
:role/PCAPIUserRole-*", "Effect": "Allow", "Sid": "AssumePCAPIUserRole" }, { "Action": [ "cloudformation:DescribeStacks" ], "Resource": "arn:PARTITION
:cloudformation:REGION
:ACCOUNT
:stack/*", "Effect": "Allow", "Sid": "CloudFormation" } ] }