# Clusters in AWS CloudHSM A cluster is a collection of individual hardware security modules (HSM) that AWS CloudHSM keeps in sync. When you perform a task or operation on one HSM in a cluster, the other HSMs in that cluster are automatically kept up to date. You can manage your AWS CloudHSM clusters from the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/) or one of the [AWS SDKs or command line tools](https://aws.amazon.com/tools/). For more information, see the following topics. To create a cluster, see [Getting started](getting-started.md). The following topics provide more information about clusters. **Topics** + [Cluster architecture](cluster-architecture.md) + [Cluster synchronization](cluster-synchronization.md) + [Cluster high availability and load balancing](cluster-high-availability-load-balancing.md) + [Cluster modes](cluster-hsm-types.md) + [HSM types](hsm-types.md) + [Connecting to the cluster](cluster-connect.md) + [Scaling HSMs](add-remove-hsm.md) + [Deleting a cluster](delete-cluster.md) + [Creating clusters from backups](create-cluster-from-backup.md) + [Migrating HSM cluster types](cluster-hsm-type-modification.md) # AWS CloudHSM cluster architecture When you create a cluster, you specify an Amazon Virtual Private Cloud (VPC) in your AWS account and one or more subnets in that VPC. We recommend that you create one subnet in each Availability Zone (AZ) in your chosen AWS Region. You can create private subnets when you create a VPC. To learn more, see [Create a virtual private cloud (VPC) for AWS CloudHSM](create-vpc.md). Each time you create an HSM, you specify the cluster and Availability Zone for the HSM. By putting the HSMs in different Availability Zones, you achieve redundancy and high availability in case one Availability Zone is unavailable. When you create an HSM, AWS CloudHSM puts an elastic network interface (ENI) in the specified subnet in your AWS account. The elastic network interface is the interface for interacting with the HSM. The HSM resides in a separate VPC in an AWS account that is owned by AWS CloudHSM. The HSM and its corresponding network interface are in the same Availability Zone. To interact with the HSMs in a cluster, you need the AWS CloudHSM client software. Typically you install the client on Amazon EC2 instances, known as *client instances*, that reside in the same VPC as the HSM ENIs, as shown in the following figure. That's not technically required though; you can install the client on any compatible computer, as long as it can connect to the HSM ENIs. The client communicates with the individual HSMs in your cluster through their ENIs. The following figure represents an AWS CloudHSM cluster with three HSMs, each in a different Availability Zone in the VPC. ![\[Architecture of an AWS CloudHSM cluster with three HSMs.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/cluster-architecture.png) # AWS CloudHSM cluster synchronization In an AWS CloudHSM cluster, AWS CloudHSM keeps the keys on the individual HSMs in sync. You don't need to do anything to synchronize the keys on your HSMs. To keep the users and policies on each HSM in sync, update the AWS CloudHSM client configuration file before you [manage HSM users](manage-hsm-users.md). For more information, see [Keep HSM users in sync](troubleshooting-keep-hsm-users-in-sync.md). When you add a new HSM to a cluster, AWS CloudHSM makes a backup of all keys, users, and policies on an existing HSM. It then restores that backup onto the new HSM. This keeps the two HSMs in sync. If the HSMs in a cluster fall out of synchronization, AWS CloudHSM automatically resynchronizes them. To enable this, AWS CloudHSM uses the credentials of the [appliance user](understanding-users.md). This user exists on all HSMs provided by AWS CloudHSM and has limited permissions. It can get a hash of objects on the HSM and can extract and insert masked (encrypted) objects. AWS cannot view or modify your users or keys and cannot perform any cryptographic operations using those keys. # AWS CloudHSM cluster high availability and load balancing When you create an AWS CloudHSM cluster with more than one HSM, you automatically get load balancing. Load balancing means that the [AWS CloudHSM client](client-tools-and-libraries.md) distributes cryptographic operations across all HSMs in the cluster based on each HSM's capacity for additional processing. When you create the HSMs in different AWS Availability Zones, you automatically get high availability. High availability means that you get higher reliability because no individual HSM is a single point of failure. We recommend that you have a minimum of two HSMs in each cluster, with each HSM in different Availability Zones within an AWS Region. For example, the following figure shows an Oracle database application that is distributed to two different Availability Zones. The database instances store their master keys in a cluster that includes an HSM in each Availability Zone. AWS CloudHSM automatically synchronizes the keys to both HSMs so that they are immediately accessible and redundant. ![\[An application and AWS CloudHSM cluster distributed to two Availability Zones for high availability.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/high-availability.png) # AWS CloudHSM cluster modes AWS CloudHSM offers clusters in two modes: *FIPS* and *non-FIPS*. In FIPS mode, only Federal Information Processing Standard (FIPS) validated keys and algorithms can be used. Non-FIPS mode offers all the keys and algorithms that are supported by AWS CloudHSM, regardless of FIPS approval. Review the details on this page before deciding which cluster mode and HSM type is right for your needs. **Note** All clusters created before June 10, 2024 are in FIPS mode and have HSM type hsm1.medium. To see your cluster's mode and HSM type, use the [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) command. The following table lists the major differences between each cluster mode: | Differentiating feature | FIPS mode | Non-FIPS mode | | --- | --- | --- | | **HSM type compatibility** | Available with hsm1.medium and hsm2m.medium. | Available with hsm2m.medium. | | **Backup compatibility** | Can only be used to backup restore clusters in FIPS mode. | Can only be used to backup restore clusters in non-FIPS mode. | | **Key selection** | Supports generating and using keys with mechanisms that are FIPS approved[1](#cluster-mode-note-1). | Supports generating and using keys with all FIPS-validated mechanisms, in addition to other non-validated mechanisms. | | **Algorithms** | Supports AWS CloudHSM algorithms that are FIPS approved[1](#cluster-mode-note-1). | Supports AWS CloudHSM algorithms that are both FIPS approved and not FIPS approved. | [1] See [Deprecation notifications](compliance-dep-notif.md#compliance-dep-notif-1) for details. Before choosing a cluster mode, note that a cluster’s mode (FIPS or non-FIPS) cannot be changed after it is created, so ensure you select the right mode for your needs. # HSM types in AWS CloudHSM AWS CloudHSM also offers two hardware security module (HSM) types: *hsm1.medium* and *hsm2m.medium*. Review the details on this page before deciding which HSM type is right for your needs. In addition to cluster modes, AWS CloudHSM offers two HSM types: *hsm1.medium* and *hsm2m.medium*. Each HSM type uses different hardware, and each cluster can only contain one type of HSM. The following table lists the major differences between the two: | Differentiating feature | hsm1.medium | hsm2m.medium | | --- | --- | --- | | **Cluster mode compatibility** | Available for clusters in FIPS mode. | Available for clusters in FIPS or non-FIPS mode. | | **Network type compatibility** | Not available | Available for clusters in FIPS or non-FIPS mode. | | **Backup compatibility** | Can be used to backup and restore to **hsm1.medium** and **hsm2m.medium** clusters in FIPS mode. | Can only be used to backup and restore **hsm2m.medium** clusters. | | **Key capacity** | 3,300 per cluster. | 16,666 total keys, with asymmetric keys having a maximum of 3,333 per cluster. | | **[Client SDKs](use-hsm.md)** | Supports all Client SDKs. | Supports all Client SDKs. | | **[Client SDK versions](client-history.md)** | Compatible with SDK version 3.1.0 and later. | Compatible with Client SDK version 5.9.0 and later. | | **Region availability ** | CloudHSM no longer supports creating new clusters in any AWS Region. For more information, see [Deprecation notifications](compliance-dep-notif.md#hsm-dep-1) for details. | Available in AWS Regions that [CloudHSM is available.](https://docs.aws.amazon.com/general/latest/gr/cloudhsm.html) | | **Performance** | To see the performance of each HSM type, refer to [AWS CloudHSM performance information](performance.md). | | **Certification** | FIPS 140-2, PCI DSS, PCI PIN, SOC2, and PCI-3DS compliant. | FIPS 140-3, PCI DSS, PCI PIN, SOC2 and PCI-3DS compliant. | # Connect the client SDK to the AWS CloudHSM cluster To connect to the cluster with either Client SDK 5 or Client SDK 3, you must first do two things: + Have an issuing certificate in place on the EC2 instance + Bootstrap the Client SDK to the cluster ## Place the issuing certificate on each EC2 instance You create the issuing certificate when you initialize the cluster. Copy the issuing certificate to the default location for the platform on each EC2 instance that connects to the cluster. ------ #### [ Linux ] ``` /opt/cloudhsm/etc/customerCA.crt ``` ------ #### [ Windows ] ``` C:\ProgramData\Amazon\CloudHSM\customerCA.crt ``` ------ ## Specify the location of the issuing certificate With Client SDK 5, you use the configure tool to specify the location of the issuing certificate. ------ #### [ PKCS \$111 library ] **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --hsm-ca-cert ``` ------ #### [ OpenSSL Dynamic Engine ] **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-dyn --hsm-ca-cert ``` ------ #### [ OpenSSL Dynamic Engine Provider ] **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider --hsm-ca-cert ``` ------ #### [ Key Storage Provider (KSP) ] **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --hsm-ca-cert ``` ------ #### [ JCE provider ] **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-jce --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --hsm-ca-cert ``` ------ #### [ CloudHSM CLI ] **To place the issuing certificate on Linux for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` $ sudo /opt/cloudhsm/bin/configure-cli --hsm-ca-cert ``` **To place the issuing certificate on Windows for Client SDK 5** + Use the configure tool to specify a location for the issuing certificate. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --hsm-ca-cert ``` ------ For more information, see [Configure Tool](configure-sdk-5.md). For more information about initializing the cluster or creating and signing the certificate, see [Initialize the Cluster](initialize-cluster.md#initialize). ## Bootstrap the Client SDK The bootstrap process is different depending on the version of the Client SDK you're using, but you must have the IP address of one of the hardware security modules (HSM) in the cluster. You can use the IP address of any HSM attached to your cluster. After the Client SDK connects, it retrieves the IP addresses of any additional HSMs and performs load balancing and client-side key synchronization operations. ### To get an IP address for the cluster **To get an IP address for an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. To change the AWS Region, use the Region selector in the upper-right corner of the page. 1. To open the cluster detail page, in the cluster table, choose the cluster ID. 1. To get the IP address, go to the HSMs tab. For IPv4 clusters, choose an address listed under **ENI IPv4 address**. For dual-stack clusters use either the ENI IPv4 or the **ENI IPv6 address**. **To get an IP address for an HSM (AWS CLI)** + Get the IP address of an HSM by using the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command from the AWS CLI. In the output from the command, the IP address of the HSMs are the values of `EniIp` and `EniIpV6` (if it is a dual-stack cluster). ``` $ aws cloudhsmv2 describe-clusters { "Clusters": [ { ... } "Hsms": [ { ... "EniIp": "10.0.0.9", ... }, { ... "EniIp": "10.0.1.6", "EniIpV6": "2600:113f:404:be09:310e:ed34:3412:f733", ... ``` For more information about bootstrapping, see [Configure Tool](configure-tool.md). ### To bootstrap Client SDK 5 ------ #### [ PKCS \$111 library ] **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-pkcs11 -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" -a ``` ------ #### [ OpenSSL Dynamic Engine ] **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-dyn -a ``` ------ #### [ OpenSSL Dynamic Engine Provider ] **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-openssl-provider -a ``` ------ #### [ Key Storage Provider (KSP) ] **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" -a ``` ------ #### [ JCE provider ] **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-jce -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" -a ``` ------ #### [ CloudHSM CLI ] **To bootstrap a Linux EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of the HSM(s) in your cluster. ``` $ sudo /opt/cloudhsm/bin/configure-cli -a ``` **To bootstrap a Windows EC2 instance for Client SDK 5** + Use the configure tool to specify the IP address of the HSM(s) in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" -a ``` ------ **Note** you can use the `–-cluster-id` parameter in place of `-a `. To see requirements for using `–-cluster-id`, see [AWS CloudHSM Client SDK 5 configure tool](configure-sdk-5.md). ### To bootstrap Client SDK 3 **To bootstrap a Linux EC2 instance for Client SDK 3** + Use **configure** to specify the IP address of an HSM in your cluster. ``` sudo /opt/cloudhsm/bin/configure -a ``` **To bootstrap a Windows EC2 instance for Client SDK 3** + Use **configure** to specify the IP address of an HSM in your cluster. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a ``` For more information about configure, see [AWS CloudHSM configure tool](configure-tool.md). # Scaling HSMs in an AWS CloudHSM cluster To scale up or down your AWS CloudHSM cluster, add or remove HSMs by using the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/) or one of the [AWS SDKs or command line tools](https://aws.amazon.com/tools/). We recommend load testing your cluster to determine the peak load you should anticipate, and then add one more HSM to it to ensure high availability. **Topics** + [Adding an HSM to an AWS CloudHSM cluster](add-hsm.md) + [Removing an HSM from an AWS CloudHSM cluster](remove-hsm.md) # Adding an HSM to an AWS CloudHSM cluster The following figure illustrates the events that occur when you add an HSM to a cluster. ![\[Animation showing the events that occur when you add an HSM to a cluster.\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/images/add-hsm.gif) 1. You add a new HSM to a cluster. The following procedures explain how to do this from the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), and the [AWS CloudHSM API](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/). This is the only action that you take. The remaining events occur automatically. 1. AWS CloudHSM makes a backup copy of an existing HSM in the cluster. For more information, see [Backups](backups.md). 1. AWS CloudHSM restores the backup onto the new HSM. This ensures that the HSM is in sync with the others in the cluster. 1. The existing HSMs in the cluster notify the AWS CloudHSM client that there's a new HSM in the cluster. 1. The client establishes a connection to the new HSM. **To add an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Choose a cluster for the HSM that you are adding. 1. On the **HSMs** tab, choose **Create HSM**. 1. Choose an Availability Zone (AZ) for the HSM that you are creating. Then choose **Create**. **To add an HSM (AWS CLI)** + At a command prompt, issue the **[create-hsm](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-hsm.html)** command, specifying a cluster ID and an Availability Zone for the HSM that you are creating. If you don't know the cluster ID of your preferred cluster, issue the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command. Specify the Availability Zone in the form of `us-east-2a`, `us-east-2b`, etc. ``` $ aws cloudhsmv2 create-hsm --cluster-id --availability-zone { "Hsm": { "State": "CREATE_IN_PROGRESS", "ClusterId": "cluster-5a73d5qzrdh", "HsmId": "hsm-lgavqitns2a", "SubnetId": "subnet-0e358c43", "AvailabilityZone": "us-east-2c", "EniId": "eni-bab18892", "EniIp": "10.0.3.10", "EniIpV6": "2600:113f:404:be09:310e:ed34:3412:f733" } } ``` **To add an HSM (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html) request, specifying the cluster ID and an Availability Zone for the HSM that you are creating. # Removing an HSM from an AWS CloudHSM cluster You can remove an HSM by using the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS CLI](https://aws.amazon.com/cli/), or the AWS CloudHSM API. **To remove an HSM (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Choose the cluster that contains the HSM that you are removing. 1. On the **HSMs** tab, choose the HSM that you are removing. Then choose **Delete HSM**. 1. Confirm that you want to delete the HSM. Then choose **Delete**. **To remove an HSM (AWS CLI)** + At a command prompt, issue the **[delete-hsm](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/delete-hsm.html)** command. Pass the ID of the cluster that contains the HSM that you are deleting and one of the following HSM identifiers: + The HSM ID (`--hsm-id`) + The HSM IP address (`--eni-ip`) + The HSM's elastic network interface ID (`--eni-id`) If you don't know the values for these identifiers, issue the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command. ``` $ aws cloudhsmv2 delete-hsm --cluster-id --eni-ip { "HsmId": "hsm-lgavqitns2a" } ``` **To remove an HSM (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteHsm.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteHsm.html) request, specifying the cluster ID and an identifier for the HSM that you are deleting. # Deleting an AWS CloudHSM cluster Before you can delete a cluster, you must remove all HSMs from the cluster. For more information, see [Removing an HSM from an AWS CloudHSM cluster](remove-hsm.md). After you remove all HSMs, you can delete a cluster by using the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/), the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), or the AWS CloudHSM API. **To delete a cluster (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Choose the cluster that you are deleting. Then choose **Delete cluster**. 1. Confirm that you want to delete the cluster, then choose **Delete**. **To delete a cluster (AWS CLI)** + At a command prompt, issue the **[delete-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/delete-cluster.html)** command, passing the ID of the cluster that you are deleting. If you don't know the cluster ID, issue the **[describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html)** command. ``` $ aws cloudhsmv2 delete-cluster --cluster-id { "Cluster": { "Certificates": { "ClusterCertificate": "" }, "SourceBackupId": "backup-rtq2dwi2gq6", "SecurityGroup": "sg-40399d28", "CreateTimestamp": 1504903546.035, "SubnetMapping": { "us-east-2a": "subnet-f1d6e798", "us-east-2c": "subnet-0e358c43", "us-east-2b": "subnet-40ed9d3b" }, "ClusterId": "cluster-kdmrayrc7gi", "VpcId": "vpc-641d3c0d", "State": "DELETE_IN_PROGRESS", "HsmType": "hsm1.medium", "StateMessage": "The cluster is being deleted.", "Hsms": [], "BackupPolicy": "DEFAULT" } } ``` **To delete a cluster (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteCluster.html) request, specifying the ID of the cluster that you are deleting. # Creating AWS CloudHSM clusters from backups To restore an AWS CloudHSM cluster from a backup, follow the steps in this topic. Your cluster will contain the same users, key material, certificates, configuration, and policies that were in the backup. For more information about managing backups, see [Cluster backups](manage-backups.md). ## Create clusters from backups (console) 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Choose **Create cluster**. 1. In the **Cluster configuration** section, do the following: 1. For **VPC**, choose a VPC for the cluster that you are creating. 1. For **AZ(s)**, choose a private subnet for each Availability Zone that you are adding to the cluster. 1. For **Network type**, choose the IP protocol your HSMs will use for connections. 1. In the **Cluster source** section, do the following: 1. Choose **Restore cluster from existing backup**. 1. Choose the backup that you are restoring. 1. Choose **Next: Review**. 1. Review your cluster configuration, then choose **Create cluster**. 1. Specify how long the service should retain backups. Accept the default retention period of 90 days or type a new value between 7 and 379 days. The service will automatically delete backups in this cluster older than the value you specify here. You can change this later. For more information, see [Configure backup retention](manage-backup-retention.md). 1. Choose **Next**. 1. (Optional) Type a tag key and an optional tag value. To add more than one tag to the cluster, choose **Add tag**. 1. Choose **Review**. 1. Review your cluster configuration, and then choose **Create cluster**. **Tip** To create an HSM in this cluster that contains the same users, key material, certificates, configuration, and policies that were in the backup that you restored, [add an HSM](add-hsm.md) to the cluster. ## Create clusters from backups (AWS CLI) To determine the backup ID, issue the **[describe-backups](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-backups.html)** command. + At a command prompt, issue the **[create-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/create-cluster.html)** command. Specify the HSM instance type, the subnet IDs of the subnets where you plan to create HSMs, and the backup ID of the backup that you are restoring. ``` $ aws cloudhsmv2 create-cluster --hsm-type hsm2m.medium \ --subnet-ids \ --source-backup-id --mode \ --network-type { "Cluster": { "HsmType": "hsm2m.medium", "VpcId": "vpc-641d3c0d", "Hsms": [], "State": "CREATE_IN_PROGRESS", "SourceBackupId": "backup-rtq2dwi2gq6", "BackupPolicy": "DEFAULT", "BackupRetentionPolicy": { "Type": "DAYS", "Value": 90 }, "NetworkType": "IPV4", "SecurityGroup": "sg-640fab0c", "CreateTimestamp": 1504907311.112, "SubnetMapping": { "us-east-2c": "subnet-0e358c43", "us-east-2a": "subnet-f1d6e798", "us-east-2b": "subnet-40ed9d3b" }, "Certificates": { "ClusterCertificate": "" }, "ClusterId": "cluster-jxhlf7644ne" } } ``` ## Create clusters from backups (AWS CloudHSM API) Refer to the following topic to learn how to create clusters from backups by using the API. + [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html) # Cluster HSM type migration AWS CloudHSM offers the ability to change the HSM type of an existing cluster. Review the table on this page to determine whether the HSM type modification is allowed. For more information on the types of HSMs supported and their features please refer to [HSM types in AWS CloudHSM](hsm-types.md). **Note** You cannot change the FIPS mode of a cluster during this operation. | From | To | Comment | | --- | --- | --- | | hsm1.medium | hsm2m.medium | Allowed | | hsm2m.medium | hsm1.medium | Conditional. You can roll back from hsm2m.medium to hsm1.medium within 24 hours of the start of a migration. | **Topics** + [Migrating from hsm1.medium to hsm2m.medium](hsm1-to-hsm2-migration.md) # Migrating from hsm1.medium to hsm2m.medium You can migrate your AWS CloudHSM cluster from hsm1.medium to hsm2m.medium. This topic describes the prerequisites, migration process, and rollback procedures. Before starting the migration, make sure your application follows the recommendations in [Architect your cluster for high availability](bp-cluster-management.md#bp-high-availability). This helps avoid downtime during the process. **Note** Automatic migrations to hsm2m.medium will begin on January 20th, 2026. ## Overview of the hsm1.medium to hsm2m.medium migration process You can start the migration using the AWS CloudHSM Console, the AWS CLI, or the AWS CloudHSM API. No matter where you initiate it, the AWS CloudHSM cluster migration uses the `modify-cluster` API endpoint. Alternatively, AWS CloudHSM will automatically migrate cluster on your behalf. Once the migration starts, your entire cluster enters a limited-write mode. For more information, see [Cluster limited-write mode](#migration-limited-write-mode). To minimize impact, AWS CloudHSM changes HSMs from hsm1.medium to hsm2m.medium one at a time. The replacement HSMs maintain the same IP addresses, thereby requiring no configuration changes during or after migration. Here's how the migration works: 1. Before migrating the first HSM, AWS CloudHSM creates a full backup of the entire cluster. 1. Using this backup, AWS CloudHSM creates a new HSM of the requested type (hsm2m.medium) to replace the first HSM. 1. Before migrating each subsequent HSM, AWS CloudHSM creates a new full backup of the entire cluster. 1. AWS CloudHSM repeats steps 3 and 4 for each HSM in the cluster, migrating one HSM at a time. 1. Each individual HSM migration takes approximately 30 minutes. AWS CloudHSM monitors cluster health and performs validations throughout the migration process. If AWS CloudHSM detects an increase in errors or a validation check fails, it will automatically stop the migration and revert the cluster to its original HSM type. You can also roll back manually for up to 24 hours after starting the migration. Before rolling back, see [HSM type rollback considerations](#rollback-migration). ## Prerequisites for migrating to hsm2m.medium Your existing AWS CloudHSM cluster must meet these requirements to migrate to hsm2m.medium. If any condition isn't met during validation checks, AWS CloudHSM automatically reverts the cluster to its original HSM type. For a list of known migration issues, see [Known issues for AWS CloudHSM cluster modification](ki-cluster-modification.md) + In the last 7 days: + All client connections have used SDK 5.9 or higher. + If performing ECDSA Verify, all client connections have used SDK 5.13 or higher. + AWS CloudHSM instances have used only supported (and none of the deprecated) functionalities. See [Deprecation notifications](compliance-dep-notif.md#compliance-dep-notif-1) for details. + You must have used an SDK to connect with at least one HSM in the cluster in the past 7 days. + The cluster is in an ACTIVE state. + The cluster has 27 HSMs or fewer. + The error rate for HSM operations doesn't increase during migration. **Note** The previous restriction which prevented customers with token key workloads from migrating has been removed. ## Cluster limited-write mode When your cluster starts migration, it enters a limited-write mode. Operations that can change the HSM state are rejected. All read operations remain unaffected. During migration, your application receives an error from the HSM when attempting these operations: + Token key generation and deletion (session key workloads continue to operate). + All user creation, deletion, or modification. + Quorum operations. + Modification of keys within the HSM, such as changing key attributes. + mTLS registration. AWS CloudHSM also places your cluster in a `MODIFY_IN_PROGRESS` state during migration. During this time, you can't add or remove HSMs from the cluster. ## Starting the migration The cluster migration process replaces individual HSMs in your cluster one at a time. The duration depends on the number of HSMs in your cluster. On average, this process takes about 30 minutes per HSM. You can track progress by monitoring the HSM type of individual HSMs in the cluster to see how many have been migrated to the new type. ------ #### [ Console ] **To change the HSM type (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the radio button next to the ID of the cluster you want to change 1. From the Actions menu, choose `Modify HSM Type` and select the desired HSM type This procedure puts your cluster into the `MODIFY_IN_PROGRESS` state. After migration, your cluster returns to the `ACTIVE` state. ------ #### [ AWS CLI ] **To change the HSM type ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[ modify-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/modify-cluster.html)** command. Specify the cluster ID and the desired HSM type. ``` $ aws cloudhsmv2 modify-cluster --cluster-id --hsm-type { "Cluster": { "BackupPolicy": "DEFAULT", "BackupRetentionPolicy": { "Type": "DAYS", "Value": 90 }, "VpcId": "vpc-50ae0636", "SubnetMapping": { "us-west-2b": "subnet-49a1bc00", "us-west-2c": "subnet-6f950334", "us-west-2a": "subnet-fd54af9b" }, "SecurityGroup": "sg-6cb2c216", "HsmType": "hsm2m.medium", "HsmTypeRollbackExpiration": 1730383180.000, "Certificates": {}, "State": "MODIFY_IN_PROGRESS", "Hsms": [], "ClusterId": "cluster-igklspoyj5v", "ClusterMode": "FIPS", "CreateTimestamp": 1502423370.069 } } ``` This procedure puts your cluster into the `MODIFY_IN_PROGRESS` state. After migration, your cluster returns to the `ACTIVE` state. ------ #### [ AWS CloudHSM API ] **To change the HSM type (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html) request. Specify the cluster ID and the desired HSM type for the cluster. This procedure puts your cluster into the `MODIFY_IN_PROGRESS` state. After migration, your cluster returns to the `ACTIVE` state. ------ ## Rolling back the migration AWS CloudHSM monitors for elevated error rates and performs continuous validation checks throughout the migration. If AWS CloudHSM detects a decrease in service quality or any validation failures, it automatically initiates a rollback to your cluster's original HSM type. During a rollback, for each HSM in the cluster: + AWS CloudHSM uses the backup taken at the start of that HSM's migration. + It replaces one HSM at a time until all HSMs are returned to the original type. + Your cluster remains in limited-write mode throughout the process. You can roll back the migration within 24 hours of starting it. To check the rollback deadline: 1. Run the [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) command. 1. Look for the `HsmTypeRollbackExpiration` value. This timestamp is your rollback deadline. If you decide to roll back, do it before this deadline. The rollback uses the latest backup of your original HSM type. **Warning** Be cautious about rolling back after a migration is complete. If you complete a migration and then use AWS CloudHSM to create new keys or users, rolling back can result in data loss. See [Synchronizing Data After a Rollback](#cluster-rollback-datasync) to learn how to mitigate data loss after a rollback. ------ #### [ Console ] **To roll back your HSM type (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. Select the ID of the cluster you want to roll back. 1. From the Actions menu, choose `Modify HSM Type` and select the original HSM type This procedure puts your cluster into the `ROLLBACK_IN_PROGRESS` state. After rollback, your cluster returns to the `ACTIVE` state. ------ #### [ AWS CLI ] **To roll back your HSM type ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/))** + At a command prompt, run the **[ modify-cluster](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/modify-cluster.html)** command. Specify the cluster ID and the original HSM type. ``` $ aws cloudhsmv2 modify-cluster --cluster-id --hsm-type { "Cluster": { "BackupPolicy": "DEFAULT", "BackupRetentionPolicy": { "Type": "DAYS", "Value": 90 }, "VpcId": "vpc-50ae0636", "SubnetMapping": { "us-west-2b": "subnet-49a1bc00", "us-west-2c": "subnet-6f950334", "us-west-2a": "subnet-fd54af9b" }, "SecurityGroup": "sg-6cb2c216", "HsmType": "hsm1.medium", "HsmTypeRollbackExpiration": 1730383180.000, "Certificates": {}, "State": "ROLLBACK_IN_PROGRESS", "Hsms": [], "ClusterId": "cluster-igklspoyj5v", "ClusterMode": "FIPS", "CreateTimestamp": 1502423370.069 } } ``` This procedure puts your cluster into the `ROLLBACK_IN_PROGRESS` state. After rollback, your cluster returns to the `ACTIVE` state. ------ #### [ AWS CloudHSM API ] **To roll back your HSM type (AWS CloudHSM API)** + Send a [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html) request. Specify the cluster ID and the original HSM type for the cluster. This procedure puts your cluster into the `ROLLBACK_IN_PROGRESS` state. After rollback, your cluster returns to the `ACTIVE` state. ------ ## Synchronizing data after a rollback During migration, HSMs are in limited-write mode, preventing changes to HSM state. If you roll back during this time (while the cluster is `MODIFY_IN_PROGRESS`), it results in a cluster with content identical to the original cluster. After your cluster returns to the `ACTIVE` state, limited-write mode is lifted. If you create a key or user while in `ACTIVE` state and then roll back, that key or user won't be present in your rolled back cluster. To address user synchronization, use [user management](manage-hsm-users-chsm-cli.md) with CloudHSM CLI to recreate the missing users on your rolled back cluster. The users must be manually recreated because the `user replicate` command does not support syncing users from hsm2m.medium to hsm1.medium. See user replicate [known issues](troubleshoot-sdk5-user-replicate-failures.md#troubleshoot-sdk5-user-replicate-failures-hsm2m-to-hsm1). To address key synchronization, use the [key replicate](cloudhsm_cli-key-replicate.md) command to replicate a key between two clusters. If you haven't installed CloudHSM CLI, see the instructions in [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md). **To synchronize keys after rollback** Follow these steps after completing the rollback. We'll use these terms: + "cluster-1": Your rolled back cluster (now hsm1.medium) + "cluster-2": A new temporary hsm2m.medium cluster that you will create 1. Create a new hsm2m.medium cluster (cluster-2) using the latest hsm2m.medium backup from cluster-1: ``` aws cloudhsmv2 create-cluster --hsm-type hsm2m.medium \ --subnet-ids \ --source-backup-id --mode ``` 1. Create an HSM in cluster-2: ``` aws cloudhsmv2 create-hsm --cluster-id ``` 1. List keys in cluster-2 that need replication: ``` cloudhsm-cli key list --cluster-id ``` 1. Replicate each key from cluster-2 to cluster-1: ``` cloudhsm-cli key replicate --source-cluster-id \ --destination-cluster-id \ --filter attr.label= ``` 1. Repeat step 4 for each key that needs copying. 1. Delete the HSM in cluster-2: ``` aws cloudhsmv2 delete-hsm --cluster-id --hsm-id ``` 1. Delete cluster-2: ``` aws cloudhsmv2 delete-cluster --cluster-id ```