AWS Documentation » AWS ParallelCluster » AWS ParallelCluster User Guide » Tutorials » Building a Custom AWS ParallelCluster AMI

Building a Custom AWS ParallelCluster AMI

Important

Building a custom AMI is not the recommended approach for customizing AWS ParallelCluster.

After you build your own AMI, you no longer receive updates or bug fixes with future releases of AWS ParallelCluster. Also, you must repeat the steps used to create your custom AMI with each new AWS ParallelCluster release.

Before reading any further, take a look at the Custom Bootstrap Actions section to determine if the modifications you want to make can be scripted and supported with future AWS ParallelCluster releases.

While building a custom AMI is not ideal, there are scenarios in which building a custom AMI for AWS ParallelCluster is necessary. This tutorial guides you through the process.

How to Customize the AWS ParallelCluster AMI

There are three ways to use a custom AWS ParallelCluster AMI. Two methods require you to build a new AMI that is available under your AWS account. The third method—Use a Custom AMI at Runtime—does not require you to build anything in advance. Select the appropriate method based on your needs.

Modify an AWS ParallelCluster AMI

This is the safest method, because the base AWS ParallelCluster AMI is often updated with new releases. This AMI has all of the components required for AWS ParallelCluster to function as installed and configured. You can start with this as the base.

1. In the AMI list, find the AMI that corresponds to the Region you are using. The AMI list to use must match the version of AWS ParallelCluster you are using. Run pcluster version to verify the version. For example:

   • For AWS ParallelCluster 2.5.0 -> https://github.com/aws/aws-parallelcluster/blob/v2.5.0/amis.txt

   • For AWS ParallelCluster 2.4.1 -> https://github.com/aws/aws-parallelcluster/blob/v2.4.1/amis.txt

   • For AWS ParallelCluster 2.4.0 -> https://github.com/aws/aws-parallelcluster/blob/v2.4.0/amis.txt

   • For AWS ParallelCluster 2.3.1 -> https://github.com/aws/aws-parallelcluster/blob/v2.3.1/amis.txt

   • For AWS ParallelCluster 2.2.1 -> https://github.com/aws/aws-parallelcluster/blob/v2.2.1/amis.txt

   • For AWS ParallelCluster 2.1.1 -> https://github.com/aws/aws-parallelcluster/blob/v2.1.1/amis.txt

   • For CfnCluster 1.6.1 -> https://github.com/aws/aws-parallelcluster/blob/v1.6.1/amis.txt

2. Within the Amazon EC2 console, choose Launch Instance.

3. Navigate to Community AMIs, and enter the AMI id for your Region into the search box.

4. Select the AMI, choose your instance type and properties, and launch your instance.

5. Log into your instance using the OS user and your SSH key.

6. Customize your instance as required.

7. Run the following command to prepare your instance for AMI creation:

   sudo /usr/local/sbin/ami_cleanup.sh

8. Stop the instance.

9. Create a new AMI from the instance.

10. Enter the AMI id in the custom_ami field within your cluster configuration.

Build a Custom AWS ParallelCluster AMI

If you have a customized AMI and software already in place, you can apply the changes needed by AWS ParallelCluster on top of it.

1. Install the following tools in your local system, together with the AWS ParallelCluster CLI:

   • Packer: find the latest version for your OS from the Packer website, and install it.

   • ChefDK: find the latest version for your OS from the ChefDK website, and install it.

2. Verify that the packer and berks commands are available in your PATH after you have installed the tools in Step 1.

3. Configure your AWS account credentials so that Packer can make calls to AWS API operations on your behalf. The minimal set of required permissions necessary for Packer to work are documented in the Packer doc.

4. Use the command createami in the AWS ParallelCluster CLI to build an AWS ParallelCluster AMI starting from the one that you provide as base:

   pcluster createami --ami-id <BASE AMI> --os <BASE OS AMI>

   Important

   You cannot use an AWS ParallelCluster AMI as <BASE AMI> for the createami command. If you do, the command fails.

   For other parameters, consult the command help:

   pcluster createami -h

5. The command in Step 4 executes Packer, which does the following:

   1. Launches an instance using the base AMI provided.

   2. Applies the AWS ParallelCluster cookbook to the instance, in order to install software and perform other necessary configuration tasks.

   3. Stops the instance.

   4. Creates an new AMI from the instance.

   5. Terminates the instance after the AMI is created.

   6. Outputs the new AMI ID string to use to create your cluster.

6. To create your cluster, enter the AMI ID in the custom_ami field within your cluster configuration.

Note

The instance type used to build a custom AWS ParallelCluster AMI is a t2.xlarge. It does not qualify for the AWS free tier. You are charged for any instances that are created when building this AMI.

Use a Custom AMI at Runtime

If you don't want to create anything in advance, you can use your AMI and create an AWS ParallelCluster from that.

Note that with this method, the AWS ParallelCluster creation time is longer, because all software that is needed by AWS ParallelCluster at cluster creation time must be installed. Also, scaling up for every new node takes more time.

• Enter the AMI id in the custom_ami field within your cluster configuration.