clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview

Name	clusters
Type	Resource
Id	aws.pcs.clusters

Fields

The following fields are returned by SELECT queries:

get_cluster

Name	Datatype	Description
id	string	The generated unique ID of the cluster.
name	string	The name that identifies the cluster.
arn	string	The unique Amazon Resource Name (ARN) of the cluster.
created_at	string (date-time)	The date and time the resource was created.
endpoints	array	The list of endpoints available for interaction with the scheduler.
error_info	array	The list of errors that occurred during cluster provisioning.
modified_at	string (date-time)	The date and time the resource was modified.
networking	object	The networking configuration for the cluster's control plane.
scheduler	object	The cluster management and job scheduling software associated with the cluster.
size	string	The size of the cluster. SMALL: 32 compute nodes and 256 jobs MEDIUM: 512 compute nodes and 8192 jobs LARGE: 2048 compute nodes and 16,384 jobs (SMALL, MEDIUM, LARGE)
slurm_configuration	object	Additional options related to the Slurm scheduler.
status	string	The provisioning status of the cluster. The provisioning status doesn't indicate the overall health of the cluster. The resource enters the SUSPENDING and SUSPENDED states when the scheduler is beyond end of life and we have suspended the cluster. When in these states, you can't use the cluster. The cluster controller is down and all compute instances are terminated. The resources still count toward your service quotas. You can delete a resource if its status is SUSPENDED. For more information, see Frequently asked questions about Slurm versions in PCS in the PCS User Guide. (CREATING, ACTIVE, UPDATING, DELETING, CREATE_FAILED, DELETE_FAILED, UPDATE_FAILED, SUSPENDING, SUSPENDED, RESUMING)

list_clusters

Name	Datatype	Description
id	string	The generated unique ID of the cluster.
name	string	The name that identifies the cluster.
arn	string	The unique Amazon Resource Name (ARN) of the cluster.
created_at	string (date-time)	The date and time the resource was created.
modified_at	string (date-time)	The date and time the resource was modified.
status	string	The provisioning status of the cluster. The provisioning status doesn't indicate the overall health of the cluster. The resource enters the SUSPENDING and SUSPENDED states when the scheduler is beyond end of life and we have suspended the cluster. When in these states, you can't use the cluster. The cluster controller is down and all compute instances are terminated. The resources still count toward your service quotas. You can delete a resource if its status is SUSPENDED. For more information, see Frequently asked questions about Slurm versions in PCS in the PCS User Guide. (CREATING, ACTIVE, UPDATING, DELETING, CREATE_FAILED, DELETE_FAILED, UPDATE_FAILED, SUSPENDING, SUSPENDED, RESUMING)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_cluster	select	region		Returns detailed information about a running cluster in your account. This API action provides networking information, endpoint information for communication with the scheduler, and provisioning status.
list_clusters	select	region		Returns a list of running clusters in your account.
create_cluster	insert	region, clusterName, scheduler, size, networking		Creates a cluster in your account. PCS creates the cluster controller in a service-owned account. The cluster controller communicates with the cluster resources in your account. The subnets and security groups for the cluster must already exist before you use this API action. It takes time for PCS to create the cluster. The cluster is in a Creating state until it is ready to use. There can only be 1 cluster in a Creating state per Amazon Web Services Region per Amazon Web Services account. CreateCluster fails with a ServiceQuotaExceededException if there is already a cluster in a Creating state.
update_cluster	update	region, clusterIdentifier		Updates a cluster configuration. You can update the scheduler version, modify scheduler settings, and update accounting configuration for an existing cluster. For more information about updating the scheduler version, see Updating the scheduler version on a cluster in the PCS User Guide. You can only update clusters that are in ACTIVE, UPDATE_FAILED, or SUSPENDED state. All associated resources (queues and compute node groups) must be in ACTIVE state before you can update the cluster.
delete_cluster	delete	region		Deletes a cluster and all its linked resources. You must delete all queues and compute node groups associated with the cluster before you can delete the cluster.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_cluster

Returns detailed information about a running cluster in your account. This API action provides networking information, endpoint information for communication with the scheduler, and provisioning status.

SELECT
id,
name,
arn,
created_at,
endpoints,
error_info,
modified_at,
networking,
scheduler,
size,
slurm_configuration,
status
FROM aws.pcs.clusters
WHERE region = '{{ region }}' -- required
;

list_clusters

Returns a list of running clusters in your account.

