Amazon Web Services uses Systems Manager Documents to define actions that should be taken on your instances. This could be a wide variety of actions including updating the operating system, copying files such as logs to another destination or re-configuring your applications. These documents are written in Javascript Object Notation (JSON) and are stored within AWS for use with theother Simple Systems Manager (SSM) services such as the Automation Service or Run command.

Amazon has created some SSM documents that you can use to get started operating your cloud such as running shell scripts or Powershell scripts. These documents are also used for things like patch compliance which we’ve covered before in another post.

Let’s assume that we want to create our own documents. We may very well never need to do this, since the Powershell and shell scripts documents will let us do about anything we want, but in this example I’m going to create my own shellscript document. In this document I will embed my commands so that I don’t need to use the document with a shell parameter anymore. This new document that I’ll create will be self contained and will have a single purpose that will be repeated each time it’s executed.

Specifically I want to download an image from an S3 bucket to use for my web page for an apache server through the AWS Run Command.

The SSM documents have a few parts that can be edited for your own purposes. Each section should be reviewed.

1. schemaVersion – This is the version of the SSM document you’d be using. Over time the documents may change so the version will be used to ensure it will work after new versions are released.
2. Description – This is a useful section to remind people what the document is used for.
3. Parameters – You can add parameters to these documents so the same document can be used with different inputs.
4. mainSteps – This will be the actions that will be taken when the document is used.
5. precondition – This is an option in version 2.2 or higher where you can specify both Windows and Linux commands. The precondition would be used to ensure that the proper commands were running on the proper operating system. I.E. Powershell runs on Windows and Bash runs on Linux.

Note: This post assumes that the documents are version 2.X. These documents may change based on the versioning.

The example below is a custom document that I created for testing.

{
   "schemaVersion":"2.2",
   "description":"Hollow World Web Document",
   "parameters":{"location":{
                        "description": "Image Location",
                        "type": "String",
                        "default":""
                      }
                },
   "mainSteps":[
      {
         "action":"aws:runShellScript",
         "name":"Configure_Apache",
         "precondition":{
            "StringEquals":[
               "platformType",
               "Linux"
            ]
         },
         "inputs":{
            "runCommand":[
              "temp=$(aws --region=us-east-1 ssm get-parameters --names /hollowweb/image --query Parameters[0].Value)",
              "image=$(echo $temp | sed 's/\"//g')",
              "aws s3 cp $image /var/www/html/image001.png",
              "service httpd restart"
            ]
         }
      }
   ]
}

I don’t want to focus too much on the schemaVersion or description which seem pretty straight forward.

Parameters

Below that the document has a parameters section. For this particular example, I’m not using the parameters but we could use them to ask for input so I added a section just for reference. If this was really needed, we’d be asking for a location parameter of type string and the default value would be blank.

   "parameters":{"location":{
                        "description": "Image Location",
                        "type": "String",
                        "default":""
                      }
                },

mainSteps

The main steps is where the magic happens. You’ll notice that we have an action of type aws:runShellScript. This is used to tell SSM which type of commands we’d be running such as Powershell or Shell scripts. The next section is just the name of the commands we’re using and is like a description for you to reference. After that is the precondition where we ensure that the commands only run if the platform type is Linux. Since this is a shell script we don’t want to try to run it on Windows. We could add another precondition with different commands for Windows machines.

Then under inputs: we’ll have the type of command it would be used for. In this case we’re using the runCommand and then we must list our commands in this section. You may notice that I’m running some commands that then get a parameter from the AWS SSM Parameter Store as we explained in the previous post on Parameter Store.

"mainSteps":[
      {
         "action":"aws:runShellScript",
         "name":"Configure_Apache",
         "precondition":{
            "StringEquals":[
               "platformType",
               "Linux"
            ]
         },
         "inputs":{
            "runCommand":[
              "temp=$(aws --region=us-east-1 ssm get-parameters --names /hollowweb/image --query Parameters[0].Value)",
              "image=$(echo $temp | sed 's/\"//g')",
              "aws s3 cp $image /var/www/html/image001.png",
              "service httpd restart"
            ]
         }
      }
   ]

Add the Document to Systems Manager

To create the document we’ll go to the EC2 Systems Console and find the “Documents” section under “Systems Manager Shared Resources”. Then click the “Create Document” button.

After that give the document a name and paste in your json that we created earlier. When you’re done click the Create Document button.

NOTE: As usual you can use the AWS cli to do the same thing. Specifically you’d use the aws sssm create-document command.

Summary

When you’re all done you’ll have an SSM document that can be used for future use with other Systems Manager Services.