(Required) Specifies the configuration for the head node.
HeadNode (p. 103):
InstanceType (p. 104): string Networking (p. 104):
SubnetId (p. 105): string
ElasticIp (p. 105): string/boolean SecurityGroups (p. 105):
- string - string
AdditionalSecurityGroups (p. 105):
- string - string Proxy (p. 105):
HttpProxyAddress (p. 105): string
DisableSimultaneousMultithreading (p. 104): boolean Ssh (p. 105):
KeyName (p. 106): string AllowedIps (p. 106): string LocalStorage (p. 106):
RootVolume (p. 106):
DeleteOnTermination (p. 107): boolean EphemeralVolume (p. 108): CustomActions (p. 109):
OnNodeStart (p. 109):
Script (p. 109): string Args (p. 109):
- string - string
Configuration files
OnNodeConfigured (p. 109):
Script (p. 109): string Args (p. 109):
- string - string Iam (p. 109):
InstanceRole (p. 110): string InstanceProfile (p. 110): string S3Access (p. 110):
- BucketName (p. 110): string
EnableWriteAccess (p. 110): boolean KeyName (p. 110): string
AdditionalIamPolicies (p. 111):
- Policy (p. 111): string Imds (p. 111):
Secured (p. 111): boolean
Topics
• HeadNode properties (p. 104)
• Networking (p. 104)
• Ssh (p. 105)
• LocalStorage (p. 106)
• Dcv (p. 108)
• CustomActions (p. 109)
• Iam (p. 109)
• Imds (p. 111)
HeadNode properties
InstanceType (Required, String)
Specifies the instance type for the head node.
Specifies the Amazon EC2 instance type that's used for the head node. The architecture of the instance type must be the same as the architecture used for the AWS Batch InstanceType (p. 116) or Slurm InstanceType (p. 120) setting.
Update policy: If this setting is changed, the update is not allowed. (p. 78) DisableSimultaneousMultithreading (Optional, Boolean)
If true, disables hyperthreading on the head node. The default value is false.
Not all instance types can disable hyperthreading. For a list of instance types that support disabling hyperthreading, see CPU cores and threads for each CPU core per instance type in the Amazon EC2 User Guide for Linux Instances.
Update policy: If this setting is changed, the update is not allowed. (p. 78)
Networking
(Required) Defines the networking configuration for the head node.
Networking (p. 104):
SubnetId (p. 105): string
ElasticIp (p. 105): string/boolean SecurityGroups (p. 105):
Configuration files
- string - string
AdditionalSecurityGroups (p. 105):
- string - string Proxy (p. 105):
HttpProxyAddress (p. 105): string
Networking properties SubnetId (Required, String)
Specifies the ID of an existing subnet in which to provision the head node.
Update policy: If this setting is changed, the update is not allowed. (p. 78) ElasticIp (Optional, String)
Creates or assigns an Elastic IP address to the head node. Supported values are true, false, or the ID of an existing Elastic IP address. The default is false.
Update policy: If this setting is changed, the update is not allowed. (p. 78) SecurityGroups (Optional, [String])
List of Amazon VPC security group ids to use for the head node. These replace the security groups that AWS ParallelCluster creates if this property is not included.
Update policy: This setting can be changed during an update. (p. 78) AdditionalSecurityGroups (Optional, [String])
List of additional Amazon VPC security group ids to use for the head node.
Update policy: This setting can be changed during an update. (p. 78) Proxy (Optional)
Specifies the proxy settings for the head node.
Proxy (p. 105):
HttpProxyAddress (p. 105): string
HttpProxyAddress (Optional, String)
Defines an HTTP or HTTPS proxy server, typically https://x.x.x.x:8080. There is no default value.
Update policy: If this setting is changed, the update is not allowed. (p. 78)
Ssh
(Optional) Defines the configuration for SSH access to the head node.
Ssh (p. 105):
KeyName (p. 106): string AllowedIps (p. 106): string
Update policy: This setting can be changed during an update. (p. 78)
Configuration files
Ssh Properties
KeyName (Optional, String)
Names an existing Amazon EC2 key pair to enable SSH access to the head node.
Update policy: If this setting is changed, the update is not allowed. (p. 78) AllowedIps (Optional, String)
Specifies the CIDR-formatted IP range for SSH connections to the head node. The default is 0.0.0.0/0.
Update policy: This setting can be changed during an update. (p. 78)
LocalStorage
(Optional) Defines the local storage configuration for the head node.
LocalStorage (p. 106):
RootVolume (p. 106):
Size (p. 106): integer Encrypted (p. 106): boolean VolumeType (p. 107): string Iops (p. 107): integer Throughput (p. 107): integer
DeleteOnTermination (p. 107): boolean EphemeralVolume (p. 108):
MountDir (p. 108): string
Update policy: This setting can be changed during an update. (p. 78)
LocalStorage Properties RootVolume (Required)
Specifies the root volume storage for the head node.
RootVolume (p. 106):
Size (p. 106): integer Encrypted (p. 106): boolean VolumeType (p. 107): string Iops (p. 107): integer Throughput (p. 107): integer
DeleteOnTermination (p. 107): boolean
Update policy: This setting can be changed during an update. (p. 78) Size (Optional, Integer)
Specifies the head node root volume size in gibibytes (GiB). The default size comes from the AMI. Using a different size requires that the AMI supports growroot.
Update policy: If this setting is changed, the update is not allowed. (p. 78) Encrypted (Optional, Boolean)
Specifies if the root volume is encrypted. The default value is false.
Update policy: If this setting is changed, the update is not allowed. (p. 78)
Configuration files
VolumeType (Optional, String)
Specifies the Amazon EBS volume type. Supported values are gp2, gp3, io1, io2, sc1, st1, and standard. The default value is gp2.
For more information, see Amazon EBS volume types in the Amazon EC2 User Guide for Linux Instances.
Update policy: If this setting is changed, the update is not allowed. (p. 78) Iops (Optional, Integer)
Defines the number of IOPS for io1, io2, and gp3 type volumes.
The default value, supported values, and volume_iops to volume_size ratio varies by VolumeType and Size.
VolumeType = io1 Default Iops = 100
Supported values Iops = 100–64000 †
Maximum Iops to Size ratio = 50 IOPS per GiB. 5000 IOPS requires a Size of at least 100 GiB.
VolumeType = io2 Default Iops = 100
Supported values Iops = 100–64000 (256000 for io2 Block Express volumes) †
Maximum Iops to Size ratio = 500 IOPS per GiB. 5000 IOPS requires a Size of at least 10 GiB.
VolumeType = gp3 Default Iops = 3000
Supported values Iops = 3000–16000
Maximum Iops to Size ratio = 500 IOPS per GiB. 5000 IOPS requires a Size of at least 10 GiB.
† Maximum IOPS is guaranteed only on Instances built on the Nitro System provisioned with more than 32,000 IOPS. Other instances guarantee up to 32,000 IOPS. Older io1 volumes might not reach full performance unless you modify the volume. io2 Block Express volumes support Iops values up to 256000 on R5b instance types. For more information, see io2 Block Express volumes in the Amazon EC2 User Guide for Linux Instances.
Update policy: This setting can be changed during an update. (p. 78) Throughput (Optional, Integer)
Defines the throughput for gp3 volume types, in MiB/s. This setting is valid only when VolumeType is gp3. The default value is 125. Supported values: 125–1000 MiB/s
The ratio of Throughput to Iops can be no more than 0.25. The maximum throughput of 1000 MiB/s requires that the Iops setting is at least 4000.
Update policy: This setting can be changed during an update. (p. 78) DeleteOnTermination (Optional, Boolean)
Specifies whether the root volume should be deleted when the head node is terminated. The default value is true.
Configuration files
Update policy: This setting can be changed during an update. (p. 78) EphemeralVolume (Optional)
Specifies details for any instance store volume. For more information, see Instance store volumes in the Amazon EC2 User Guide for Linux Instances.
EphemeralVolume (p. 108):
MountDir (p. 108): string
MountDir (Optional, String)
Specifies the mount directory for the instance store volume. The default is /scratch.
Update policy: If this setting is changed, the update is not allowed. (p. 78)
Dcv
(Optional) Defines configuration settings for the NICE DCV server running on the head node.
Dcv (p. 108):
Enabled (p. 108): boolean Port (p. 108): integer AllowedIps (p. 108): string
Important
By default, the NICE DCV port setup by AWS ParallelCluster is open to all IPv4 addresses.
However, you can connect to a NICE DCV port only if you have the URL for the NICE DCV session and connect to the NICE DCV session within 30 seconds of when the URL is returned from pcluster dcv connect. Use the AllowedIps setting to further restrict access to the NICE DCV port with a CIDR-formatted IP range, and use the Port setting to set a nonstandard port.
Update policy: If this setting is changed, the update is not allowed. (p. 78) Dcv properties
Enabled (Required, Boolean)
Specifies whether NICE DCV is enabled on the head node. The default value is false.
Update policy: If this setting is changed, the update is not allowed. (p. 78)
NoteNICE DCV automatically generates a self-signed certificate that's used to secure traffic between the NICE DCV client and NICE DCV server running on the head node. To configure your own certificate, see NICE DCV HTTPS certificate (p. 257).
Port (Optional, Integer)
Specifies the port for NICE DCV. The default value is 8443.
Update policy: If this setting is changed, the update is not allowed. (p. 78) AllowedIps (Optional, Recommended, String)
Specifies the CIDR-formatted IP range for connections to NICE DCV. This setting is used only when AWS ParallelCluster creates the security group. The default value is 0.0.0.0/0, which allows access from any internet address.
Update policy: This setting can be changed during an update. (p. 78)
Configuration files
CustomActions
(Optional) Specifies custom scripts to run on the head node.
CustomActions (p. 109):
OnNodeStart (p. 109):
Script (p. 109): string Args (p. 109):
- string - string
OnNodeConfigured (p. 109):
Script (p. 109): string Args (p. 109):
- string - string
Update policy: If this setting is changed, the update is not allowed. (p. 78) CustomActions properties
OnNodeStart (Optional, String)
Specifies a script to run on the head node before any node deployment bootstrap action is started.
For more information, see Custom Bootstrap Actions (p. 57).
Script (Required, String)
Specifies the file to use. The file path can start with https:// or s3://.
Args (Optional, [String])
List of arguments to pass to the script.
OnNodeConfigured (Optional, String)
Specifies a script to run on the head node after the node bootstrap actions are complete. For more information, see Custom Bootstrap Actions (p. 57).
Script (Required, String)
Specifies the file to use. The file path can start with https://, s3://, or file://.
Args (Optional, [String])
List of arguments to pass to the script.
Update policy: If this setting is changed, the update is not allowed. (p. 78) Iam
(Optional) Specifies either an instance role or an instance profile to use on the head node to override the default instance role or instance profile for the cluster.
Iam (p. 109):
InstanceRole (p. 110): string InstanceProfile (p. 110): string S3Access (p. 110):
- BucketName (p. 110): string
EnableWriteAccess (p. 110): boolean KeyName (p. 110): string
AdditionalIamPolicies (p. 111):
- Policy (p. 111): string
Configuration files
Update policy: This setting can be changed during an update. (p. 78)
Iam properties
InstanceProfile (Optional, String)
Specifies an instance profile to override the default head node instance profile.
You can't specify both InstanceProfile and InstanceRole. The format is arn:Partition:iam::Account:instance-profile/InstanceProfileName. If this is specified, the S3Access and AdditionalIamPolicies settings are ignored. We
recommend that you use AdditionalIamPolicies because features added to AWS ParallelCluster often require new permissions.
Update policy: If this setting is changed, the update is not allowed. (p. 78) InstanceRole (Optional, String)
Specifies an instance role to override the default head node instance role. You can't specify both InstanceProfile and InstanceRole. The format is arn:Partition:iam::Account:role/RoleName.
If this is specified, the S3Access and AdditionalIamPolicies settings are ignored. We
recommend that you use AdditionalIamPolicies because features added to AWS ParallelCluster often require new permissions.
Update policy: This setting can be changed during an update. (p. 78)
S3Access
S3Access (Optional)
Specifies a bucket. This is used to generate policies to grant the specified access to the bucket. If the InstanceProfile or InstanceRole setting is specified, this setting is ignored. We recommend that you use AdditionalIamPolicies because features added to AWS ParallelCluster often require new permissions.
S3Access (p. 110):
- BucketName (p. 110): string
EnableWriteAccess (p. 110): boolean KeyName (p. 110): string
Update policy: This setting can be changed during an update. (p. 78) BucketName (Required, String)
The name of the bucket.
Update policy: This setting can be changed during an update. (p. 78) KeyName (Optional, String)
The key for the bucket. The default value is "*".
Update policy: This setting can be changed during an update. (p. 78) EnableWriteAccess (Optional, Boolean)
Indicates whether write access is enabled for the bucket. The default value is false.
Update policy: This setting can be changed during an update. (p. 78)
Configuration files
AdditionalIamPolicies
AdditionalIamPolicies (Optional)
Specifies a list of Amazon Resource Names (ARNs) of IAM policies for Amazon EC2. This list is attached to the root role used for the head node in addition to the permissions required by AWS ParallelCluster.
An IAM policy name and its ARN are different. Names can't be used. If the InstanceProfile or InstanceRole setting is specified, this setting is ignored. We recommend that you use
AdditionalIamPolicies because AdditionalIamPolicies are added to the permissions that AWS ParallelCluster requires, and the InstanceRole must include all permissions required. The permissions required often change from release to release as features are added.
There is no default value.
AdditionalIamPolicies (p. 111):
- Policy (p. 111): string
Policy (Optional, [String]) List of IAM policies.
Update policy: This setting can be changed during an update. (p. 78)
Imds
(Optional) Specifies the properties for instance metadata service (IMDS). For more information, see How instance metadata service version 2 works in the Amazon EC2 User Guide for Linux Instances.
Imds (p. 111):
Secured (p. 111): boolean
Update policy: This setting can be changed during an update. (p. 78) Imds Properties
Secured (Optional, Boolean)
If true, restricts access to the head node's IMDS (and the instance profile credentials) to a subset of superusers.
NoteThis only restricts cluster head node IMDS access through the IPv4 IMDS endpoint.
If false, every user in the head node has access to the head node's IMDS.
The following users are permitted access to the head node's IMDS:
• root user
• cluster administrative user (pc-cluster-admin by default)
• operating system specific default user (ec2-user on Amazon Linux 2, ubuntu on Ubuntu 18.04, centos on CentOS 7)
The default is true.
The default users are responsible for ensuring a cluster has the permissions it needs to interact with AWS resources. If you disable default user IMDS access, AWS ParallelCluster can't manage the compute nodes and stops working. Don't disable default user IMDS access.
Configuration files
When a user is granted access to the head node's IMDS, they can use the permissions included in the head node's instance profile (p. 26). For example, they can use these permissions to launch EC2 instances or to read the password for an AD domain that the cluster is configured to use for authentication.
To restrict IMDS access, AWS ParallelCluster manages a chain of iptables.
Cluster users with sudo access can selectively enable or disable access to the head node's IMDS for other individual users, including default users, by running the command:
$ sudo /opt/parallelcluster/scripts/imds/imds-access.sh --allow <USERNAME>
You can disable user IMDS access with the --deny option for this command.
If you unknowingly disable default user IMDS access, you can restore the permission by using the --allow option.
NoteAny customization of iptables rules can interfere with the mechanism used to restrict IMDS access on the head node.
Update policy: If this setting is changed, the update is not allowed. (p. 78)