Creating SSM document content
If the AWS Systems Manager public documents don't perform all the actions you want to perform on
your AWS resources, you can create your own SSM documents. You can also clone SSM
documents using the console. Cloning documents copies content from an existing document
to a new document that you can modify. When creating or cloning a document, the content
of the document must not exceed 64KB. This quota also includes the content specified for
input parameters at runtime. When you create a new Command
or
Policy
document, we recommend that you use schema version 2.2 or later
so you can take advantage of the latest features, such as document editing, automatic
versioning, sequencing, and more.
Writing SSM document content
To create your own SSM document content, it's important to understand the different schemas, features, plugins, and syntax available for SSM documents. We recommend becoming familiar with the following resources.
-
Working with Systems Manager Automation runbooks using the AWS Toolkit for Visual Studio Code
AWS pre-defined SSM documents might perform some of the actions you require.
You can call these documents by using the aws:runDocument
,
aws:runCommand
, or aws:executeAutomation
plugins
within your custom SSM document, depending on the document type. You can also copy
portions of those documents into a custom SSM document, and edit the content to
meet your requirements.
Tip
When creating SSM document content, you might change the content and update your SSM document several times while testing. The following commands update the SSM document with your latest content, and update the document's default version to the latest version of the document.
Note
The Linux and Windows commands use the jq
command line tool
to filter the JSON response data.
Cloning an SSM document
You can clone AWS Systems Manager documents using the Systems Manager Documents console to create SSM documents. Cloning SSM documents copies content from an existing document to a new document that you can modify. You can't clone a document larger than 64KB.
To clone an SSM document
Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/
. In the navigation pane, choose Documents.
-
In the search box, enter the name of the document you want to clone.
-
Choose the name of the document you want to clone, and then choose Clone document in the Actions dropdown.
-
Modify the document as you prefer, and then choose Create document to save the document.
After writing your SSM document content, you can use your content to create an SSM document using one of the following methods.
Create SSM documents
Creating composite documents
A composite AWS Systems Manager (SSM) document is a custom document that performs a series of actions by running one or more secondary SSM documents. Composite documents promote infrastructure as code by allowing you to create a standard set of SSM documents for common tasks such as boot-strapping software or domain-joining instances. You can then share these documents across AWS accounts in the same AWS Region to reduce SSM document maintenance and ensure consistency.
For example, you can create a composite document that performs the following actions:
-
Installs all patches in the allow list.
-
Installs antivirus software.
-
Downloads scripts from GitHub and runs them.
In this example, your custom SSM document includes the following plugins to perform these actions:
-
The
aws:runDocument
plugin to run theAWS-RunPatchBaseline
document, which installs all allow listed patches. -
The
aws:runDocument
plugin to run theAWS-InstallApplication
document, which installs the antivirus software. -
The
aws:downloadContent
plugin to download scripts from GitHub and run them.
Composite and secondary documents can be stored in Systems Manager, GitHub (public and private repositories), or Amazon S3. Composite documents and secondary documents can be created in JSON or YAML.
Note
Composite documents can only run to a maximum depth of three documents. This means that a composite document can call a child document; and that child document can call one last document.
To create a composite document, add the aws:runDocument plugin in a custom SSM document and specify the required inputs. The following is an example of a composite document that performs the following actions:
-
Runs the aws:downloadContent plugin to download an SSM document from a GitHub public repository to a local directory called bootstrap. The SSM document is called StateManagerBootstrap.yml (a YAML document).
-
Runs the
aws:runDocument
plugin to run the StateManagerBootstrap.yml document. No parameters are specified. -
Runs the
aws:runDocument
plugin to run theAWS-ConfigureDocker pre-defined
SSM document. The specified parameters install Docker on the instance.
{ "schemaVersion": "2.2", "description": "My composite document for bootstrapping software and installing Docker.", "parameters": { }, "mainSteps": [ { "action": "aws:downloadContent", "name": "downloadContent", "inputs": { "sourceType": "GitHub", "sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", \"path\":\"documents/bootstrap/StateManagerBootstrap.yml\"}", "destinationPath": "bootstrap" } }, { "action": "aws:runDocument", "name": "runDocument", "inputs": { "documentType": "LocalPath", "documentPath": "bootstrap", "documentParameters": "{}" } }, { "action": "aws:runDocument", "name": "configureDocker", "inputs": { "documentType": "SSMDocument", "documentPath": "AWS-ConfigureDocker", "documentParameters": "{\"action\":\"Install\"}" } } ] }
- More info
-
-
For information about rebooting servers and instances when using Run Command to call scripts, see Handling reboots when running commands.
-
For more information about the plugins you can add to a custom SSM document, see Command document plugin reference.
-
If you simply want to run a document from a remote location (without creating a composite document), see Running documents from remote locations.
-