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. This helps avoid downtime during the process.
Overview of the hsm1.medium to hsm2m.medium migration process
Warning
AWS KMS CloudHSM key stores don't support hsm2m.medium clusters. Do not migrate until support is added.
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. Once the migration starts, your entire cluster
enters a limited-write mode. For more information, see Cluster limited-write mode.
To minimize impact, AWS CloudHSM changes HSMs from hsm1.medium to hsm2m.medium one at a time.
Here's how the migration works:
-
Before migrating the first HSM, AWS CloudHSM creates a full backup of the entire cluster.
-
Using this backup, AWS CloudHSM creates a new HSM of the requested type (hsm2m.medium) to replace the first HSM.
-
Before migrating each subsequent HSM, AWS CloudHSM creates a new full backup of the entire cluster.
-
AWS CloudHSM repeats steps 3 and 4 for each HSM in the cluster, migrating one HSM at a time.
-
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.
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
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 for details.
There have been no token key creations or deletions in the past 7 days.
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.
Warning
AWS KMS CloudHSM key stores do not support hsm2m.medium clusters. Please do not migrate until support is added.
Cluster limited-write mode
When you start the cluster 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.
To change the HSM type (console)
Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/home
. -
Select the radio button next to the ID of the cluster you want to change
-
From the Actions menu, choose
Modify HSM Typeand 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.
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:
-
Run the describe-clusters command.
-
Look for the
HsmTypeRollbackExpirationvalue. 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 to learn how to mitigate data loss after a rollback.
To roll back your HSM type (console)
Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/home
. -
Select the ID of the cluster you want to roll back.
-
From the Actions menu, choose
Modify HSM Typeand 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.
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 resolve this, use the CloudHSM CLI's key replicate command to replicate a key between two clusters. If you haven't installed it, see the instructions in Getting started with AWS CloudHSM Command Line Interface (CLI).
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
-
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<subnet ID 1><subnet ID 2>subnet ID N>\ --source-backup-id<backup ID>--mode<FIPS> -
Create an HSM in cluster-2:
aws cloudhsmv2 create-hsm --cluster-id<cluster-2 ID> -
List keys in cluster-2 that need replication:
cloudhsm-cli key list --cluster-id<cluster-2 ID -
Replicate each key from cluster-2 to cluster-1:
cloudhsm-cli key replicate --source-cluster-id<cluster-2 ID>\ --destination-cluster-id<cluster-1 ID>\ --filter attr.label=<key ID> -
Repeat step 4 for each key that needs copying.
-
Delete the HSM in cluster-2:
aws cloudhsmv2 delete-hsm --cluster-id<cluster-2 ID>--hsm-id<HSM ID> -
Delete cluster-2:
aws cloudhsmv2 delete-cluster --cluster-id<cluster-2 ID>
