How-To

How To Create Composite AWS Systems Manager Documents

Sometimes you might want to automate multiple tasks without the hassle of working with several individual SSM documents. You can simplify this action by creating a composite document. Here's how you can do that.

• By Brien Posey
• 03/19/2019

I recently wrote an article about how you can use AWS Systems Manager (SSM) documents to automate tasks within the Amazon Web Services (AWS) cloud. As handy as these documents can be, each document tends to be dedicated to a single task. A document might, for example, be used to run Sysprep or to terminate a virtual machine (VM) instance. Sometimes, though, you may wish to automate multiple tasks without the hassle of working with several individual SSM documents. In these types of situations, you can simplify your automation action by creating a composite document.

A composite document is simply an SSM document that references multiple secondary documents, each of which has been designed to perform a specific task. Composite documents can be a little bit tedious to set up, but in the long run it's much simpler to create a composite document than to manually interact with a large collection of individual documents every time that a task needs to be performed.

A composite document is relatively easy to create, although if you haven't read my previously mentioned article yet, I strongly recommend checking it out before continuing on. You'll need to understand how basic SSM documents work in order to create a composite document.

So with that said, composite SSM documents consist of two main sections. The first section is basically just a header. Here's an example of a composite AWS Systems Manager document containing only the header section:

{
  "schemaVersion": "2.2",
  "description": "My composite document to stop and terminate EC2 instances.",
  "parameters": {
  },
  "mainSteps": [
      ]
}

As you can see, the header is pretty simple. It provides a schema version and a description of the document. There's also a spot for entering parameters, but the use of parameters is optional.

The last command in the document example is MainSteps. This command indicates that all of the remaining code within the document will be used to reference secondary AWS Systems Manager documents.

This is where the second document section comes into play. The second part of the document references the secondary documents you want to use, and provides the parameters that are required by those documents. Here's an example of what one of those sections looks like:

{
  "action": "",
  "name": "",
  "inputs": {
          }
}

Although this sample code is definitely a bit sparse, it provides the basic outline for referencing a secondary document. The Actions section is normally used to tell AWS that you want to run the document you're about to reference (although the action can also be used to tell AWS to download content instead). The Name section acts as a section name and usually reflects the function of the document that you want to run. Finally, the Inputs section tells AWS that you're referencing an SSM document, and then provides the name of the document, as well as any required parameters.

So with that said, let's take a look at what this section might look like if we wanted to run the AWS-StopEC2Instance document:

  {
    "action": "aws:runDocument",
    "name": "StopEC2Instance",
    "inputs": {
      "documentType": "SSMDocument",
      "documentPath": "AWS-StopEC2Instance",
      "documentParameters": ""
    }
  }

In this example, I've set the Action to aws:runDocument, indicating that I want to run an AWS document. The name loosely reflects the name of the document that I'm going to run.

In the Inputs section, I've set the documentType to SSMDocument, indicating that an existing SSM document is to be run. The documentPath provides the exact name of the document.

I've left the document parameters empty in the name of simplicity, but the AWS-StopEC2Instance document requires a couple of parameters, including AutomationAssumeRole and InstanceID. You can find a description of those parameters on the AWS Systems Manager User Guide.

Of course, this block of code only references a single document. You can reference multiple documents by separating blocks of code like I just showed you with a comma. For the sake of example, AWS provides a complete composite document that's designed to download and install bootstrap software, and then install Docker. Here's what the AWS sample code looks like:

{
  "schemaVersion": "2.2",
  "description": "My composite document for bootstrapping software and installing Docker.",
  "parameters": {
  },
  "mainSteps": [
    {
      "action": "aws:downloadContent",
      "name": "downloadContent",
      "inputs": {
        "sourceType": "GitHub",
        "sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", 
          \"path\":\"documents/bootstrap/StateManagerBootstrap.yml\"}",
        "destinationPath": "bootstrap"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "runDocument",
      "inputs": {
        "documentType": "LocalPath",
        "documentPath": "bootstrap",
        "documentParameters": "{}"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "configureDocker",
      "inputs": {
        "documentType": "SSMDocument",
        "documentPath": "AWS-ConfigureDocker",
        "documentParameters": "{\"action\":\"Install\"}"
      }
    }
  ]
}

As you can see, the sample code starts with a header, and then delves into the main steps. Each of those steps, except for the last one, concludes with a comma, which allows another step (or in this case, another document) to be used.