AWS ParallelCluster AMI customization - AWS ParallelCluster

AWS ParallelCluster AMI customization

There are scenarios where building a custom AMI for AWS ParallelCluster is necessary. This section covers what to consider when building a custom AWS ParallelCluster AMI.

You can build a custom AWS ParallelCluster AMI using one of the following methods:

  1. Create a build image configuration file, and then use the pcluster CLI to build the image with EC2 Image Builder. This process is automated, repeatable, and supports monitoring. For more information, see the pcluster image commands.

  2. Create an instance from an AWS ParallelCluster AMI, then log in to it and make manual modifications. Last, use Amazon EC2 to create a new AMI from the modified instance. This process takes less time. However, it isn't automated or repeatable, and it doesn't support use of the pcluster CLI image monitoring commands.

For more information about these methods, see Building a custom AWS ParallelCluster AMI.

AWS ParallelCluster AMI customization considerations

No matter how you create your custom image, we recommend that you perform preliminary validation tests and include provisions to monitor the status of the image being created.

To build a custom AMI using pcluster, you create a build image configuration file with a Build and Image section that EC2 Image Builder uses to build your custom image. The Build section specifies what Image Builder needs to build the image. This includes the ParentImage (base image), and Components. An Image Builder component defines a sequence of steps that are required to customize an instance before an image is created or to test an instance that was launched by the created image. For AWS ParallelCluster component examples, see Custom AMIs. The Image section specifies the image properties.

When called from pcluster build-image to create a custom image, Image Builder uses the build image configuration with the AWS ParallelCluster cookbook to bootstrap AWS ParallelCluster on your ParentImage. Image Builder downloads components, runs build and validate phases, creates the AMI, launches an instance from the AMI, and runs tests. When the process completes, Image Builder then produces a new image or a stop message.

Perform custom component validation tests

Before you include an Image Builder component in a configuration, test and validate it using one of the following methods. Because the Image Builder process can take up to 1 hour, we recommend that you test the components beforehand. This can save you a considerable amount of time.

Script case

Test the script in a running instance, outside the build image process, and verify that the script exits with exit code 0.

Amazon Resource Name (ARN) case

Test the component document in a running instance, outside the build image process. For a list of requirements, see Component manager in the Image Builder User Guide.

After successful validation, add the component to your build image configuration

After you verified that the custom component is working, add it to the Build image configuration file.

Monitor the Image Builder process with pcluster commands to aid in debugging


Use this command to monitor the build image status.


Use this command to get the IDs of log streams that you can use to retrieve log events with get-image-log-events.


Use this command to get the log stream of build image process events.

For example, you can tail build image events using the following command.

$ watch -n 1 'pcluster get-image-log-events -i <image-id> \ --log-stream-name/1 <pcluster-version> \ --query "events[*].message" | tail -n 50'


Use this command to retrieve image stack events for the stack that Image Builder creates.


Use this command save image logs.

For more information about AWS ParallelCluster logs and Amazon CloudWatch, see Amazon CloudWatch Logs build image logs and Amazon CloudWatch dashboard.

Other considerations

New AWS ParallelCluster releases and custom AMIs

If you build and use a custom AMI, you must repeat the steps that you used to create your custom AMI with each new AWS ParallelCluster release.

Custom bootstrap actions

Review the Custom bootstrap actions section to determine if the modifications you want to make can be scripted and supported with future AWS ParallelCluster releases.

Using custom AMIs

You can specify custom AMIs in the cluster configuration in the Image / CustomAmi and Scheduling / SlurmQueues / - Name / Image / CustomAmi sections.

To troubleshoot custom AMI validation warnings, see Troubleshooting custom AMI issues.