Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Documents

An Amazon EC2 Systems Manager Document defines the actions that Systems Manager performs on your managed instances. Systems Manager includes more than a dozen pre-configured documents that you can use by specifying parameters at runtime. Documents use JavaScript Object Notation (JSON), and they include steps and parameters that you specify. Steps execute in sequential order.

Type Use with Details

Command document

Run Command

State Manager

Run Command uses command documents to execute commands. State Manager uses command documents to apply a policy. These actions can be run on one or more targets at any point during the lifecycle of an instance,

Policy document

State Manager

Policy documents enforce a policy on your targets. If the policy document is removed, the policy (for example, collecting inventory) no longer happens.

Automation document

Automation

Use automation documents when performing common maintenance and deployment tasks such as creating or updating an Amazon Machine Image (AMI).

Systems Manager Pre-Defined Documents

To help you get started quickly, Systems Manager provides pre-defined documents. You can view these documents in the Amazon EC2 console. In the EC2 console, expand Systems Manager Shared Resources, and then choose Documents. After you choose a document, use the tabs in the lower pane to view information about the document you selected, as shown in the following image.


                        Systems Manager documents

You can also use the AWS CLI and Tools for Windows PowerShell commands to view a list of documents and get descriptions about those documents.

AWS CLI

Copy
aws ssm list-documents
Copy
aws ssm describe-document --name "document_name"

Tools for Windows PowerShell

Copy
Get-SSMDocumentList
Copy
Get-SSMDocumentDescription -Name "document_name"

Customizing a Document

If you want to customize the steps and actions in a document, you can create your own. The first time you use a document to perform an action on an instance, the system stores the document with your AWS account. For more information about how to create a Systems Manager document, see Creating Systems Manager Documents.

Sharing a Document

You can make your documents public or share them with specific AWS accounts. For more information, see Sharing Systems Manager Documents.

Document Schemas and Features

Systems Manager documents currently use the following schema versions.

  • Documents of type Command can use schema version 1.2 or 2.0. If you are currently using schema 1.2 documents, we recommend that you create documents that use schema version 2.0.

  • Documents of type Policy must use schema version 2.0.

  • Documents of type Automation must use schema version 0.3.

By using the latest schema versions for each document type, you can take advantage of the following features.

Schema Version 2.0 Document Features

Feature Details

Document editing

Documents can now be updated. With version 1.2, any update to a document requires that you save it with a different name.

Automatic versioning

Any update to a document creates a new version. This is not a schema version, but a version of the document.

Default version

If you have multiple versions of a document, you can specify which version is the default document.

Sequencing

Steps in the document execute in the order that you specified.

Document types

Systems Manager supports Command, Policy, and Automation document types.

Document Examples by Schema Version

The following example shows a document that uses schema version 1.2. In this example, the document includes the aws:runShellScript plugin for executing ifconfig with Run Command.

Schema 1.2 example

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

The following example shows a document that uses schema version 2.0. In this example, the document includes the aws:runShellScript and aws:runPowerShellScript plugins for executing commands with Run Command.

Schema 2.0 example

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 }}" } } ] }

The following sample shows a basic policy document that uses the aws:runPowerShellScript plugin to get information about a process. A policy document can have multiple steps.

Schema 2.0 example

Copy
{ "schemaVersion": "2.0", "description": "Sample version 2.0 document v2", "parameters": { }, "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "runPowerShellScript", "inputs": { "runCommand": [ "Get-Process" ] } } ] }

The following sample includes multiple actions.

Schema 2.0 example

Copy
{ "schemaVersion": "2.0", "description": "Sample version 2.0 document v2 to install application and run a command", "parameters": { "action": { "type": "String", "default": "Install", "description": "(Optional) The type of action to perform. Valid values: Install | Repair | Uninstall", "allowedValues": [ "Install", "Repair", "Uninstall" ] }, "parameters": { "type": "String", "default": "", "description": "(Optional) The parameters for the installer." }, "source": { "type": "String", "description": "(Required) The URL or local path on the instance to the application .msi file." }, "sourceHash": { "type": "String", "default": "", "description": "(Optional) The SHA256 hash of the .msi file." }, "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)" } }, "mainSteps": [ { "action": "aws:applications", "name": "installApplication", "inputs": { "action": "{{ action }}", "parameters": "{{ parameters }}", "source": "{{ source }}", "sourceHash": "{{ sourceHash }}" } }, { "action": "aws:runPowerShellScript", "name": "runPowerShellScript", "inputs": { "runCommand": "{{ commands }}", "workingDirectory": "{{ workingDirectory }}", "timeoutSeconds": "{{ executionTimeout }}" } } ] }

The following table lists the differences between versions.

Version 1.2 Version 2.0 Details

runtimeConfig

mainSteps

In version 2.0, the mainSteps section replaces runtimeConfig. The mainSteps section enables Systems Manager to execute steps in sequence.

properties

inputs

In version 2.0, the inputs section replaces the properties section. The inputs section accepts parameters for steps.

commands

runCommand

In version 2.0, the inputs section takes the runCommand parameter instead of the commands parameter.

id

action

Action replaces ID in version 2.0. This is just a name change.

not applicable

name

Name is any user-defined name for a step.

Document Versions and Execution

You can create and save different versions of documents. You can then specify a default version for each document. The default version of a document can be updated to a newer version or reverted to an older version of the document. If you change the default version of a State Manager Policy or Command document, any association that uses the document will start using the new default version the next time Systems Manager applies the association to the instance.

When you change the JSON content of a document, Systems Manager automatically increments the version of the document. You can retrieve and view previous versions of the document. State Manager Policy or Command documents can be associated with either instances or tagged groups.

Also note the following details about policy documents.

  • You can assign multiple documents to a target by creating different associations that use different policy documents.

  • If you associate multiple documents to a target, you can use the AWS CLI or SDK to view a consolidated list of plugins that will be executed across all associated documents.

  • The order in which steps are specified in a document is the order in which they will be executed.

  • You can use a shared document with State Manager, as long as you have permission, but you can't associate a shared document to an instance. If you want to use or share a document that is associated with one or more targets, you must create a copy of the document and then use or share it.

  • If you create a document with conflicting plugins (e.g., domain join and remove from domain), the last plugin executed will be the final state. State Manager does not validate the logical sequence or rationality of the commands or plugins in your document.

  • When processing documents, instance associations are applied first, and next tagged group associations are applied. If an instance is part of multiple tagged groups, then the documents that are part of the tagged group will not be executed in any particular order. If an instance is directly targeted through multiple documents by its instance ID, there is no particular order of execution.

Limitations

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

  • By default, you can create a maximum of 200 documents per AWS account per region.

  • Systems Manager 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.

  • Each document can store up to 1,000 versions.