Create VSS snapshots with Amazon Systems Manager command documents - Amazon Elastic Compute Cloud
Parameters for Systems Manager VSS snapshot documentsRun Systems Manager VSS snapshot command documents
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create VSS snapshots with Amazon Systems Manager command documents

You can use Amazon Systems Manager command documents to create VSS-enabled snapshots. The following content introduces the command documents that are available, and the runtime parameters that the documents use to create your snapshots.

Before you use any of the Systems Manager command documents, ensure that you've met all Prerequisites.

Parameters for Systems Manager VSS snapshot documents

The Systems Manager documents that create VSS snapshots all use the following parameters, except where noted:

ExcludeBootVolume (string, optional)

This setting excludes boot volumes from the backup process if you create snapshots. To exclude boot volumes from your snapshots, set ExcludeBootVolume to True, and CreateAmi to False.

If you create an AMI for your backup, this parameter should be set to False. The default value for this parameter is False.

NoWriters (string, optional)

To exclude application VSS writers from the snapshot process, set this parameter to True. Excluding application VSS writers can help you resolve conflicts with third-party VSS backup components. The default value for this parameter is False.

CopyOnly (string, optional)

If you use the native SQL Server backup in addition to Amazon VSS, performing a Copy-only backup prevents Amazon VSS from breaking the native differential backup chain. To perform a Copy-only backup operation, set this parameter to True.

The default value for this parameter is False, which causes Amazon VSS to perform a full backup operation.

CreateAmi (string, optional)

To create a VSS-enabled Amazon Machine Image (AMI) to back up your instance, set this parameter to True. The default value for this parameter is False, which backs up your instance with an EBS snapshot instead.

For more information about creating an AMI from an instance, see Create a Windows AMI from a running instance.

AmiName (string, optional)

If the CreateAmi option is set to True, specify the name of the AMI that the backup creates.

description (string, optional)

Specify a description for the snapshots or image that this process creates.

tags (string, optional)

We recommend that you tag your snapshots and images to help you locate and manage your resources, for example, to restore volumes from a list of snapshots. The system adds the Name key, with a blank value where you can specify the name that you want to apply to your output snapshots or images.

If you want to specify additional tags, separate tags with a semicolon in between. For example, Key=Environment,Value=Test;Key=User,Value=TestUser1.

By default, the system adds the following reserved tags for VSS-enabled snapshots and images.

  • Device – For VSS-enabled snapshots, this is the device name of the EBS volume that the snapshot captures.

  • AppConsistent – This tag indicates the successful creation of a VSS-enabled snapshot or AMI.

  • AwsVssConfig – This identifies snapshots and AMIs that are created with VSS enabled. The tag includes meta information such as the AwsVssComponents version.

Warning

Specifying any of these reserved tags in your parameter list will cause an error.

executionTimeout (string, optional)

Specify the maximum time in seconds to run the snapshot creation process on the instance, or to create an AMI from the instance. Increasing this timeout allows the command to wait longer for VSS to start its freeze and complete tagging of the resources it creates. This timeout only applies to the snapshot or AMI creation steps. The initial step to install or update the AwsVssComponents package is not included in the timeout.

CollectDiagnosticLogs (string, optional)

To collect more information during snapshot and AMI creation steps, set this parameter to True. The default value for this parameter is False.

VssVersion (string, optional)

For the AWSEC2-VssInstallAndSnapshot document only, you can specify the VssVersion parameter to install a specific version of AwsVssComponents package on your instance. Leave this parameter blank to install the recommended default version.

If the specified version of the AwsVssComponents package is already installed, the script skips the install step and moves on to the backup step. For a list of AwsVssComponents package versions and operating support, see Amazon VSS solution version history.

Run Systems Manager VSS snapshot command documents

You can create VSS-enabled EBS snapshots with Amazon Systems Manager command documents as follows.

When you use Amazon Systems Manager to run the AWSEC2-VssInstallAndSnapshot document, the script runs the following steps.

  1. The script first installs or updates the AwsVssComponents package on your instance, depending on whether it's already installed.

  2. The script creates the application-consistent snapshots after the first step completes.

