Amazon ParallelCluster AMI customization - Amazon ParallelCluster
Amazon ParallelCluster AMI customization considerationsPerform custom component validation testsMonitor the Image Builder process with pcluster commands to aid in debuggingOther considerations
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).

Amazon ParallelCluster AMI customization

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

You can build a custom Amazon 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 Amazon 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 Amazon ParallelCluster AMI.

Amazon 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 Amazon 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 Amazon ParallelCluster cookbook to bootstrap Amazon 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

describe-image

Use this command to monitor the build image status.

list-image-log-streams

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

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'

get-image-stack-events

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

export-image-logs

Use this command save image logs.

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

Other considerations

New Amazon 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 Amazon 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 Amazon 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.