Important

New Docs are available at https://docs.aws.amazon.com/parallelcluster

All new features, starting with 2.4.0, will be documented there.

AWS ParallelCluster CLI commands

pcluster is the AWS ParallelCluster CLI and permits launching and management of HPC clusters in the AWS cloud.

usage: pcluster [-h]
                {create,update,delete,start,stop,status,list,instances,ssh,createami,configure,version}
                ...

Positional Arguments

command Possible choices: create, update, delete, start, stop, status, list, instances, ssh, createami, configure, version

Sub-commands:

create

Creates a new cluster.

pcluster create [-h] [-c CONFIG_FILE] [-r REGION] [-nw] [-nr]
                [-u TEMPLATE_URL] [-t CLUSTER_TEMPLATE] [-p EXTRA_PARAMETERS]
                [-g TAGS]
                cluster_name

Positional Arguments

cluster_name Defines the name of the cluster. The CloudFormation stack name will be parallelcluster-[cluster_name]

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.
-nw, --nowait

Do not wait for stack events after executing stack command.

Default: False

-nr, --norollback
 

Disables stack rollback on error.

Default: False

-u, --template-url
 Specifies the URL for a custom CloudFormation template, if it was used at creation time.
-t, --cluster-template
 Indicates which section of the cluster template to use.
-p, --extra-parameters
 Adds extra parameters to the stack create.
-g, --tags Specifies additional tags to be added to the stack.

When the command is called and begins polling for status of that call , it is safe to use ‘Ctrl-C’ to exit. You can return to viewing the current status by calling “pcluster status mycluster”.

Examples:

$ pcluster create mycluster
$ pcluster create mycluster --tags '{ "Key1" : "Value1" , "Key2" : "Value2" }'

update

Updates a running cluster using the values in the config file.

pcluster update [-h] [-c CONFIG_FILE] [-r REGION] [-nw] [-nr]
                [-t CLUSTER_TEMPLATE] [-p EXTRA_PARAMETERS] [-rd]
                cluster_name

Positional Arguments

cluster_name Names the cluster to update.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.
-nw, --nowait

Do not wait for stack events after executing stack command.

Default: False

-nr, --norollback
 

Disable CloudFormation stack rollback on error.

Default: False

-t, --cluster-template
 Indicates which section of the cluster template to use.
-p, --extra-parameters
 Adds extra parameters to the stack update.
-rd, --reset-desired
 

Resets the current ASG desired capacity to the initial config values.

Default: False

When the command is called and it begins polling for the status of that call, it is safe to “Ctrl-C” out. You can always return to that status by calling “pcluster status mycluster”.

delete

Deletes a cluster.

pcluster delete [-h] [-c CONFIG_FILE] [-r REGION] [-nw] cluster_name

Positional Arguments

cluster_name Names the cluster to delete.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.
-nw, --nowait

Do not wait for stack events after executing stack command.

Default: False

When the command is called and it begins polling for the status of that call it is safe to “Ctrl-C” out. You can return to that status by calling “pcluster status mycluster”.

start

Starts the compute fleet for a cluster that has been stopped.

pcluster start [-h] [-c CONFIG_FILE] [-r REGION] cluster_name

Positional Arguments

cluster_name Starts the compute fleet of the cluster name provided here.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.

This command sets the Auto Scaling Group parameters to either the initial configuration values (max_queue_size and initial_queue_size) specified in the template that was used to create the cluster or to the configuration values that were used to update the cluster after it was created.

stop

Stops the compute fleet, leaving the master server running.

pcluster stop [-h] [-c CONFIG_FILE] [-r REGION] cluster_name

Positional Arguments

cluster_name Stops the compute fleet of the cluster name provided here.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.

This command sets the Auto Scaling Group parameters to min/max/desired = 0/0/0 and terminates the compute fleet. The master will remain running. To terminate all EC2 resources and avoid EC2 charges, consider deleting the cluster.

status

Pulls the current status of the cluster.

pcluster status [-h] [-c CONFIG_FILE] [-r REGION] [-nw] cluster_name

Positional Arguments

cluster_name Shows the status of the cluster with the name provided here.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.
-nw, --nowait

Do not wait for stack events after executing stack command.

Default: False

list

Displays a list of stacks associated with AWS ParallelCluster.

pcluster list [-h] [--color] [-c CONFIG_FILE] [-r REGION]

Named Arguments

--color

Display the cluster status in color.

Default: False

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.

This command lists the names of any CloudFormation stacks named parallelcluster-*

instances

Displays a list of all instances in a cluster.

pcluster instances [-h] [-c CONFIG_FILE] [-r REGION] cluster_name

Positional Arguments

cluster_name Display the instances for the cluster with the name provided here.

Named Arguments

-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.

ssh

Run ssh command with the cluster username and IP address pre-populated. Arbitrary arguments are appended to the end of the ssh command. This command can be customized in the aliases section of the config file.

pcluster ssh [-h] [-d] cluster_name

Positional Arguments

cluster_name Name of the cluster to connect to.

Named Arguments

-d, --dryrun

Prints command and exits.

Default: False

Example:

$ pcluster ssh mycluster -i ~/.ssh/id_rsa

Returns an ssh command with the cluster username and IP address pre-populated:

$ ssh ec2-user@1.1.1.1 -i ~/.ssh/id_rsa

The SSH command is defined in the global config file under the aliases section and it can be customized:

[aliases]
ssh = ssh {CFN_USER}@{MASTER_IP} {ARGS}

Variables substituted:

{CFN_USER}
{MASTER_IP}
{ARGS} (only if specified on the cli)

createami

(Linux/macOS) Creates a custom AMI to use with AWS ParallelCluster.

pcluster createami [-h] -ai BASE_AMI_ID -os BASE_AMI_OS [-i INSTANCE_TYPE]
                   [-ap CUSTOM_AMI_NAME_PREFIX] [-cc CUSTOM_AMI_COOKBOOK]
                   [-c CONFIG_FILE] [-r REGION]

Named Arguments

-ai, --ami-id Specifies the base AMI to use for building the AWS ParallelCluster AMI.
-os, --os Specifies the OS of the base AMI. Valid options are: alinux, ubuntu1404, ubuntu1604, centos6, centos7.
-i, --instance-type
 

Sets instance type to build the ami on. Defaults to t2.xlarge.

Default: “t2.xlarge”

-ap, --ami-name-prefix
 

Specifies the prefix name of the resulting AWS ParallelCluster AMI.

Default: “custom-ami-“

-cc, --custom-cookbook
 Specifies the cookbook to use to build the AWS ParallelCluster AMI.
-c, --config Defines an alternative config file.
-r, --region Indicates which region to connect to.

configure

Start the AWS ParallelCluster configuration.

pcluster configure [-h] [-c CONFIG_FILE]

Named Arguments

-c, --config Defines an alternative config file.

version

Displays the version of AWS ParallelCluster.

pcluster version [-h]

For command specific flags, please run: “pcluster [command] –help”