To run the AWSEC2-VssInstallAndSnapshot document, follow the steps for your preferred environment.

Console
Create VSS-enabled EBS snapshots from the console

  1. Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.

  2. Select Run Command from the navigation pane. This shows a list of commands that are currently running in your account, if applicable.

  3. Choose Run command. This opens a list of command documents that you have access to.

  4. Select AWSEC2-VssInstallAndSnapshot from the list of command documents. To streamline results, you can enter all or part of the document name. You can also filter by the owner, by platform types, or by tags.

    When you select a command document, details populate below the list.

  5. Select Default version at runtime from the Document version list.

  6. Configure the Command parameters to define how AWSEC2-VssInstallAndSnapshot will install the AwsVssComponents package and back up with VSS snapshots or an AMI. For parameter details, see Parameters for Systems Manager VSS snapshot documents.

  7. For Target selection, specify tags or select instances manually to identify the instances on which to run this operation.

    Note

    If you select instances manually, and an instance you expect to see is not included in the list, see Where Are My Instances? for troubleshooting tips.

  8. For additional parameters to define Systems Manager Run Command behavior such as Rate control, enter values as described in Running commands from the console.

  9. Choose Run.

    If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the Systems Manager command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes.

Amazon CLI

You can run the following commands in the Amazon CLI to create VSS-enabled EBS snapshots and get the status of your snapshot creation.

Create VSS-enabled EBS snapshots

Run the following command to create VSS-enabled EBS snapshots. To create the snapshots, you must identify the instances with the --instance-ids parameter. For more information about other parameters that you can use, see Parameters for Systems Manager VSS snapshot documents.

aws ssm send-command \
	--document-name "AWSEC2-VssInstallAndSnapshot" \
	--instance-ids "i-01234567890abcdef" \
	--parameters '{"ExcludeBootVolume":["False"],"description":["Description"],"tags":["Key=key_name,Value=tag_value"],"VssVersion":[""]}'

If successful, the command document populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed.

Get command status

To get the current status of the snapshots, run the following command using the command ID returned from send-command.

aws ssm get-command-invocation
	--instance-ids "i-01234567890abcdef" \
	--command-id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" \
	--plugin-name "CreateVssSnapshot"
PowerShell

Run the following commands with Amazon Tools for Windows PowerShell to create VSS-enabled EBS snapshots and get the current runtime status for the creation of your output. Specify parameters described in the prior list to modify the behavior of the snapshot process.

Create VSS-enabled EBS snapshots with Tools for Windows PowerShell

Run the following command to create VSS-enabled EBS snapshots or AMIs.

Send-SSMCommand -DocumentName "AWSEC2-VssInstallAndSnapshot" -InstanceId "i-01234567890abcdef" -Parameter @{'ExcludeBootVolume'='False';'description'='a_description'
	;'tags'='Key=key_name,Value=tag_value';'VssVersion'=''}
Get command status

To get the current status of the snapshots, run the following command using the command ID returned from Send-SSMCommand.

Get-SSMCommandInvocationDetail -InstanceId "i-01234567890abcdef" -CommandId "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" -PluginName "CreateVssSnapshot"

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed.

To run the AWSEC2-CreateVssSnapshot document, follow the steps for your preferred environment.

Console
Create VSS-enabled EBS snapshots from the console

  1. Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.

  2. Select Run Command from the navigation pane. This shows a list of commands that are currently running in your account, if applicable.

  3. Choose Run command. This opens a list of command documents that you have access to.

  4. Select AWSEC2-CreateVssSnapshot from the list of command documents. To streamline results, you can enter all or part of the document name. You can also filter by the owner, by platform types, or by tags.

    When you select a command document, details populate below the list.

  5. Select Default version at runtime from the Document version list.

  6. Configure the Command parameters to define how AWSEC2-CreateVssSnapshot will back up with VSS snapshots or an AMI. For parameter details, see Parameters for Systems Manager VSS snapshot documents.

  7. For Target selection, specify tags or select instances manually to identify the instances on which to run this operation.

    Note

    If you select instances manually, and an instance you expect to see is not included in the list, see Where Are My Instances? for troubleshooting tips.

  8. For additional parameters to define Systems Manager Run Command behavior such as Rate control, enter values as described in Running commands from the console.

  9. Choose Run.

    If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the Systems Manager command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes.

