# Use an automation runbook to restore your database from AWS VSS solution snapshots VSS based database restore with automation runbook This guide explains how to use the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook to restore a Microsoft SQL Server database running on an EC2 instance from application-consistent snapshots created by the AWS VSS solution. You can tailor the restoration parameters to your specific needs, such as setting the database to restore mode after restoration. By leveraging Windows VSS technology, this solution offers the following advantages: + Fast restoration times. + The ability to perform the restore without shutting down or pausing the Microsoft SQL Server application. For more information about the AWS VSS solution, see [Application consistent Windows VSS based Amazon EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/application-consistent-snapshots.html) in the *Amazon EC2 User Guide*. **Topics** + [ ## Pricing ](#ms-ssdb-ec2-vss-restore-pricing) + [ ## VSS based database restore solution change history ](#ms-ssdb-ec2-vss-restore-history) + [ # VSS snapshot restore prerequisites ](ms-ssdb-ec2-vss-restore-prereq.md) + [ # Restore your SQL Server database from VSS snapshots ](ms-ssdb-ec2-vss-restore-from-snap.md) ## Pricing The AWS VSS solution uses AWS Systems Manager automation runbooks with EBS resources to restore a Microsoft SQL Server database on an EC2 instance. Associated costs include the following: **Systems Manager Automation** With Systems Manager automation runbooks, you pay only for what you use and are charged based on the number and duration of steps, which includes a free tier per account. If you created an organization, your free tier usage is shared across all accounts in the Consolidated Billing family. For more information about Systems Manager automation pricing, see [Automation](https://aws.amazon.com/systems-manager/pricing/#Automation). **Amazon EBS** During restore steps, the AWS VSS solution creates a new EBS volume and restores data from VSS based EBS snapshots. With Amazon EBS resources, you pay only for what you provision. For more information, see [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). ## VSS based database restore solution change history The following table includes release and change history for the AWS VSS restore solution. | Release date | Details | | --- | --- | | January 14, 2026 | Enhanced restore solution to create new Amazon EBS volumes only from snapshots that contain source database files to be restored, reducing cleanup overhead and improving the overall reliability of restore operations. | | April 22, 2025 | Fixed an issue where the restore process times out when disk partition information is not available, improving reliability of restore operations. | | January 24, 2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sql-server-ec2/latest/userguide/ms-ssdb-ec2-restore-vss.html) | | January 15, 2025 | Initial release of the VSS restore solution. | # VSS snapshot restore prerequisites Prerequisites To restore your SQL Server databases from AWS VSS solution based EBS snapshots, you must meet the following prerequisites. **Note** The `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook only supports restoring snapshots to the original EC2 instance where the snapshots were created. + **Disk management configuration** – Your EC2 database instance must be configured with Basic Disks. For more information, see [Basic Disks](https://learn.microsoft.com/en-us/windows/win32/fileio/basic-and-dynamic-disks#basic-disks) on the *Microsoft Learn* website. + **Microsoft SQL Server deployment options** – To restore a SQL Server database with the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook, the database must either be configured as a standalone deployment, or be the primary database in a Microsoft SQL Server Always On availability group. For more information, see [Deployment options](create-sql-server-on-ec2-instance.md#create-sql-server-deployment-options). + **Configure settings to save VSS metadata files** – To successfully initiate a restore operation, VSS metadata files are required. The following files are generated for each snapshot set taken during the snapshotting process. + `{Snapshot set id}-{timestamp}-BCD.xml` + `{Snapshot set id}-{timestamp}-SqlServerWriter.xml` + `{Snapshot set id}-{timestamp}-VolumeMapping.json` **Note** The volume mapping metadata file (`{Snapshot set id}-{timestamp}-VolumeMapping.json`) maps Windows drives to their corresponding snapshots and is used in VSS restore operations to create EBS volumes from snapshots that contains database files to be restored. To ensure that these files are generated, set the `SaveVssMetadata` parameter to `true` when you run the command document. + [Grant IAM permissions for the restore process](#ms-ssdb-ec2-vss-restore-iam). ## Grant IAM permissions for the restore process Executing the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook to restore databases needs permissions to perform necessary Amazon EC2 and Systems Manager operations. Follow these steps to grant the appropriate permissions. 1. [Attach the AWSEC2VssRestorePolicy managed policy to the role that's used for the automation execution](#ms-ssdb-ec2-vss-restore-iam-policy-attach). 1. [Grant IAM permissions to the invoker role for starting and managing automation executions](#ms-ssdb-ec2-vss-restore-iam-policy-add). ### Attach the AWSEC2VssRestorePolicy managed policy to the role that's used for the automation execution You can choose from the following options to attach the **AWSEC2VssRestorePolicy** AWS managed policy to the role that Systems Manager uses for interacting with Amazon EC2 and Systems Manager when executing the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook. For more information about this managed policy, see [AWSEC2VssRestorePolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSEC2VssRestorePolicy). + Create a role, attach the **AWSEC2VssRestorePolicy** managed policy, and add a PassRole policy to restrict access. Use the ARN of this role for the `AutomationAssumeRole` parameter when invoking the automation, and the automation execution will assume this role. Expand the `Invoke automation with an assumed role (recommended)` section to see detailed steps. + Attach the **AWSEC2VssRestorePolicy** managed policy to the invoker role that initiates the automation execution, without specifying the `AutomationAssumeRole` parameter. For example, if you start the automation execution from the AWS console, the console role acts as the invoker role. Expand the `Invoke automation without an assumed role` section to see detailed steps. ### Invoke automation with an assumed role (recommended) **Step 1: Create the role that the automation assumes and attach your policy** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose `Roles`, and then choose **Create role**. This opens the **Select trusted entity** page. 1. In the **Trusted entity type** panel, choose **AWS service**. This is the default selection. 1. In the **Use case** panel, select **Systems Manager** from the list, and then choose **Next**. This opens the **Add permissions** page. 1. Search for **AWSEC2VssRestorePolicy**. Select the check box next to the name and then choose **Next**. This takes you to the **Name, review, and create** page. 1. In the **Role details** panel, enter **Role name** and **Description**. 1. When you've finished reviewing, choose **Create role**. This takes you back to the **Roles** page. 1. Open the detail page for the role that you just created. Take note of the **Role Name** at the top for future reference. Copy the **Role ARN** from the **Summary** panel to use in the next steps, then continue to Step 2 to create a PassRole policy for your role. **Step 2: Create an inline policy to pass the role that the automation assumes** 1. In the detail page for the role that you just created, choose the **Permissions** tab. 1. Choose **Add inline policy** from the **Add permissions** menu. This opens the **Specify permissions** page. 1. Select the **Visual** policy editor. 1. Choose **IAM** from the **Service** list. 1. In the **Actions allowed** search box, enter `PassRole`, then select the **PassRole** check box. 1. The **Resources** panel opens with the **Specific** option selected by default. Select the **Add ARNs** link to open a panel where you can specify the ARN for your role. 1. In the **Resource ARN** box, paste the ARN that you copied at the end of Step 1. IAM automatically populates the role name based on the ARN. 1. Choose Add ARNs to save your resource ARN. This takes you back to the **Specify permissions** page, and shows your entry. 1. Choose **Next** to review your policy. This opens the **Review and create** page. 1. On the Review Policy page, enter a name (for example, `VssRestorePassRolePolicy`) and then choose **Next** to create the PassRole policy for your role. ### Invoke automation without an assumed role 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**, and then select the role that will be used to start the automation execution. For example, if you will start the automation execution from console, you should choose the current console role, which appears in the upper right corner of the console: ``` role/user @ account ``` 1. In the **Permissions** tab, choose **Attach policies** from the **Add permissions** menu. This opens the **Attach policy to ** page. 1. Use the search bar in the **Other permissions policies** panel to search for **AWSEC2VssRestorePolicy**. Select the check box next to the name and then choose **Add permissions**. ### Grant IAM permissions to the invoker role for starting and managing automation executions To attach necessary permissions to the role that starts and manages the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation executions, follow these steps. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**, and then select the role that will be used to start the automation execution. 1. Choose **Add inline policy** from the **Add permissions** menu. This opens the **Specify permissions** page. 1. Select the **JSON** policy editor and copy the following JSON policy content into the editor. The policy allows the role to: + Execute the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook. + Stop and send signals to an automation execution. + View details about the automation execution after it has been started. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StartVssRestoreAutomationExecution", "Effect": "Allow", "Action": "ssm:StartAutomationExecution", "Resource": [ "arn:aws:ssm:*:*:document/AWSEC2-RestoreSqlServerDatabaseWithVss", "arn:aws:ssm:*:*:automation-execution/*" ] }, { "Sid": "ManageVssRestoreAutomationExecution", "Effect": "Allow", "Action": [ "ssm:StopAutomationExecution", "ssm:GetAutomationExecution", "ssm:DescribeAutomationExecutions", "ssm:DescribeAutomationStepExecutions", "ssm:SendAutomationSignal" ], "Resource": [ "arn:aws:ssm:*:*:automation-execution/*" ] } ] } ``` ------ 1. If you are to start the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation with an assume role by providing a role arn to the `AutomationAssumeRole` parameter, you will need to add the following permission to the above policy statements, and replace the `[AutomationAssumeRole's ARN]` placeholder with the ARN of the role created in step `Invoke runbook automation with an assumed role (recommended)`. The permission allows the invoker role to pass the automation assume role to Systems Manager. ``` { "Action": "iam:PassRole", "Effect": "Allow", "Resource": [ "[AutomationAssumeRole's ARN]" ] } ``` 1. Choose **Next** to review your policy. This opens the review and create page. 1. On the **Review Policy** page, enter a name (for example, `VssRestoreRunSSMAutomationPolicy`) and then choose **Next** to create and add the inline policy to your role. # Restore your SQL Server database from VSS snapshots Restore from VSS snapshots The `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook provides a streamlined process to restore your SQL Server databases. This guide outlines the automation runbook functionality and explains the parameters that you can customize to suit your specific restoration needs. Before you run the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook, ensure that you've met all prerequisites to create application consistent snapshots with the AWS VSS solution. For more information, see [Prerequisites to create Windows VSS based EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/application-consistent-snapshots-prereqs.html) in the *Amazon EC2 User Guide*. The `AWSEC2-RestoreSqlServerDatabaseWithVss` process consists of several key steps, as follows. 1. The first step uses `AWS-ConfigureAwsPackage` to upgrade or install the latest version of the `AwsVssComponents` component package. 1. The next step invokes `AWSEC2-PrepareVssRestore` to verify that prerequisites are met and that the input parameters include a valid value for the VSS Snapshot Set ID and Source Database Name. 1. The process then creates new EBS volumes from the snapshots and attaches them to the instance. 1. Finally, the process invokes `AWSEC2-RunVssRestoreForSqlDatabase`, which runs the Amazon EC2 VSS Agent to restore the database on the instance, and returns volume IDs and their usage status by the restored database, the final restore operation status, and Amazon EC2 VSS Agent logs. ## Parameters for the SQL Server database restore runbook Runbook parameters The `AWSEC2-RestoreSqlServerDatabaseWithVss` automation runbook uses the following input parameters: **Note** You can provide one of the following parameters to use a specific snapshot: `SnapshotSetId` `RestorePointOfTime` If both parameters are empty, the restore uses the most recent snapshot set. **InstanceId** (string, required) The ID of the Amazon EC2 instance where the restore is performed. **SourceDatabaseName** (string, required) The name of the database that's included in the snapshots. **TargetDatabaseName** (string, optional) The restore process creates a new database, and restores the data from the snapshots to the new database from the snapshots. You can optionally set the name, or leave this parameter empty to use the default name for the new database (`Db_Restored`). The old database files are removed from the volume after the process completes. **SnapshotSetId** (string, optional) The Snapshot Set ID of the snapshot to use for recovery. **RestorePointOfTime** (string, optional) If this parameter is specified, the restore process uses the last Snapshot Set that was created before the provided point in time value. This parameter uses the following string format: **MM-dd-yyyy:hh-mm**. **RestoreWithNorecovery** (string, required) If this parameter is set to `True` the restore process leaves the database in restoring state so that you can apply transaction logs after the database restore is completed. To bring the database online immediately after the restore is completed, set this parameter to `False`. **MetadataPath** (string, optional) The fully qualified path to the directory where the VSS metadata files are stored. If not specified, the system uses the following default location, where metadata files are automatically saved during snapshot operations. Use this parameter to indicate a custom storage location if you've relocated the files. `%PROGRAMDATA%\Amazon\AwsVss\VssMetadata`. **AutomationAssumeRole** (string, conditional) The ARN of the IAM role that the automation assumes during execution. If not specified, the automation uses the IAM role that initiated the execution. For example, when starting the automation from the AWS Console without specifying this parameter, the automation uses your current console session's IAM role to interact with Amazon EC2 and SSM. **ExecutionTimeout** (string, optional) The amount of time, in seconds, that the `RunVssRestoreForSqlDatabase` step can run before it fails. If this value is not specified, the default timeout is 600 seconds. ## Run the SQL Server database restore process Run the restore process 1. **Always On databases: Remove the source database from the SQL Server availability group** If your database is the primary database in an Always On availability group, you must remove the database from the availability group before you run the restore process. 1. To remove the database from the availability group, follow the steps described in [Remove a primary database from an Always On availability group](https://learn.microsoft.com/en-us/sql/database-engine/availability-groups/windows/remove-a-primary-database-from-an-availability-group-sql-server?view=sql-server-ver16) on the *Microsoft Learn* website. 1. Verify that the database remains online, and is not in a `Synchronized` state. 1. **Execute AWSEC2-RestoreSqlServerDatabaseWithVss Automation Runbook** To view instructions, select the tab that matches your environment. ------ #### [ AWS Management Console ] To run the restore in the AWS Management Console, follow these steps: 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. Select **Automation** from the navigation pane, under **Change Management Tools**. This shows a list of automation executions in your account, if applicable. 1. Choose **Execute automation**. This opens the **Choose runbook** page. 1. In the **Owned by Amazon** tab, search for `AWSEC2-RestoreSqlServerDatabaseWithVss`, and select it from the results. This opens the **Runbook details** panel. 1. Select **Default version at runtime** from the **Runbook version** list. 1. Choose **Next**. This opens the page where you can configure the settings and enter input parameters for the runbook. 1. Enter values for the **Input parameters** to configure runtime settings for the restore process. For parameter details, see [Parameters for the SQL Server database restore runbook](#ms-ssdb-ec2-vss-restore-params). 1. Choose **Execute** to run the automation. To review the execution status, navigate to the **Executed Steps** section within the automation execution details. This section displays all of the steps that ran, along with their runtime status. If the automation execution failed, follow the troubleshooting steps outlined in [ Troubleshoot restoring your SQL Server database from AWS VSS solution snapshots using the Systems Manager consoleTroubleshoot restoring your SQL Server database using AWS VSS solution Before you try any troubleshooting steps, we recommend that you verify that you've met all [VSS snapshot restore prerequisites](ms-ssdb-ec2-vss-restore-prereq.md). In the Systems Manager console, the **Failure details** section in the automation runbook **Execution Details** page includes the following information: **Failure Message** **Failure Type** **Failure Stage** Together, these details offer a general overview of the cause of the failure. For a more comprehensive understanding, you must examine the specific step execution that failed. The steps in `AWSEC2-RestoreSqlServerDatabaseWithVss` can be classified into three main categories: **Script Execution Steps** These use the `aws:executeScript` action and include the following steps. + `ExtractPrepareVssRestoreOutput` + `PrepareForVolumeCreation` + `ExtractCurrIterValues` + `ConcatVolumeIds` If one of these steps fails, investigate the step execution and review the execution logs found under **OutputPayload** in the **Outputs** section to determine what caused the issue. **EC2 API Interaction Steps** These interact with Amazon EC2 APIs to create volumes from snapshots, attach them to instances, and monitor volume status. Many of these steps are performed within loop steps. If a loop step fails, identify the specific step within the loop that caused the failure to pinpoint the root cause. The **Failure details** section in the step execution details page provides relevant information for debugging. **Run Command Execution Steps** These use the `aws:RunCommand` action to execute commands on the target instance. If a failure occurs due to a run command execution, examine the step execution details. Under **Outputs**, select the **CommandId** link for the command to access the **Run command execution** page, where you can view the complete log for debugging purposes. ](#ms-ssdb-ec2-vss-restore-troubleshoot). + Locate the command execution ID in the step details. + Select the linked ID to access the execution details. + Inspect the command output and return code for further troubleshooting. ------ #### [ AWS CLI ] Run the following command to restore a Microsoft SQL Server database on an instance. Replace or add parameters based on your specific use case. For parameter details, see [Parameters for the SQL Server database restore runbook](#ms-ssdb-ec2-vss-restore-params). ``` aws ssm start-automation-execution \ --document-name "AWSEC2-RestoreSqlServerDatabaseWithVss" \ --parameters '{"InstanceId":"i-1234567890abcdef0","SourceDatabaseName":"DB_Source","TargetDatabaseName":"DB_Restored"}' ``` **Get execution status** To get the status of the automation execution, run the following command using the execution ID returned from `start-automation-execution`. ``` aws ssm get-automation-execution \ --automation-execution-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ``` ------ #### [ PowerShell ] Run the following PowerShell commands with AWS Tools for Windows PowerShell to restore a SQL Server database on an instance. Replace or add parameters based on your specific use case. For parameter details, see [Parameters for the SQL Server database restore runbook](#ms-ssdb-ec2-vss-restore-params). ``` Start-SSMAutomationExecution ` -DocumentName "AWSEC2-RestoreSqlServerDatabaseWithVss" ` -Parameter @{"InstanceId" = @($InstanceId); "SourceDatabaseName" = @("DB_Source"); "TargetDatabaseName" = @("DB_Restored"); "RestoreWithNorecovery" = @($True); "AutomationAssumeRole" = @("Arn:of:role")} ``` **Get execution status** To get the status of the automation execution and the status of each action step, run the following command using the execution ID returned from `Start-SSMAutomationExecution`. ``` Get-SSMAutomationExecution -AutomationExecutionId $ExecutionId | Select-Object -ExpandProperty StepExecutions | Select-Object -Property StepName, StepStatus | Out-String ``` ------ 1. **(Optional) Clean up unused EBS volumes after the automation execution succeeds** When volume mapping metadata is used, the `AWSEC2-RestoreSqlServerDatabaseWithVss` automation creates new EBS volumes only from volume snapshots that contain files of the database to be restored. However, when this metadata is not used, the automation creates a new EBS volume for each volume snapshot within the VSS snapshot set and attaches them to the target instance. To determine if volume mapping metadata was used for your database restore operation, check the automation execution steps. In the automation execution details, examine the `PrepareForVolumeCreation` step output. If `ExecutionLog` in the `OutputPayload` says `No volume mapping found - using all snapshots`, volume mapping metadata was not used during the restore operation. If volume mapping metadata was not used for your restore operation, follow these steps to identify and clean up volumes that don't contain restored database files: 1. In the **Execution detail** page, choose the **RunVssRestoreForSqlDatabase** step (this is the last step). 1. Choose the **CommandId** link in the **Outputs** section, and then choose the instance id to view the run command output. 1. At the end of the output is a list of all volumes created and attached to the instance for restore purposes, and the status for each one. The status is either `in-use` or `unused`. To detach and delete the volumes, see [Detach an Amazon EBS volume from an Amazon EC2 instance](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-detaching-volume.html) in the *Amazon EBS User Guide*. ## Troubleshoot restoring your SQL Server database from AWS VSS solution snapshots using the Systems Manager console Troubleshoot restoring your SQL Server database using AWS VSS solution Before you try any troubleshooting steps, we recommend that you verify that you've met all [VSS snapshot restore prerequisites](ms-ssdb-ec2-vss-restore-prereq.md). In the Systems Manager console, the **Failure details** section in the automation runbook **Execution Details** page includes the following information: + **Failure Message** + **Failure Type** + **Failure Stage** Together, these details offer a general overview of the cause of the failure. For a more comprehensive understanding, you must examine the specific step execution that failed. The steps in `AWSEC2-RestoreSqlServerDatabaseWithVss` can be classified into three main categories: **Script Execution Steps** These use the `aws:executeScript` action and include the following steps. + `ExtractPrepareVssRestoreOutput` + `PrepareForVolumeCreation` + `ExtractCurrIterValues` + `ConcatVolumeIds` If one of these steps fails, investigate the step execution and review the execution logs found under **OutputPayload** in the **Outputs** section to determine what caused the issue. **EC2 API Interaction Steps** These interact with Amazon EC2 APIs to create volumes from snapshots, attach them to instances, and monitor volume status. Many of these steps are performed within loop steps. If a loop step fails, identify the specific step within the loop that caused the failure to pinpoint the root cause. The **Failure details** section in the step execution details page provides relevant information for debugging. **Run Command Execution Steps** These use the `aws:RunCommand` action to execute commands on the target instance. If a failure occurs due to a run command execution, examine the step execution details. Under **Outputs**, select the **CommandId** link for the command to access the **Run command execution** page, where you can view the complete log for debugging purposes.