AWS Cloud Operations Blog

Writing your own AWS Systems Manager documents

AWS Systems Manager is a powerful unified interface from AWS that provides you with the ability to centrally manage your AWS resources. Core to leveraging AWS Systems Manager is the use of AWS Systems Manager documents.

An AWS Systems Manager document (SSM document) allows you to define what actions you want Systems Manager to perform on your AWS resources. Systems Manager includes many pre-configured documents that you can use by specifying parameters at runtime. Documents are written in JavaScript Object Notation (JSON) or YAML, and include steps and parameters that you define as needed. In this blog post, I outline the key aspects of leveraging AWS Systems Manager documents for your organization.

THE SSM DOCUMENT

1. The SSM document

First let’s look at an existing SSM document. In the AWS Systems Manager console, in the left navigation pane, choose Documents. Then filter on AWS-ConfigureWindowsUpdate, select the AWS-ConfigureWindowsUpdate document by clicking on its name and then select the Content tab. Notice that AWS Systems Manager typically provides a breadcrumb at the top of the screen for navigation, use this if you are unsure of how to navigate to certain pages.

CLI commands:

aws ssm describe-document 
		--name AWS-UpdateEC2Config

aws ssm get-document 
		--name AWS-UpdateEC2Config

2. Modify an existing SSM document

Typically, documents starting with AWS-* are provided by AWS and cannot be modified. That is the case with this document. You can simply copy and paste it into a new document and make your revisions.

 

3. Create your own SSM document

Choose Create Document at the top of the console. This allows you to create your own document, note that documents can be written in either JSON or YAML.

Document Structure

I’ve labelled the parts of the following screenshot as follows:

  • A. schemaVersion: the schema version to use.

    • It is strongly recommended to use v 2.2.  Automation documents also support versioning.
  • B. Description: Information you provide to describe the purpose of the document.
  • C. Parameters: The parameters the document accepts, both required and optional. To easily reference parameters you use often, use Parameter Store parameters in the following format: {{ssm:parameter_name}}. For more information, see AWS Systems Manager Parameter Store.
  • D. mainSteps: An object that can include multiple steps (plugins). Steps include one or more actions, such as Run command, a unique name of the action, and inputs (parameters) for those actions.

 

The following screenshot is for Execute Automation.

  • A. The description and version to be executed.
  • B. Execution Mode, here you can execute the document. Should there be multiple steps, you may wish to execute all at once, or you may wish to perform each manually and in-turn study the effects of each automation step.
  • C. The parameters this automation document is expecting, required or optional, typically their requirement is displayed here.

Document Type: This tailors the document template for the service you plan to run it against.

4.     SSM document versions

Multiple versions of your own SSM document can be created and stored in AWS.

By highlighting an existing document and selecting Actions > and then Create New Version, you can create a revised version.

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.

For this example, another action has been added to mainSteps, and three new parameters have been added to the parameter list to support this new action.

Note:
To run scripts at instance launch only, consider using State Manager, shown later in this blog post.

For more complex automation scenarios, consider using AWS CloudFormation or AWS OpsWorks instead. For more information, see the AWS CloudFormation User Guide or the AWS OpsWorks User Guide.

5.     Share your SSM documents across accounts.

The ability for organization to develop their own documents and sharing them across accounts is invaluable.

For example, the DevOps and/or SecOps groups can develop, create and validate documents and share them across accounts , for example Dev, Test, and Prod.

A single SSM document can be shared with a maximum of 1000 AWS accounts (at the time of writing this blog post).

Conclusion

In this blog post I cover the key aspects of reviewing existing SSM documents provided by the Systems Manager team. I show you how to take an existing SSM document and modify it. I outline the structure of an SSM document to help you develop your own SSM documents. I provide direction in the versioning of your SSM documents. Finally, I show you how share your SSM documents across accounts. For example, if your organization has a DevOps and/or SecOps team they can develop, create and validate documents and share them across accounts, such as with Dev, Test and Prod.

I encourage you to use what you have learned here and consider leveraging AWS Systems Manager resources in your own organization.

I welcome your comments or questions below.

About the Author

Stefan Minhas is a senior consultant at Amazon Web Services. He is a subject matter expert in the Global Microsoft Specialty Practice, and he provides guidance and technical assistance in the development and growth of specialty skills across the broader Professional Services community.