How-To
Working with AWS Systems Manager Documents
Perform automated actions against your AWS resources with SSM.
Amazon Web Services (AWS) provides a collection of preconfigured documents that you can use to perform automated actions against your AWS resources. These documents can be used for tasks ranging from terminating an Amazon Elastic Compute Cloud (EC2) instance to running Sysprep.
If you're using a Windows machine, you can see a list of the AWS Systems Manager (SSM) documents that AWS provides by opening PowerShell for AWS and entering the Get-SSMDocumentList cmdlet. You can see the cmdlet's results in Figure 1. Incidentally, if you aren't working from a Windows machine, you can access the document list by entering this command:
aws ssm list-documents
[Click on image for larger view.]
Figure 1. These are a few of the SSM documents that AWS provides.
As you look through the list of SSM documents, one of the first things that you might notice is that some of the document names do a fairly good job of describing what the document is used for, while the names of some of the other documents are a bit less clear. If you want to find out what a particular document does, you can query the document file to get a description (or you could just do a Web search on the document name). The command used to retrieve a document description looks something like this:
Aws ssn describe-document –name <document name> --query "[Document.Name,Document.Description]"
For example, if you wanted to find out more about the document named AWSEC2-RunSysprep, you could enter this command:
Aws ssn describe-document –name AWSEC2-RunSysprep --query "[Document.Name,Document.Description]"
As you can see in Figure 2, this command displays a description of the document's function.
[Click on image for larger view.]
Figure 2. You can perform a query to determine a document's function.
In case you're wondering, the document's description is actually embedded inside of the document file. Most of the document files are in JSON format (although YAML format is also supported). The document files contain a series of key/value pairs. The command that I used in Figure 2 displays the values associated with keys named Name and Description.
So what other information is contained within a document file? You can actually display the document's full contents by repeating the previous command, but omitting the query at the end of the command. For example, if you wanted to display the contents of the AWSEC2-RunSysprep document, you could do so by using this command:
Aws ssm describe-document –name AWSEC2-RunSysprep
You can see what the results look like in Figure 3. As you can see in the figure, this command displays things such as the document's version and its owner.
[Click on image for larger view.]
Figure 3. This is how you can display the full contents of an SSM document.
In the real world, if you're planning to use an SSM document to perform an automated action, you usually won't have to worry about displaying and then attempting to decipher the document's full contents. What you might need to do, however, is to determine which parameters need to be supplied with the document in order to perform the desired action. In the case of the AWSEC2-RunSysprep document, for example, the document will need to know which EC2 instance you want to Sysprep. Thankfully, there's a really easy way to get the list of required parameters.
If you want to see which parameters are supported by an SSM document, just enter the following command:
Aws ssm describe-document –name <document name> --query "Document.Parameters[*]"
You can see the document parameters for the AWSEC2-RunSysprep document in Figure 4.
[Click on image for larger view.]
Figure 4. This is how you retrieve a document's list of supported parameters.
In this case, the document requires the use of the name parameter, and also supports the use of an optional description. A string parameter named Type is also supported.
Wrapping Up
The process of executing a document works a bit differently depending on which document you're using. Typically, you'll need to enter the Send-SSMCommand cmdlet, followed by the -DocumentName parameter and the name of the document. In some cases you might be able to get away with using the document's short name (AWSEC2-RunSysprep), but in other cases, the full ARN name might be required (arn:aws:ssm:us-east-2:12345678912:document/AWSEC2-RunSysprep). You can append the document's required parameters to the end of the command.
About the Author
Brien Posey is a 22-time Microsoft MVP with decades of IT experience. As a freelance writer, Posey has written thousands of articles and contributed to several dozen books on a wide variety of IT topics. Prior to going freelance, Posey was a CIO for a national chain of hospitals and health care facilities. He has also served as a network administrator for some of the country's largest insurance companies and for the Department of Defense at Fort Knox. In addition to his continued work in IT, Posey has spent the last several years actively training as a commercial scientist-astronaut candidate in preparation to fly on a mission to study polar mesospheric clouds from space. You can follow his spaceflight training on his Web site.