# Cluster backups in AWS CloudHSM AWS CloudHSM makes periodic backups of your cluster at least once every 24 hours. Each backup contains encrypted copies of the following data: + Users (COs, CUs, and AUs) + Key material and certificates + Hardware security module (HSM) configuration and policies You can't instruct the service to make backups, but you can take certain actions that force the service to create a backup. The service makes a backup when you perform any of the following actions: + Activate a cluster + Add an HSM to an active cluster + Remove an HSM from an active cluster AWS CloudHSM deletes backups based on the backup retention policy you set when you create clusters. For information about managing backup retention policy, see [Configure backup retention](manage-backup-retention.md). **Topics** + [Working with backups](backups-using.md) + [Delete backups](delete-restore-backup.md) + [Restore backups](restore-backup.md) + [Configure backup retention](manage-backup-retention.md) + [Copying backups across Regions](copy-backup-to-region.md) + [Working with shared backups](sharing.md) # Working with AWS CloudHSM cluster backups When you add a hardware security module (HSM) to a cluster in AWS CloudHSM that previously contained one or more active HSMs, the service restores the latest backup onto the new HSM. Use backups to manage HSMs you use infrequently. When you don't need the HSM, delete it to trigger a backup. Later, when you need the HSM, create a new one in the same cluster, and this action will restore the backup you previously created with the delete HSM operation. ## Removing expired keys or inactive users You may want to remove unwanted cryptographic materials from your environment such as expired keys or inactive users. This is a two-step process. First, delete these materials from your HSM. Next, delete all existing backups. Following this process ensures you do not restore deleted information when initializing a new cluster from backup. For more information, see [Delete AWS CloudHSM cluster backups](delete-restore-backup.md). ## Considering disaster recovery You can create a cluster from a backup. You might want to do this to set a recovery point for your cluster. Nominate a backup that contains all the users, key material, certificates that you want in your recovery point, and then use that backup to create a new cluster. For more information about creating a cluster from a backup, see [Creating clusters from backups](create-cluster-from-backup.md). You can also copy a backup of a cluster into a different region, where you can create a new cluster as a clone of the original. You may want to do this for a number of reasons, including simplification of the disaster recovery process. For more information about copying backups to regions, see [Copying backups across Regions](copy-backup-to-region.md). # Delete AWS CloudHSM cluster backups After you delete an AWS CloudHSM cluster backup, the service holds the backup for seven days, during which time you can restore the backup. After the seven-day period, you can no longer restore the backup. For more information about managing backups, see [Cluster backups](manage-backups.md). The following table describes how to delete a backup. ------ #### [ Console ] **To delete a backup (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. In the navigation pane, choose **Backups**. 1. Choose a backup to delete. 1. To delete the selected backup, choose **Actions, Delete**. The Delete backups dialog box appears. 1. Choose **Delete**. The state of the backup changes to `PENDING_DELETE`. You can restore a backup that is pending deletion for up to 7 days after you request the deletion. **To list backups (AWS CLI)** + To see a list of all backups in the `PENDING_DELETION` state, run the **describe-backups** command and include `states=PENDING_DELETION` as a filter. ``` $ aws cloudhsmv2 describe-backups --filters states=PENDING_DELETION { "Backups": [ { "BackupId": "backup-ro5c4er4aac", "BackupState": "PENDING_DELETION", "ClusterId": "cluster-dygnwhmscg5", "CreateTimestamp": 1534461854.64, "DeleteTimestamp": 1536339805.522, "HsmType": "hsm2m.medium", "Mode": "NON_FIPS", "NeverExpires": false, "TagList": [] } } ``` ------ #### [ AWS CLI ] Check the status of a backup or find its ID by using the **[describe-backups](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-backups.html)** command from the AWS CLI. **To delete a backup (AWS CLI)** + At a command prompt, run the **[delete-backup](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/delete-backup.html)** command, passing the ID of the backup to be deleted. ``` $ aws cloudhsmv2 delete-backup --backup-id { "Backup": { "CreateTimestamp": 1534461854.64, "ClusterId": "cluster-dygnwhmscg5", "BackupId": "backup-ro5c4er4aac", "BackupState": "PENDING_DELETION", "DeleteTimestamp": 1536339805.522, "HsmType": "hsm1.medium", "Mode": "FIPS" } } ``` ------ #### [ AWS CloudHSM API ] Refer to [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteBackup.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DeleteBackup.html) to learn how to delete backups by using the API. ------ # Restore AWS CloudHSM backups AWS CloudHSM holds deleted backups for seven days, during which time you can restore the backup. After the seven-day period, you can no longer restore the backup. For more information about managing backups, see [Cluster backups](manage-backups.md). The following table describes how to delete a backup. ------ #### [ Console ] **To restore a backup (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. In the navigation pane, choose **Backups**. 1. Choose a backup in the `PENDING_DELETE` state to restore. 1. To restore the selected backup, choose **Actions, Restore**. ------ #### [ AWS CLI ] **To restore a backup (AWS CLI)** + To restore a backup, issue the **[restore-backup](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/restore-backup.html)** command, passing the ID of a backup that is in the `PENDING_DELETION` state. ``` $ aws cloudhsmv2 restore-backup --backup-id { "Backup": { "ClusterId": "cluster-dygnwhmscg5", "CreateTimestamp": 1534461854.64, "BackupState": "READY", "BackupId": "backup-ro5c4er4aac" } } ``` ------ #### [ AWS CloudHSM API ] Refer to [RestoreBackup](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_RestoreBackup.html) to learn how to restore backups by using the API. ------ # Configure AWS CloudHSM backup retention policy AWS CloudHSM purges backups based on the backup retention policy you set when you create a cluster. Backup retention policy applies to clusters. If you move a backup to a different region, that backup is no longer associated with a cluster and has no backup retention policy. You must manually delete any backups not associated with a cluster. AWS CloudHSM does not delete a cluster's last backup. For clusters migrated from hsm1.medium, AWS CloudHSM retains the latest hsm1.medium backup until hsm1.medium reaches end of life. [AWS CloudTrail](get-api-logs-using-cloudtrail.md) reports backups marked for deletion. You can restore backups the service purges just as you would restore [manually deleted backups](delete-restore-backup.md). To prevent a race condition, you should change the backup retention policy for the cluster before you restore a backup deleted by the service. If you want to keep the retention policy the same and preserve select backups, you can specify that the service [exclude backups](#exclude-backups-console-proc) from the cluster backup retention policy. For more information on AWS CloudHSM pricing, see [Reduce costs by scaling to your needs](bp-cluster-management.md#bp-reduce-cost). ## Managed backup retention Clusters created before November 18, 2020 have a backup retention policy of 90 days plus the age of the cluster. For example, if you created a cluster on November 18, 2019, the service would assign your cluster a backup retention policy of one year plus 90 days (455 days). You can set this period to any number between 7 and 379 days. AWS CloudHSM does not delete a cluster's last backup. For more information about managing backups, see [Cluster backups](manage-backups.md). **Note** You can opt out of managed backup retention altogether by contacting [AWS Support](https://aws.amazon.com/support). The following table describes how to set the backup retention. ------ #### [ Console ] **To configure backup retention policy (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. Click the cluster ID of a cluster in the Active state to manage the backup retention policy for that cluster. 1. To change the backup retention policy, choose **Actions, Change backup retention period**. The Change backup retention period dialog box appears. 1. In **Backup retention period (in days)**, type a value between 7 and 379 days. 1. Choose **Change backup retention period**. **To exclude or include a backup from backup retention policy (console)** 1. Open the AWS CloudHSM console at [https://console.aws.amazon.com/cloudhsm/home](https://console.aws.amazon.com/cloudhsm/home). 1. To view your backups, in the navigation pane choose **Backups**. 1. Click the backup ID of a backup in the Ready state to exclude or include. 1. On the **Backup details** page, take one of the following actions. + To exclude a backup with a date in **Expiration time**, choose **Actions, Disable expiration**. + To include a backup that does not expire, choose **Actions, Use cluster retention policy**. ------ #### [ AWS CLI ] **To configure backup retention policy (AWS CLI)** + At a command prompt, issue the **modify-cluster** command. Specify the cluster ID and the backup retention policy. ``` $ aws cloudhsmv2 modify-cluster --cluster-id \ --backup-retention-policy Type=DAYS,Value= { "Cluster": { "BackupPolicy": "DEFAULT", "BackupRetentionPolicy": { "Type": "DAYS", "Value": 90 }, "Certificates": {}, "ClusterId": "cluster-kdmrayrc7gi", "CreateTimestamp": 1504903546.035, "Hsms": [], "HsmType": "hsm1.medium", "SecurityGroup": "sg-40399d28", "State": "ACTIVE", "SubnetMapping": { "us-east-2a": "subnet-f1d6e798", "us-east-2c": "subnet-0e358c43", "us-east-2b": "subnet-40ed9d3b" }, "TagList": [ { "Key": "Cost Center", "Value": "12345" } ], "VpcId": "vpc-641d3c0d" } } ``` **To exclude a backup from backup retention policy (AWS CLI)** + At a command prompt, issue the **modify-backup-attributes** command. Specify the backup ID and set the never-expires flag to preserve the backup. ``` $ aws cloudhsmv2 modify-backup-attributes --backup-id \ --never-expires { "Backup": { "BackupId": "backup-ro5c4er4aac", "BackupState": "READY", "ClusterId": "cluster-dygnwhmscg5", "NeverExpires": true } } ``` **To include a backup in backup retention policy (AWS CLI)** + At a command prompt, issue the **modify-backup-attributes** command. Specify the backup ID and set the no-never-expires flag to include the backup in backup retention policy, which means the service will eventually delete the backup. ``` $ aws cloudhsmv2 modify-backup-attributes --backup-id \ --no-never-expires { "Backup": { "BackupId": "backup-ro5c4er4aac", "BackupState": "READY", "ClusterId": "cluster-dygnwhmscg5", "NeverExpires": false } } ``` ------ #### [ AWS CloudHSM API ] Refer to the following topics to learn how to manage backup retention by using the API. + [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyCluster.html) + [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyBackupAttributes.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_ModifyBackupAttributes.html) ------ # Copying AWS CloudHSM cluster backups across AWS Regions You can copy AWS CloudHSM cluster backups across Regions for many reasons, including cross-region resilience, global workloads, and [disaster recovery](backups-using.md#recovery-backups). After you copy backups, they appear in the destination region with a `CREATE_IN_PROGRESS` status. Upon successful completion of the copy, the status of the backup changes to `READY`. If the copy fails, the status of the backup changes to `DELETED`. Check your input parameters for errors and ensure that the specified source backup is not in a `DELETED` state before rerunning the operation. For information about backups or how to create a cluster from a backup, see [Cluster backups](manage-backups.md) or [Creating clusters from backups](create-cluster-from-backup.md). Note the following: + To copy a cluster backup to a destination region, your account must have the proper IAM policy permissions. In order to copy the backup to a different region, your IAM policy must allow access to the source region in which the backup is located. Once copied across regions, your IAM policy must allow access to the destination region in order to interact with the copied backup, which includes using the [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateCluster.html) operation. For more information, see [Create IAM administrators](create-iam-user.md). + The original cluster and the cluster that may be built from a backup in the destination region are not linked. You must manage each of these clusters independently. For more information, see [Clusters](manage-clusters.md). + Backups cannot be copied between AWS partitions. Backups can be copied between AWS restricted regions and standard regions within the same partition. ## Copy backups to different Regions (console) **To copy backups to different Regions (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. In the navigation pane, choose **Backups**. 1. Choose a backup to copy to a different region. 1. To copy the selected backup, choose **Actions, Copy backup to another region**. The Copy backup to another region dialog box appears. 1. In **Destination region**, choose a region from **Select a region**. 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 **Copy backup**. ## Copy backups to different Regions (AWS CLI) To determine the backup ID, run the **[describe-backups](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-backups.html)** command. **To copy backups to different regions (AWS CLI)** + At a command prompt, run the **[ copy-backup-to-region](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/copy-backup-to-region.html)** command. Specify the destination region and the backup ID of the source backup. If you specify a backup ID, the associated backup is copied. ``` $ aws cloudhsmv2 copy-backup-to-region --destination-region \ --backup-id ``` ## Copy backups to different Regions (AWS CloudHSM API) Refer to the following topic to learn how to copy backups to different regions by using the API. + [https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CopyBackupToRegion.html](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CopyBackupToRegion.html) # Working with shared backups in AWS CloudHSM CloudHSM integrates with AWS Resource Access Manager (AWS RAM) to enable resource sharing. AWS RAM is a service that enables you to share some CloudHSM resources with other AWS accounts or through AWS Organizations. With AWS RAM, you share resources that you own by creating a *resource share*. A resource share specifies the resources to share, and the consumers with whom to share them. Consumers can include: + Specific AWS accounts inside or outside of its organization in AWS Organizations + An organizational unit inside its organization in AWS Organizations + An entire organization in AWS Organizations For more information about AWS RAM, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*. This topic explains how to share resources that you own, and how to use resources that are shared with you. **Topics** + [Prerequisites for sharing backups](#sharing-prereqs) + [Sharing a backup](#sharing-share) + [Unsharing a shared backup](#sharing-unshare) + [Identifying a shared backup](#sharing-identify) + [Permissions for shared backups](#sharing-perms) + [Billing and metering](#sharing-billing) ## Prerequisites for sharing backups + To share a backup, you must own it in your AWS account. This means that the resource must be allocated or provisioned in your account. You cannot share a backup that has been shared with you. + To share a backup, it must be in the *READY* state. + To share a backup with your organization or an organizational unit in AWS Organizations, you must enable sharing with AWS Organizations. For more information, see [ Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs) in the *AWS RAM User Guide*. ## Sharing a backup When you share a backup with other AWS accounts, you enable them to restore clusters from the backup which contain the keys and users stored in the backup. To share a backup, you must add it to a resource share. A resource share is an AWS RAM resource that lets you share your resources across AWS accounts. A resource share specifies the resources to share, and the consumers with whom they are shared. When you share a backup using the CloudHSM console, you add it to an existing resource share. To add the backup to a new resource share, you must first create the resource share using the [AWS RAM console](https://console.aws.amazon.com/ram). If you are part of an organization in AWS Organizations and sharing within your organization is enabled, consumers in your organization are automatically granted access to the shared backup. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared backup after accepting the invitation. You can share a backup that you own using the AWS RAM console or AWS CLI. **To share a backup that you own using the AWS RAM console** See [Creating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*. **To share a backup that you own (AWS RAM command)** Use the [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command. **To share a backup that you own (CloudHSM command)** **Important** While you can share a backup using the CloudHSM PutResourcePolicy operation, we recommend using AWS Resource Access Manager (AWS RAM) instead. Using AWS RAM provides multiple benefits as it creates the policy for you, allows multiple resources to be shared at one time, and increases the discoverability of shared resources. If you use PutResourcePolicy and want consumers to be able to describe the backups you shared with them, you must promote the backup to a standard AWS RAM Resource Share using the AWS RAM PromoteResourceShareCreatedFromPolicy API operation. Use the [put-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/put-resource-policy.html) command. 1. Create a file named `policy.json` and copy the following policy into it. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal": { "AWS":"111122223333" }, "Action":[ "cloudhsm:CreateCluster", "cloudhsm:DescribeBackups" ], "Resource":"arn:aws:cloudhsm:us-west-2:111122223333:backup/backup-to-share" } ] } ``` ------ 1. Update `policy.json` with the backup ARN and identifiers to share it with. The following example grants read-only access to the root user for the AWS account identified by 123456789012. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal": { "AWS": [ "123456789012" ] }, "Action": [ "cloudhsm:CreateCluster", "cloudhsm:DescribeBackups" ], "Resource":"arn:aws:cloudhsm:us-west-2:123456789012:backup/backup-123" } ] } ``` ------ **Important** You can only grant permissions to DescribeBackups at the account level. When you share a backup with another customer, any principal that has DescribeBackups permission in that account can describe the backup. 1. Run the [put-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/put-resource-policy.html) command. ``` $ aws cloudhsmv2 put-resource-policy --resource-arn --policy file://policy.json ``` **Note** At this point, the consumer can use the backup but it will not show up in the DescribeBackups response with the shared parameter. The next steps describe how to promote the AWS RAM resource share in order for the backup to be included in the response. 1. Get the AWS RAM resource share ARN. ``` $ aws ram list-resources --resource-owner SELF --resource-arns ``` This returns a response similar to this: ``` { "resources": [ { "arn": "", "type": "", "resourceShareArn": "", "creationTime": "", "lastUpdatedTime": "" } ] } ``` From the response, copy the ** value to use in the next steps. 1. Run the AWS RAM [promote-resource-share-created-from-policy](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html) command. ``` $ aws ram promote-resource-share-created-from-policy --resource-share-arn ``` 1. To validate that the resource share has been promoted, you can run the AWS RAM [get-resource-shares ](https://docs.aws.amazon.com/cli/latest/reference/ram/get-resource-shares.html)command. ``` $ aws ram get-resource-shares --resource-owner SELF --resource-share-arns ``` When the policy has been promoted, the `featureSet` listed in the response is `STANDARD`. This also means the backup can be described by the new accounts in the policy. ## Unsharing a shared backup When you unshare a resource, the consumer may no longer use it to restore a cluster. Consumers will still be able to access any clusters that they restored from the shared backup. To unshare a shared backup that you own, you must remove it from the resource share. You can do this using the AWS RAM console or AWS CLI. **To unshare a shared backup that you own using the AWS RAM console** See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*. **To unshare a shared backup that you own (AWS RAM command)** Use the [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command. **To unshare a shared backup that you own (CloudHSM command)** Use the [delete-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/delete-resource-policy.html) command. ``` $ aws cloudhsmv2 delete-resource-policy --resource-arn ``` ## Identifying a shared backup Consumers can identify a backup shared with them using the CloudHSM console and AWS CLI. **To identify backups shared with you using the CloudHSM 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. In the navigation pane, choose **Backups**. 1. In the table, choose the **Shared backups** tab. **To identify backups shared with you using the AWS CLI** Use the [describe-backups](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-backups.html) command with the `--shared` parameter to return the backups that are shared with you. ## Permissions for shared backups ### Permissions for owners Backup owners can describe and manage a shared backup as well as use it to restore a cluster. ### Permissions for consumers Backup consumers cannot modify a shared backup, but they can describe it and use it to restore a cluster. ## Billing and metering There are no additional charges for sharing backups.