Creating SSM Documents

When you execute a command using SSM Run Command, the system reads the actions to be performed from a document that defines the plugins to run and parameters to use. This document is called an SSM document. The first time you execute a command from a new SSM document, the system stores the document with your Amazon Web Services (AWS) user account.

Limitations

As you begin working with SSM documents, be aware of the following limitations.

You can create a maximum of 200 SSM documents per AWS account.
SSM documents that you create are only available in the region where you created them. To add a document in another region, copy the content and recreate it in the new region.

Note

If you need to create more than the maximum number of SSM documents, contact AWS Support.

When giving a user access to Run Command the best practice is to start with a policy of least privilege. Create different SSM documents that allow the user to do a minimum number of tasks. For example, you could specify the name of a specific service on an instance so that a Run Command user could only restart that service.

Create an SSM Document Using the Amazon EC2 Console

Open the Amazon EC2 console and choose Commands in the navigation pane.
Choose Documents and then choose Create Document.
Enter a descriptive name for the document and then specify plugins and parameters in the Content field in JSON format. For more information, see SSM Plugins in the Amazon EC2 Simple Systems Manager API Reference.
Choose Create Document to save it with your AWS user account.

Create an SSM Document Using Windows PowerShell

Specify plugins and parameters in a file. Save the document with a descriptive name and a .json file extension. For more information, see SSM Plugins in the Amazon EC2 Simple Systems Manager API Reference.
Create the document and save it with your AWS user account using AWS Tools for Windows PowerShell.
```
$json = Get-Content C:\your file | Out-String
New-SSMDocument -Name document name -Content $json
```

Create an SSM Document Using the AWS CLI

Specify plugins and parameters in a file. Save the document with a descriptive name and a .json file extension. For more information, see SSM Plugins in the Amazon EC2 Simple Systems Manager API Reference.
Create the document and save it with your AWS user account using the AWS CLI.
```
aws ssm create-document --content file://c:\temp\your file --name "document name"
```

Sample SSM Documents

SSM documents are currently supported in JavaScript Object Notation (JSON) and use the following:

schemaVersion 1.2
A runtimeConfig that uses one or more plugins to execute tasks. Plugins are platform specific, meaning they run on either a supported version of Microsoft Windows or Linux. For more information about plugins, see SSM Plugins in the Amazon EC2 Simple Systems Manager API Reference.

Use the following examples as a foundation to create your own documents.

Restrictive SSM Document for Linux

The following example shows a highly-restrictive SSM document that uses the AWS-RunShellScript document on Linux. The user can only run the ifconfig command to check the IP configuration of the instance:

{
  "schemaVersion": "1.2",
  "description": "Check ip configuration of a Linux instance.",
  "parameters": {
 
  },
  "runtimeConfig": {
    "aws:runShellScript": {
      "properties": [
        {
          "id": "0.aws:runShellScript",
          "runCommand": ["ifconfig"]
        }
      ]
    }
  }
}

This section includes several JSON templates that you can use to create your own SSM documents. These templates are based on the AWS public SSM documents. http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/;

AWS-RunShellScript

{
    "schemaVersion":"1.2",
    "description":"Run a shell script or specify the commands to run.",
    "parameters":{
        "commands":{
            "type":"StringList",
            "description":"(Required) Specify a shell script or a command to run.",
            "minItems":1,
            "displayType":"textarea"
        },
        "workingDirectory":{
            "type":"String",
            "default":"",
            "description":"(Optional) The path to the working directory on your instance.",
            "maxChars":4096
        },
        "executionTimeout":{
            "type":"String",
            "default":"3600",
            "description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours).",
            "allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
        }
    },
    "runtimeConfig":{
        "aws:runShellScript":{
            "properties":[
                {
                    "id":"0.aws:runShellScript",
                    "runCommand":"{{ commands }}",
                    "workingDirectory":"{{ workingDirectory }}",
                    "timeoutSeconds":"{{ executionTimeout }}"
                }
            ]
        }
    }
}

AWS-UpdateSSMAgent

{
    "schemaVersion": "1.2",
    "description": "Update the Amazon SSM Agent to the latest version or specified version.",
    "parameters": {
        "version": {
            "default": "",
            "description": "(Optional) A specific version of the Amazon SSM Agent to install. If not specified, the agent will be updated to the latest version.",
            "type": "String"
        },
        "allowDowngrade": {
            "default": "false",
            "description": "(Optional) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.",
            "type": "String",
            "allowedValues": [
                "true",
                "false"
            ]
        }
    },
    "runtimeConfig": {
        "aws:updateSsmAgent": {
            "properties": [
                {
                "agentName": "amazon-ssm-agent",
                "allowDowngrade": "{{ allowDowngrade }}",
                "targetVersion": "{{ version }}"
                }
            ]
        }
    }
}

Document Conventions

« Previous Next »