Menu
Amazon EC2 Systems Manager
User Guide

Creating Systems Manager Documents

If the Systems Manager public documents limit the actions you want to perform on your managed instances, you can create your own documents. When creating a new document, we recommend that you use schema version 2.0 or later. A Systems Manager document contains the following sections.

  • schemaVersion: the schema version to use.

  • Description: Information you provide to describe the purpose of the document.

  • Parameters: The parameters the document accepts, for example command. To easily reference parameters you use often, use Parameter Store parameters in the following format: {{ssm:parameter_name}}. For more information, see Systems Manager Parameter Store.

  • mainSteps: An object that can include multiple steps (plugins). Steps include one or more actions, a unique name of the action, and inputs (parameters) for those actions. For more information, see SSM Plugins in the Amazon EC2 Systems Manager API Reference.

The following example shows the Systems Manager required sections.

Copy
{ "schemaVersion":"2.0", "description":"Run a script", "parameters":{ "commands":{ "type":"StringList", "description":"(Required) Specify a shell script or a command to run.", "minItems":1, "displayType":"textarea" } }, "mainSteps":[ { "action":"aws:runShellScript", "name":"runShellScript", "inputs":{ "runCommand":"{{ commands }}" } }, { "action":"aws:runPowerShellScript", "name":"runPowerShellScript", "inputs":{ "runCommand":"{{ commands }}" } } ] }

Note

You currently can't use the same plugin twice in a policy document.

When you create a document, you specify the contents of the document in JSON. The easiest way to get started with the JSON is to copy an existing sample from one of the Systems Manager public documents.

To copy a Systems Manager document

  1. In the Amazon EC2 console, expand Systems Manager Shared Resources, and then choose Documents.

  2. Choose a document.

  3. In the lower pane, choose the Content tab.

  4. Copy the JSON to a text editor and specify the details for your custom document.

  5. Save the file with a .json file extension.

After you author the content of the document, you can add it to Systems Manager using any one of the following procedures.

Note

If you author a policy document, you must associate the document with your managed instances after you add it the system. For more information, see State Manager Associations.

Add a Systems Manager Document Using the Amazon EC2 Console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Documents.

  3. Choose Create Document.

  4. Type a descriptive name for the document

  5. In the Document Type list, choose the type of document you want to create.

  6. Delete the brackets in the Content field, and then paste the document you created earlier.

  7. Choose Create Document to save the document.

Add a Systems Manager Document Using Windows PowerShell

  1. Copy and customize an existing document, as described earlier.

  2. Add the document using the AWS Tools for Windows PowerShell.

    Copy
    $json = Get-Content C:\your file | Out-String New-SSMDocument -Name document name -Content $json

Add a Systems Manager Document Using the AWS CLI

  1. Copy and customize an existing document, as described earlier.

  2. Add the document using the AWS CLI.

    Copy
    aws ssm create-document --content file://path to your file\your file --name "document name" --document-type "Command"

    Windows example

    Copy
    aws ssm create-document --content file://c:\temp\PowershellScript.json --name "PowerShellScript" --document-type "Command"

    Linux example

    Copy
    aws ssm create-document --content file:///home/ec2-user/RunShellScript.json --name "RunShellScript" --document-type "Command"