Amazon CLI

You can run the following command in the Amazon CLI to create VSS-enabled EBS snapshots.

Create VSS-enabled EBS snapshots

Run the following command to create VSS-enabled EBS snapshots. To create the snapshots, you must identify the instances with the --instance-ids parameter. For more information about other parameters that you can use, see Parameters for Systems Manager VSS snapshot documents.

aws ssm send-command \
	--document-name "AWSEC2-CreateVssSnapshot" \
	--instance-ids "i-01234567890abcdef" \
	--parameters '{"ExcludeBootVolume":["False"],"description":["Description"],"tags":["Key=key_name,Value=tag_value"]}'

If successful, the command document populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed.

PowerShell

Run the following command with Amazon Tools for Windows PowerShell to create VSS-enabled EBS snapshots.

Create VSS-enabled EBS snapshots with Tools for Windows PowerShell

Run the following command to create VSS-enabled EBS snapshots. To create the snapshots, you must identify the instances with the InstanceId parameter. You can specify more than one instance to create snapshots for. For more information about other parameters that you can use, see Parameters for Systems Manager VSS snapshot documents.

Send-SSMCommand -DocumentName AWSEC2-CreateVssSnapshot -InstanceId "i-01234567890abcdef" -Parameter @{'ExcludeBootVolume'='False';'description'='a_description'
	;'tags'='Key=key_name,Value=tag_value'}

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS snapshots.

You can use any of the command line procedures described in the previous section to create a VSS-enabled snapshot. The command document (AWSEC2-VssInstallAndSnapshot or AWSEC2-CreateVssSnapshot) must run on the primary node in your cluster. The document will fail on the secondary nodes as they don't have access to the shared disks. If your primary and secondary change dynamically, you can run the Amazon Systems Manager Run Command document on multiple nodes with the expectation that the command will succeed on the primary node and fail on secondary nodes.

You can use the following script and the pre-defined AWSEC2-ManageVssIO SSM document to temporarily pause I/O, create VSS-enabled EBS snapshots, and restart I/O. This process runs in the context of the user who runs the command. If the user has sufficient permission to create and tag snapshots, then Amazon Systems Manager can create and tag VSS-enabled EBS snapshots without the need for the additional IAM snapshot role on the instance.

In contrast, the command document (AWSEC2-VssInstallAndSnapshot or AWSEC2-CreateVssSnapshot) requires that you assign the IAM snapshot role to each instance for which you want to create EBS snapshots. If you don’t want to provide additional IAM permissions to your instances for policy or compliance reasons, then you can use the following script.

Before you begin

Note the following important details about this process:

  • This process uses a PowerShell script (CreateVssSnapshotAdvancedScript.ps1) to take snapshots of all volumes on the instances you specify, except root volumes. If you need to take snapshots of root volumes, then you must use the AWSEC2-CreateVssSnapshot SSM document.

  • The script calls the AWSEC2-ManageVssIO document twice. The first time with the Action parameter set to Freeze, which pauses all I/O on the instances. The second time, the Action parameter is set to Thaw, which forces I/O to resume.

  • Don't attempt to use the AWSEC2-ManageVssIO document without using the CreateVssSnapshotAdvancedScript.ps1 script. Microsoft's VSS framework requires that the Freeze and Thaw actions be called no more than ten seconds apart, and manually calling these actions without the script could result in errors.

To create VSS-enabled EBS snapshots by using the AWSEC2-ManageVssIO SSM document

  1. Download the CreateVssSnapshotAdvancedScript.zip file and extract the file contents.

  2. Open CreateVssSnapshotAdvancedScript.ps1 in a text editor, edit the sample call at the bottom of the script with a valid EC2 instance ID, snapshot description, and desired tag values, and then run the script from PowerShell.

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed. If the command was successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes.

Note

To automate backups, you can create an Amazon Systems Manager maintenance window task that uses the AWSEC2-VssInstallAndSnapshot document. For more information, see Working with Maintenance Windows (Console) in the Amazon Systems Manager User Guide.