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.

The following table describes the different types of SSM documents.

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).

For information about SSM document limits, see Amazon EC2 Systems Manager Limits.

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"

Document Schemas and Features

Systems Manager documents currently use the following schema versions.

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

  • Documents of type Policy must use schema version 2.0 or later.

  • Documents of type Automation must use schema version 0.3.

By using the latest schema version for Command and Policy documents, you can take advantage of the following features.

Schema Version 2.2 Document Features

Feature Details

Document editing

Documents can now be updated. With version 1.2, any update to a document required 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

Plugins or steps in a document execute in the order that you specified.

Cross-platform support

Cross-platform support enables you to specify different operating systems for different plugins within the same SSM document. Cross-platform support uses the precondition parameter within a step.

Note

You must update the SSM Agent on your instances to the latest version to use new Systems Manager features and SSM document features. For more information, see the section titled Example: Update the SSM Agent in Executing Commands from the EC2 Console.

The following table lists the differences between major schema versions.

Version 1.2 Version 2.0 Details

runtimeConfig

mainSteps

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

properties

inputs

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

commands

runCommand

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

id

action

In version 2.0 or later, Action replaces ID. This is just a name change.

not applicable

name

In version 2.0 or later, name is any user-defined name for a step.

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 higher. 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 in the Amazon EC2 Systems Manager API Reference.

  • 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 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 Plugins in the Amazon EC2 Systems Manager API Reference.

    Important

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

Using the Precondition Parameter

With schema version 2.2 or higher, you can use the precondition parameter to specify the target operating system for each plugin. The precondition parameter supports platformType and a value of either Windows or Linux.

For documents that use schema version 2.2 or higher, if precondition is not specified, each plugin is either executed or skipped based on the plugin’s compatibility with the operating system. For documents that use schema 2.0 or earlier, incompatible plugins throw an error.

For example, in a schema version 2.2 document, if precondition is not specified and the aws:runShellScript plugin is listed, then the step executes on Linux instances, but the system skips it on Windows instances because the aws:runShellScript is not compatible with Windows instances. However, for a schema version 2.0 document, if you specify the aws:runShellScript plugin, and then run the document on a Windows instances, the execution fails.

Syntax for Schema Version 2.0 or higher

The following example shows the top-level elements of a schema version 2.0 or higher document.

Copy
{ "schemaVersion":"2.0", "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 }}", } } ] }

Schema Version 2.2 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.

Copy
{ "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 2.0 Example

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

Copy
{ "schemaVersion": "2.0", "description": "Install or uninstall the latest version or specified version of an AWS package.", "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", "allowedValues": [ "AWSPVDriver" ] }, "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": "", "allowedPattern": "(^(?:(\\d+)\\.)(?:(\\d+)\\.)(\\d+)$|^$)" } }, "mainSteps": [{ "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "version": "{{ version }}" } }] }

Syntax for Schema Version 1.2

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

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

Note

The aws:applications, aws:psModule, aws:runShellScript, and aws:runPowerShellScript plugins allow you to specify an array of properties.

Schema Version 1.2 Example

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

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

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 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 documents can be associated with either instances or tagged groups.

Also note the following details about documents.

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

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

  • Steps in a document execute in sequential order.

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

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.

Tagging Systems Manager Documents

You can use the AddTagsToResource API, the AWS CLI, or the AWS Tools for Windows to add tags to Systems Manager resources including documents, managed instances, Maintenance Windows, Parameter Store parameters, and patch baselines.

Tagging is useful when you have many resources of the same type — you can quickly identify a specific resource based on the tags you've assigned to it. Each tag consists of a key and an optional value, both of which you define.

For example, you can tag documents for specific environments, departments, users, groups, or periods. After you tag a document, you can restrict access to it by creating an IAM policy that specifies the tags that a user can access. For more information about restricting access to documents by using tags, see Controlling Access to Documents Using Tags.

Use the AWS CLI to tag a document

  1. At a terminal (Linux, macOS, or Unix) or command prompt (Windows), run the list-documents command to list the documents that you can tag.

    Copy
    aws ssm list-documents

    Note the name of a document that you want to tag.

  2. Run the following command to tag a document.

    Copy
    aws ssm add-tags-to-resource --resource-type "Document" --resource-id "document-name" --tags "Key=key,Value=value"

    document-name the name of the Systems Manager document you want to tag.

    key is the name of a custom key you supply. For example, region or quarter.

    value is the custom content for the value you want to supply for that key. For example, west or Q318.

    If successful, the command has no output.

  3. Execute the following command to verify the document tags.

    Copy
    aws ssm list-tags-for-resource --resource-type "Document" --resource-id "document-name"

Use the AWS Tools for Windows to tag a document

  1. Open AWS Tools for Windows PowerShell and run the following command to list documents that you can tag:

    Copy
    Get-SSMDocumentList
  2. Run the following commands one at a time to tag a document:

    Copy
    $tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag $tag1.Key = "key" $tag1.Value = "value" Add-SSMResourceTag -ResourceType "Document" -ResourceId "document-name" -Tag $tag1

    document-name the name of the Systems Manager document you want to tag.

    key is the name of a custom key you supply. For example, region or quarter.

    value is the custom content for the value you want to supply for that key. For example, west or Q318.

    If successful, the command has no output.

  3. Run the following command to verify the document tags:

    Copy
    Get-SSMResourceTag -ResourceType "Document" -ResourceId "document-name"

Controlling Access to Documents Using Tags

After you tag a document, you can restrict access to it by creating an IAM policy that specifies the tags the user can access. When a user attempts to use a document, the system checks the IAM policy and the tags specified for the document. If the user does not have access to the tags assigned to the document, the user receives an access denied error. Use the following procedure to create an IAM policy that restricts access to documents by using tags.

Before You Begin

Create and tag documents. For more information, see Tagging Systems Manager Documents.

To restrict a user's access to documents by using tags

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies, and then choose Create policy.

  3. In the Create Your Own Policy section, choose Select.

  4. In the Policy Name field, specify a name that identifies this as a user policy for tagged documents.

  5. Enter a description.

  6. In the Policy Document field, copy and paste the following sample policy. Replace tag_key and tag_value with the key-value pair for your tag.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "ssm:GetDocument" ], "Resource":"*", "Condition":{ "StringLike":{ "ssm:resourceTag/tag_key":[ "tag_value" ] } } } ] }

    You can specify multiple keys in the policy by using the following Condition format. Specifying multiple keys creates an AND relationship for the keys.

    Copy
    "Condition":{ "StringLike":{ "ssm:resourceTag/tag_key1":[ "tag_value1" ], "ssm:resourceTag/tag_key2":[ "tag_value2" ] } }

    You can specify multiple values in the policy by using the following Condition format. ForAnyValue establishes an OR relationship for the values. You can also specify ForAllValues to establish an AND relationship.

    Copy
    "Condition":{ "ForAnyValue:StringLike":{ "ssm:resourceTag/tag_key1":[ "tag_value1", "tag_value2" ] } }
  7. Choose Create Policy.

  8. Assign the policy to IAM users or groups. For more information, see Changing Permissions for an IAM User and Attaching a Policy to an IAM Group.

After you attach the policy to the IAM user or group account, if a user tries to use a document and the user's policy does not allow the user to access a tag for the document (call the GetDocument API), the system returns an error. The error is similar to the following:

"User: user_name is not authorized to perform: ssm:GetDocument on resource: document-name with the following command."

If a document has multiple tags, the user will still receive the Access Denied error if the user does not have permission to access any one of those tags.