SELECT
id,
name,
arn,
created_at,
modified_at,
status
FROM aws.pcs.clusters
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_cluster

Creates a cluster in your account. PCS creates the cluster controller in a service-owned account. The cluster controller communicates with the cluster resources in your account. The subnets and security groups for the cluster must already exist before you use this API action. It takes time for PCS to create the cluster. The cluster is in a Creating state until it is ready to use. There can only be 1 cluster in a Creating state per Amazon Web Services Region per Amazon Web Services account. CreateCluster fails with a ServiceQuotaExceededException if there is already a cluster in a Creating state.

INSERT INTO aws.pcs.clusters (
clusterName,
scheduler,
size,
networking,
slurmConfiguration,
clientToken,
tags,
region
)
SELECT 
'{{ clusterName }}' /* required */,
'{{ scheduler }}' /* required */,
'{{ size }}' /* required */,
'{{ networking }}' /* required */,
'{{ slurmConfiguration }}',
'{{ clientToken }}',
'{{ tags }}',
'{{ region }}'
RETURNING
cluster
;

Manifest

# Description fields are for documentation purposes
- name: clusters
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the clusters resource.
  - name: clusterName
    value: "{{ clusterName }}"
    description: |
      A name to identify the cluster. Example: MyCluster
  - name: scheduler
    description: |
      The cluster management and job scheduling software associated with the cluster.
    value:
      type_: "{{ type_ }}"
      version: "{{ version }}"
  - name: size
    value: "{{ size }}"
    description: |
      A value that determines the maximum number of compute nodes in the cluster and the maximum number of jobs (active and queued). SMALL: 32 compute nodes and 256 jobs MEDIUM: 512 compute nodes and 8192 jobs LARGE: 2048 compute nodes and 16,384 jobs
    valid_values: ['SMALL', 'MEDIUM', 'LARGE']
  - name: networking
    description: |
      The networking configuration used to set up the cluster's control plane.
    value:
      subnetIds:
        - "{{ subnetIds }}"
      securityGroupIds:
        - "{{ securityGroupIds }}"
      networkType: "{{ networkType }}"
  - name: slurmConfiguration
    description: |
      Additional options related to the Slurm scheduler.
    value:
      scaleDownIdleTimeInSeconds: {{ scaleDownIdleTimeInSeconds }}
      slurmCustomSettings:
        - parameterName: "{{ parameterName }}"
          parameterValue: "{{ parameterValue }}"
      slurmdbdCustomSettings:
        - parameterName: "{{ parameterName }}"
          parameterValue: "{{ parameterValue }}"
      cgroupCustomSettings:
        - parameterName: "{{ parameterName }}"
          parameterValue: "{{ parameterValue }}"
      accounting:
        defaultPurgeTimeInDays: {{ defaultPurgeTimeInDays }}
        mode: "{{ mode }}"
      slurmRest:
        mode: "{{ mode }}"
  - name: clientToken
    value: "{{ clientToken }}"
    description: |
      A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully, the subsequent retries with the same client token return the result from the original successful request and they have no additional effect. If you don't specify a client token, the CLI and SDK automatically generate 1 for you.
  - name: tags
    value: "{{ tags }}"
    description: |
      1 or more tags added to the resource. Each tag consists of a tag key and tag value. The tag value is optional and can be an empty string.

UPDATE examples

update_cluster

Updates a cluster configuration. You can update the scheduler version, modify scheduler settings, and update accounting configuration for an existing cluster. For more information about updating the scheduler version, see Updating the scheduler version on a cluster in the PCS User Guide. You can only update clusters that are in ACTIVE, UPDATE_FAILED, or SUSPENDED state. All associated resources (queues and compute node groups) must be in ACTIVE state before you can update the cluster.

UPDATE aws.pcs.clusters
SET 
clusterIdentifier = '{{ clusterIdentifier }}',
clientToken = '{{ clientToken }}',
slurmConfiguration = '{{ slurmConfiguration }}',
scheduler = '{{ scheduler }}'
WHERE 
region = '{{ region }}' --required
AND clusterIdentifier = '{{ clusterIdentifier }}' --required
RETURNING
cluster;

DELETE examples

delete_cluster

Deletes a cluster and all its linked resources. You must delete all queues and compute node groups associated with the cluster before you can delete the cluster.

DELETE FROM aws.pcs.clusters
WHERE region = '{{ region }}' --required
;