clusters

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

Overview

Name	`clusters`
Type	Resource
Id	`aws.cloudhsmv2.clusters`

Fields

The following fields are returned by SELECT queries:

describe_clusters

Name	Datatype	Description
`backup_policy`	`string`	The cluster's backup policy. (DEFAULT)
`backup_retention_policy`	`object`	A policy that defines how the service retains backups.
`certificates`	`object`	Contains one or more certificates or a certificate signing request (CSR).
`cluster_id`	`string`	The cluster's identifier (ID). (pattern: <code>cluster-[2-7a-zA-Z]{11,16}</code>)
`create_timestamp`	`string (date-time)`	The date and time when the cluster was created.
`hsm_type`	`string`	The type of HSM that the cluster contains. (pattern: <code>((p\|)hsm[0-9][a-z.]*.[a-zA-Z]+)</code>)
`hsm_type_rollback_expiration`	`string (date-time)`	The timestamp until when the cluster can be rolled back to its original HSM type.
`hsms`	`array`	Contains information about the HSMs in the cluster.
`mode`	`string`	The mode of the cluster. (FIPS, NON_FIPS)
`network_type`	`string`	The cluster's NetworkType can be IPv4 (the default) or DUALSTACK. The IPv4 NetworkType restricts communication between your application and the hardware security modules (HSMs) to the IPv4 protocol only. The DUALSTACK NetworkType enables communication over both IPv4 and IPv6 protocols. To use DUALSTACK, configure your virtual private cloud (VPC) and subnets to support both IPv4 and IPv6. This configuration involves adding IPv6 Classless Inter-Domain Routing (CIDR) blocks to the existing IPv4 CIDR blocks in your subnets. The NetworkType you choose affects the network addressing options for your cluster. DUALSTACK provides more flexibility by supporting both IPv4 and IPv6 communication. (IPV4, DUALSTACK)
`pre_co_password`	`string`	The default password for the cluster's Pre-Crypto Officer (PRECO) user.
`security_group`	`string`	The identifier (ID) of the cluster's security group. (pattern: <code>sg-[0-9a-fA-F]{8,17}</code>)
`source_backup_id`	`string`	The identifier (ID) of the backup used to create the cluster. This value exists only when the cluster was created from a backup. (pattern: <code>backup-[2-7a-zA-Z]{11,16}</code>)
`state`	`string`	The cluster's state. (CREATE_IN_PROGRESS, UNINITIALIZED, INITIALIZE_IN_PROGRESS, INITIALIZED, ACTIVE, UPDATE_IN_PROGRESS, MODIFY_IN_PROGRESS, ROLLBACK_IN_PROGRESS, DELETE_IN_PROGRESS, DELETED, DEGRADED)
`state_message`	`string`	A description of the cluster's state. (pattern: <code>.*</code>)
`subnet_mapping`	`object`	A map from availability zone to the cluster’s subnet in that availability zone.
`tag_list`	`array`	The list of tags for the cluster.
`vpc_id`	`string`	The identifier (ID) of the virtual private cloud (VPC) that contains the cluster. (pattern: <code>vpc-[0-9a-fA-F]</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Description
`describe_clusters`	`select`	`region`	Gets information about CloudHSM clusters. This is a paginated operation, which means that each response might contain only a subset of all the clusters. When the response contains only a subset of clusters, it includes a NextToken value. Use this value in a subsequent DescribeClusters request to get more clusters. When you receive a response with no NextToken (or an empty or null value), that means there are no more clusters to get. Cross-account use: No. You cannot perform this operation on CloudHSM clusters in a different Amazon Web Services account.
`create_cluster`	`insert`	`region`, `HsmType`, `SubnetIds`	Creates a new CloudHSM cluster. Cross-account use: Yes. To perform this operation with an CloudHSM backup in a different AWS account, specify the full backup ARN in the value of the SourceBackupId parameter.
`create_hsm`	`insert`	`region`, `ClusterId`, `AvailabilityZone`	Creates a new hardware security module (HSM) in the specified CloudHSM cluster. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Service account.
`modify_cluster`	`update`	`region`, `ClusterId`	Modifies CloudHSM cluster. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.
`delete_cluster`	`delete`	`region`	Deletes the specified CloudHSM cluster. Before you can delete a cluster, you must delete all HSMs in the cluster. To see if the cluster contains any HSMs, use DescribeClusters. To delete an HSM, use DeleteHsm. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.
`delete_hsm`	`exec`	`region`, `ClusterId`	Deletes the specified HSM. To specify an HSM, you can use its identifier (ID), the IP address of the HSM's elastic network interface (ENI), or the ID of the HSM's ENI. You need to specify only one of these values. To find these values, use DescribeClusters. Cross-account use: No. You cannot perform this operation on an CloudHSM hsm in a different Amazon Web Services account.
`initialize_cluster`	`exec`	`region`, `ClusterId`, `SignedCert`, `TrustAnchor`	Claims an CloudHSM cluster by submitting the cluster certificate issued by your issuing certificate authority (CA) and the CA's root certificate. Before you can claim a cluster, you must sign the cluster's certificate signing request (CSR) with your issuing CA. To get the cluster's CSR, use DescribeClusters. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.

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

describe_clusters

Gets information about CloudHSM clusters. This is a paginated operation, which means that each response might contain only a subset of all the clusters. When the response contains only a subset of clusters, it includes a NextToken value. Use this value in a subsequent DescribeClusters request to get more clusters. When you receive a response with no NextToken (or an empty or null value), that means there are no more clusters to get. Cross-account use: No. You cannot perform this operation on CloudHSM clusters in a different Amazon Web Services account.

SELECT
backup_policy,
backup_retention_policy,
certificates,
cluster_id,
create_timestamp,
hsm_type,
hsm_type_rollback_expiration,
hsms,
mode,
network_type,
pre_co_password,
security_group,
source_backup_id,
state,
state_message,
subnet_mapping,
tag_list,
vpc_id
FROM aws.cloudhsmv2.clusters
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_cluster
create_hsm
Manifest

Creates a new CloudHSM cluster. Cross-account use: Yes. To perform this operation with an CloudHSM backup in a different AWS account, specify the full backup ARN in the value of the SourceBackupId parameter.

INSERT INTO aws.cloudhsmv2.clusters (
BackupRetentionPolicy,
HsmType,
SourceBackupId,
SubnetIds,
NetworkType,
TagList,
Mode,
region
)
SELECT 
'{{ BackupRetentionPolicy }}',
'{{ HsmType }}' /* required */,
'{{ SourceBackupId }}',
'{{ SubnetIds }}' /* required */,
'{{ NetworkType }}',
'{{ TagList }}',
'{{ Mode }}',
'{{ region }}'
RETURNING
cluster
;

Creates a new hardware security module (HSM) in the specified CloudHSM cluster. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Service account.

INSERT INTO aws.cloudhsmv2.clusters (
ClusterId,
AvailabilityZone,
IpAddress,
region
)
SELECT 
'{{ ClusterId }}' /* required */,
'{{ AvailabilityZone }}' /* required */,
'{{ IpAddress }}',
'{{ region }}'
RETURNING
hsm
;

# Description fields are for documentation purposes
- name: clusters
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the clusters resource.
  - name: BackupRetentionPolicy
    description: |
      A policy that defines how the service retains backups.
    value:
      Type: "{{ Type }}"
      Value: "{{ Value }}"
  - name: HsmType
    value: "{{ HsmType }}"
    description: |
      The type of HSM to use in the cluster. The allowed values are hsm1.medium and hsm2m.medium.
  - name: SourceBackupId
    value: "{{ SourceBackupId }}"
    description: |
      The identifier (ID) or the Amazon Resource Name (ARN) of the cluster backup to restore. Use this value to restore the cluster from a backup instead of creating a new cluster. To find the backup ID or ARN, use DescribeBackups. If using a backup in another account, the full ARN must be supplied.
  - name: SubnetIds
    value:
      - "{{ SubnetIds }}"
    description: |
      The identifiers (IDs) of the subnets where you are creating the cluster. You must specify at least one subnet. If you specify multiple subnets, they must meet the following criteria: All subnets must be in the same virtual private cloud (VPC). You can specify only one subnet per Availability Zone.
  - name: NetworkType
    value: "{{ NetworkType }}"
    description: |
      The NetworkType to create a cluster with. The allowed values are IPV4 and DUALSTACK.
    valid_values: ['IPV4', 'DUALSTACK']
  - name: TagList
    description: |
      Tags to apply to the CloudHSM cluster during creation.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: Mode
    value: "{{ Mode }}"
    description: |
      The mode to use in the cluster. The allowed values are FIPS and NON_FIPS.
    valid_values: ['FIPS', 'NON_FIPS']
  - name: ClusterId
    value: "{{ ClusterId }}"
    description: |
      The identifier (ID) of the HSM's cluster. To find the cluster ID, use DescribeClusters.
  - name: AvailabilityZone
    value: "{{ AvailabilityZone }}"
    description: |
      The Availability Zone where you are creating the HSM. To find the cluster's Availability Zones, use DescribeClusters.
  - name: IpAddress
    value: "{{ IpAddress }}"
    description: |
      The HSM's IP address. If you specify an IP address, use an available address from the subnet that maps to the Availability Zone where you are creating the HSM. If you don't specify an IP address, one is chosen for you from that subnet.

`UPDATE` examples

modify_cluster

Modifies CloudHSM cluster. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.

UPDATE aws.cloudhsmv2.clusters
SET 
HsmType = '{{ HsmType }}',
BackupRetentionPolicy = '{{ BackupRetentionPolicy }}',
ClusterId = '{{ ClusterId }}'
WHERE 
region = '{{ region }}' --required
AND ClusterId = '{{ ClusterId }}' --required
RETURNING
cluster;

`DELETE` examples

delete_cluster

Deletes the specified CloudHSM cluster. Before you can delete a cluster, you must delete all HSMs in the cluster. To see if the cluster contains any HSMs, use DescribeClusters. To delete an HSM, use DeleteHsm. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.

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

Lifecycle Methods

delete_hsm
initialize_cluster

Deletes the specified HSM. To specify an HSM, you can use its identifier (ID), the IP address of the HSM's elastic network interface (ENI), or the ID of the HSM's ENI. You need to specify only one of these values. To find these values, use DescribeClusters. Cross-account use: No. You cannot perform this operation on an CloudHSM hsm in a different Amazon Web Services account.

EXEC aws.cloudhsmv2.clusters.delete_hsm 
@region='{{ region }}' --required 
@@json=
'{
"ClusterId": "{{ ClusterId }}", 
"HsmId": "{{ HsmId }}", 
"EniId": "{{ EniId }}", 
"EniIp": "{{ EniIp }}"
}'
;

Claims an CloudHSM cluster by submitting the cluster certificate issued by your issuing certificate authority (CA) and the CA's root certificate. Before you can claim a cluster, you must sign the cluster's certificate signing request (CSR) with your issuing CA. To get the cluster's CSR, use DescribeClusters. Cross-account use: No. You cannot perform this operation on an CloudHSM cluster in a different Amazon Web Services account.

EXEC aws.cloudhsmv2.clusters.initialize_cluster 
@region='{{ region }}' --required 
@@json=
'{
"ClusterId": "{{ ClusterId }}", 
"SignedCert": "{{ SignedCert }}", 
"TrustAnchor": "{{ TrustAnchor }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​