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. |
For command specific flags, please run: “pcluster [command] –help”