Amazon EC2 Systems Manager Documents: Support for Cross-platform Documents and Multiple Steps of the Same Type

This post was written by Babul Mehta, Software Development Engineer with Amazon Web Services.

Amazon EC2 Systems Manager documents define the actions that Systems Manager services perform on your managed instances. Documents are essentially a series of steps executed in sequence, and can be versioned and shared across accounts (and even publicly). Systems Manager includes many pre-configured documents that you can use by specifying parameters at runtime. In addition to these pre-configured public documents, you can create your own documents to perform actions relevant to your needs.

With the launch of cross-platform support and the ability to have multiple steps of the same type in a document, some of the existing pain points are eliminated and you can build rich documents to perform cross-platform actions. In this post, I show you how to use these new features while creating documents and executing them via Run Command and State Manager.

Cross-platform document support

For each step in a document, you can now set preconditions that let you specify whether a step can target Windows or Linux instances. Previously, you could not add Windows-only compatible and Linux-only compatible steps in a single document. You had to create multiple, duplicate documents. With cross-platform support, this restriction is removed. I walk through an example to demonstrate this. Preconditions are supported from document schema version 2.2, which is the latest version recommended for new documents.

Precondition

You can now specify an option precondition for each step. The step is executed if the precondition is met, else it is skipped. For example:

{
      "action":"aws:runPowerShellScript",
      "precondition": {
          "StringEquals": ["platformType", "Windows"]
      },
      "name":"runPowerShellScript",
      "inputs": {
        "runCommand":["hostname"]
      }
    }

Here, the runPowerShellScript step is executed only on Windows instances. On Linux instances, this step is skipped.

To use cross-platform functionality, your instances must be running Systems Manager (SSM) Agent version 2.0.834.0 or later.

Another good example of cross-platform document is the AWS-RunPatchBaseline public document. It scans or installs patches from a patch baseline to a Linux or Windows operating system. For more information, see Amazon EC2 Systems Manager Patch Manager now supports Linux.

Here’s another example where you can create a custom document that lists open ports on Windows and Linux managed instances. The document contains two steps:  one runs a PowerShell command and another a Shell command. They have preconditions with platformType equaling Windows and Linux respectively, so that the same document can be targeted against both platforms. Only the compatible step is executed, while the non-compatible step is skipped.

Step 1: Create a cross-platform document

Store the following JSON in a local file:

{
  "schemaVersion":"2.2",
  "description":"Cross-platform demo document",
  "mainSteps": [
    {
      "action":"aws:runPowerShellScript",
      "precondition": {
          "StringEquals": ["platformType", "Windows"]
      },
      "name":"WindowsOpenPorts",
      "inputs": {
        "runCommand": ["netstat -a"]
      }
    },
    {
        "action":"aws:runShellScript",
        "precondition": {
            "StringEquals": ["platformType", "Linux"]
        },
        "name":"LinuxOpenPorts",
        "inputs": {
            "runCommand": ["netstat -lntu"]
        }
    }
  ]
}

To create the document, call the CreateDocument API operation:

aws ssm create-document --name CrossPlatformDemo --content file://cross-platform_demo.json --document-type Command

You can execute the preceding document using Systems Manager Run Command or State Manager. This post demonstrates both.

Step 2: Execute cross-platform document via Run Command

First, execute the CrossPlatformDemo document via the Send Command API. You are executing the command against two instances:  Windows and Linux. You can do the same via tags as well.

aws ssm send-command --document-name "CrossPlatformDemo" --instance-ids "i-09d19a0a297ad4c56" "i-07091332b7f4c71f2"

You can view the results via AWS CLI or console. Here is the console output:

The preceding screenshots are the results from the Linux instance. You can see that the LinuxOpenPorts step got executed and returned valid results, while the WindowsOpenPorts step was skipped because the precondition was not satisfied on the Linux instance.

Step 3:  Execute the cross-platform document via State Manager

Now, execute the same document via State Manager by creating an association. An association is a binding of the intent (described in the document) to a target specified by either a list of instance IDs or a tag query.

Use the following command to create an association using a tag query. The document name is from the previous step: “CrossPlatformDemo”.

aws ssm create-association --name CrossPlatformDemo --targets "Key=tag:Scenario,Values=Demo" --schedule-expression "cron(0 0/30 * 1/1 * ? *)"

After you create an association, you can view the details using either the CLI or the console. You can easily drill down and find out which instances were targeted as part of this State Manager association, and their status.

Multiple steps of the same type

Previously, Systems Manager did not support having the same step or plugin multiple times within a document. This made it cumbersome to separate out logical steps, such as pre- and post-scripts in a configuration.

With this addition, you can perform more powerful configurations using Systems Manager. For example, you can use RunShellScript to install different applications. It is more organized if you have different steps for each application, instead of forcing everything in one step.

In the following example, you install SSMAgent and Apache HTTP Server in two separate steps. They both run the RunShellScript plugin.

Step 1:  Create a document with multiple steps of the same type

Store the following JSON in a local file:

{
  "schemaVersion":"2.0",
  "description":"Multiple steps of same type demo document",
  "mainSteps": [
    {
        "action":"aws:runShellScript",
        "name":"installSSMAgent",
        "inputs": {
            "runCommand":[
            	"sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm",
            	"sudo start amazon-ssm-agent",
            	"sudo status amazon-ssm-agent"
            ]
        }
    },
    {
        "action":"aws:runShellScript",
        "name":"installApache",
        "inputs": {
            "runCommand":[
            	"sudo yum install -y httpd24"
            ]
        }
    }
  ]
}

To create the document, call the CreateDocument API operation:

aws ssm create-document --name MultipleStepsDemo --content file://multiple-steps_demo.json --document-type Command

Again, you can execute this document via Systems Manager Run Command or State Manager. For this scenario, execute it via Run Command only.

Step 2: Execute the multiple-steps document via Run Command

The following command executes the MultipleStepsDemo document against one instance. You can do the same via tags as well.

aws ssm send-command --document-name "MultipleStepsDemo" --instance-ids "i-09d19a0a297ad4c56"

You can view the results via CLI or console. Here’s the output from the console.

Conclusion

In this post, I showed you how to use the newly launched Systems Manager document features to create cross-platform documents, and have multiple steps of same type within a document. These features eliminate the current pain point of maintaining a duplicate set of documents for different platforms. They also open up more possibilities to create rich documents that you can use with Systems Manager to manage and configure your EC2 instance fleet.

About the Author

Babul Mehta is a Software Development Engineer in the Amazon EC2 Systems Manager team. Outside of work, he loves to watch cricket and American football and he is a big fan of the Indian cricket team and the Seahawks.