SSM Document Syntax

The syntax of your document is defined by the schema version used to create it. We recommended that you use schema version 2.2 or later. Documents that use this schema version include the following top-level elements. For information about the properties that you can specify in these elements, see Top-level Elements.

schemaVersion: The schema version to use.
Description: Information you provide to describe the purpose of the document.
Parameters: The parameters the document accepts. For parameters that you reference often, we recommend that you store those parameters in Systems Manager Parameter Store and then reference them. You can reference String and StringList Systems Manager parameters in this section of a document. You can't reference Secure String Systems Manager parameters in this section of a document. For more information, see AWS Systems Manager Parameter Store.
mainSteps: An object that can include multiple steps (plugins). Steps include one or more actions, an optional precondition, a unique name of the action, and inputs (parameters) for those actions. For a list of supported plugins and plugin properties, see SSM Document Plugin Reference.

Important

The name of the action can't include a space. If a name includes a space, you will receive an InvalidDocumentContent error.

Topics

Schema Version 2.2
Schema Version 1.2

Schema Version 2.2

The following example shows the top-level elements of a schema version 2.2 document in JSON.


{
   "schemaVersion":"2.2",
   "description":"A description of the document.",
   "parameters":{
       "parameter 1":{
           "one or more parameter properties"
        },
        "parameter 2":{
            "one or more parameter properties"
        },
        "parameter 3":{
           "one or more parameter properties"
        }
    },
   "mainSteps":[
      {
         "action":"plugin 1",
         "name":"A name for this action.",
         "inputs":{
            "name":"{{ input 1 }}",
            "name":"{{ input 2 }}",
            "name":"{{ input 3 }}",
            
         }
      }
   ]
}

YAML Schema Version 2.2 Example

You can use the following YAML document with Run Command to return the hostname of one or more instances.


---
schemaVersion: '2.2'
description: Sample document
mainSteps:
- action: aws:runPowerShellScript
  name: runPowerShellScript
  inputs:
    runCommand:
    - hostname

Schema Version 2.2 Precondition Parameter Example

Schema version 2.2 provides cross-platform support. This means that within a single SSM document you can specify different operating systems for different plugins. Cross-platform support uses the precondition parameter within a step, as shown in the following example.


{
   "schemaVersion":"2.2",
   "description":"cross-platform sample",
   "mainSteps":[
      {
         "action":"aws:runPowerShellScript",
         "name":"PatchWindows",
         "precondition":{
            "StringEquals":[
               "platformType",
               "Windows"
            ]
         },
         "inputs":{
            "runCommand":[
               "cmds"
            ]
         }
      },
      {
         "action":"aws:runShellScript",
         "name":"PatchLinux",
         "precondition":{
            "StringEquals":[
               "platformType",
               "Linux"
            ]
         },
         "inputs":{
            "runCommand":[
               "cmds"
            ]
         }
      }
   ]
}

Schema Version Examples 2.2

You can use the following YAML document with State Manager to download and install the ClamAV antivirus software. State Manager enforces a specific configuration, which means that each time the State Manager association is run, the system checks to see if the ClamAV software is installed. If not, State Manager reruns this document.


---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
  name: configureServer
  inputs:
    runCommand:
    - sudo yum install -y httpd24
    - sudo yum --enablerepo=epel install -y clamav

Schema Version 2.0 YAML Inventory Example

You can use the following YAML document with State Manager to collect inventory metadata about your instances.


---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
  applications:
    type: String
    default: Enabled
    description: "(Optional) Collect data for installed applications."
    allowedValues:
    - Enabled
    - Disabled
  awsComponents:
    type: String
    default: Enabled
    description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
    allowedValues:
    - Enabled
    - Disabled
  networkConfig:
    type: String
    default: Enabled
    description: "(Optional) Collect data for Network configurations."
    allowedValues:
    - Enabled
    - Disabled
  windowsUpdates:
    type: String
    default: Enabled
    description: "(Optional) Collect data for all Windows Updates."
    allowedValues:
    - Enabled
    - Disabled
  instanceDetailedInformation:
    type: String
    default: Enabled
    description: "(Optional) Collect additional information about the instance, including
      the CPU model, speed, and the number of cores, to name a few."
    allowedValues:
    - Enabled
    - Disabled
  customInventory:
    type: String
    default: Enabled
    description: "(Optional) Collect data for custom inventory."
    allowedValues:
    - Enabled
    - Disabled
mainSteps:
- action: aws:softwareInventory
  name: collectSoftwareInventoryItems
  inputs:
    applications: "{{ applications }}"
    awsComponents: "{{ awsComponents }}"
    networkConfig: "{{ networkConfig }}"
    windowsUpdates: "{{ windowsUpdates }}"
    instanceDetailedInformation: "{{ instanceDetailedInformation }}"
    customInventory: "{{ customInventory }}"

Schema Version 2.2 AWS-ConfigureAWSPackage Example

The following example shows the AWS-ConfigureAWSPackage document. The mainSteps section includes the aws:configurePackage plugin in the action step.

Note

On Linux operating systems, only the AmazonCloudWatchAgent and AWSSupport-EC2Rescue packages are supported.


{
	"schemaVersion": "2.2",
	"description": "Install or uninstall the latest version or specified version of an AWS package. 
	                Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, IntelSriovDriver, 
	                AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
	"parameters": {
		"action": {
			"description": "(Required) Specify whether or not to install or uninstall the package.",
			"type": "String",
			"allowedValues": [
				"Install",
				"Uninstall"
			]
		},
		"name": {
			"description": "(Required) The package to install/uninstall.",
			"type": "String",
			"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9]
			                   [-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^
			                   [a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
		},
		"version": {
			"description": "(Optional) A specific version of the package to install or uninstall. If installing, 
			the system installs the latest published version, by default. If uninstalling, the system uninstalls 
			the currently installed version, by default. If no installed version is found, the latest published 
			version is downloaded, and the uninstall action is run.",
			     "type": "String",
			     "default": "latest"
		}
	},
	"mainSteps": [{
		"action": "aws:configurePackage",
		"name": "configurePackage",
		"inputs": {
			"name": "{{ name }}",
			"action": "{{ action }}",
			"version": "{{ version }}"
		}
	}]
}

Schema Version 1.2

The following example shows the top-level elements of a schema version 1.2 document.


{
   "schemaVersion":"1.2",
   "description":"A description of the Systems Manager document.",
   "parameters":{
      "parameter 1":{
         "one or more parameter properties"
      },
      "parameter 2":{
         "one or more parameter properties"
      },
      "parameter 3":{
         "one or more parameter properties"
      }
   },
   "runtimeConfig":{
      "plugin 1":{
         "properties":[
            {
               "one or more plugin properties"
            }
         ]
      }
   }
}

Schema Version 1.2 Example

The following example shows the AWS-RunShellScript Systems Manager document. The runtimeConfig section includes the aws:runShellScript plugin.


{
    "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 172800 (48 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 }}"
                }
            ]
        }
    }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »