Other use cases for Data Lifecycle Manager pre and post scripts
In addition to using pre and post scripts for automating application-consistent snapshots, you can use pre and post scripts together, or individually, to automate other administrative tasks before or after snapshot creation. For example:
-
Using a pre script to apply patches before creating snapshots. This can help you create snapshots after applying your regular weekly or monthly software updates.
Note
If you choose to run a pre script only, Default to crash-consistent snapshots is enabled by default.
-
Using a post script to apply patches after creating snapshots. This can help you create snapshots before applying your regular weekly or monthly software updates.
Getting started for other use cases
This section explains the steps you need perform when using pre and/or post scripts for uses cases other than application-consistent snapshots.
To prepare your target instances for pre and/or post scripts
-
Install the SSM Agent on your target instances, if it is not already installed. If SSM Agent is already installed on your target instances, skip this step.
-
(Linux instances) Manually installing SSM Agent on Amazon EC2 instances for Linux
-
(Windows instances) Manually installing SSM Agent on Amazon EC2 instances for Windows
-
-
Ensure that the SSM Agent is running. For more information, see Checking SSM Agent status and starting the agent.
-
Set up Systems Manager for Amazon EC2 instances. For more information, see Setting up Systems Manager for Amazon EC2 instances in the AWS Systems Manager User Guide.
You must create an SSM command document that includes the pre and/or post scripts with the commands you want to run.
You can create an SSM document using the empty SSM document template below and add your pre and post script commands in the appropriate document sections.
Note the following:
-
It is your responsibility to ensure that the SSM document performs the correct and required actions for your workload.
-
The SSM document must include required fields for
allowedValues
, includingpre-script
,post-script
, anddry-run
. Amazon Data Lifecycle Manager will execute commands on your instance based on the contents of those sections. If your SSM document does not have those sections, then Amazon Data Lifecycle Manager will treat it as a failed execution.
###===============================================================================### # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ###===============================================================================### schemaVersion: '2.2' description: SSM Document Template for Amazon Data Lifecycle Manager Pre/Post script feature parameters: executionId: type: String default: None description: (Required) Specifies the unique identifier associated with a pre and/or post execution allowedPattern: ^(None|[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$ command: # Data Lifecycle Manager will trigger the pre-script and post-script actions during policy execution. # 'dry-run' option is intended for validating the document execution without triggering any commands # on the instance. The following allowedValues will allow Data Lifecycle Manager to successfully # trigger pre and post script actions. type: String default: 'dry-run' description: (Required) Specifies whether pre-script and/or post-script should be executed. allowedValues: - pre-script - post-script - dry-run mainSteps: - action: aws:runShellScript description: Run Database freeze/thaw commands name: run_pre_post_scripts precondition: StringEquals: - platformType - Linux inputs: runCommand: - | #!/bin/bash ###===============================================================================### ### Error Codes ###===============================================================================### # The following Error codes will inform Data Lifecycle Manager of the type of error # and help guide handling of the error. # The Error code will also be emitted via AWS Eventbridge events in the 'cause' field. # 1 Pre-script failed during execution - 201 # 2 Post-script failed during execution - 202 # 3 Auto thaw occurred before post-script was initiated - 203 # 4 Pre-script initiated while post-script was expected - 204 # 5 Post-script initiated while pre-script was expected - 205 # 6 Application not ready for pre or post-script initiation - 206 ###===============================================================================### ### Global variables ###===============================================================================### START=$(date +%s) # For testing this script locally, replace the below with OPERATION=$1. OPERATION={{ command }} # Add all pre-script actions to be performed within the function below execute_pre_script() { echo "INFO: Start execution of pre-script" } # Add all post-script actions to be performed within the function below execute_post_script() { echo "INFO: Start execution of post-script" } # Debug logging for parameters passed to the SSM document echo "INFO: ${OPERATION} starting at $(date) with executionId: ${EXECUTION_ID}" # Based on the command parameter value execute the function that supports # pre-script/post-script operation case ${OPERATION} in pre-script) execute_pre_script ;; post-script) execute_post_script ;; dry-run) echo "INFO: dry-run option invoked - taking no action" ;; *) echo "ERROR: Invalid command parameter passed. Please use either pre-script, post-script, dry-run." exit 1 # return failure ;; esac END=$(date +%s) # Debug Log for profiling the script time echo "INFO: ${OPERATION} completed at $(date). Total runtime: $((${END} - ${START})) seconds."
Note
This step is needed if:
-
You create or update a pre/post script-enabled snapshot policy that uses a custom IAM role.
-
You use the command line to create or update a pre/post script-enabled snapshot policy that uses the default.
If you use the console to create or update a pre/post script-enabled snapshot policy that uses the default role for managing snapshots (AWSDataLifecycleManagerDefaultRole), skip this step. In this case, we automatically attach the AWSDataLifecycleManagerSSMFullAccess policy to that role.
You must ensure that that IAM role that you use for the policy grants Amazon Data Lifecycle Manager permission to perform the SSM actions required to run pre and post scripts on instances targeted by the policy.
Amazon Data Lifecycle Manager provides a managed policy (AWSDataLifecycleManagerSSMFullAccess) that includes the required permissions. You can attach this policy to your IAM role for managing snapshots to ensure that it includes the permissions.
Important
The AWSDataLifecycleManagerSSMFullAccess managed policy uses the aws:ResourceTag
condition key to restrict access to specific SSM documents when using pre and post scripts.
To allow Amazon Data Lifecycle Manager to access the SSM documents, you must ensure that your SSM documents
are tagged with DLMScriptsAccess:true
.
Alternatively, you can manually create a custom policy or assign the required
permissions directly to the IAM role that you use. You can use the same permissions
that are defined in the AWSDataLifecycleManagerSSMFullAccess managed policy, however,
the aws:ResourceTag
condition key is optional. If you decide to not
use that condition key, then you do not need to tag your SSM documents with
DLMScriptsAccess:true
.
Use one of the following methods to add the AWSDataLifecycleManagerSSMFullAccess policy to your IAM role.