Introduction to Creating SSM Automation Runbooks Using CloudFormation

Introduction to creating SSM Automation Runbooks using CloudFormation AWS_EN

Introduction to Creating SSM Automation Runbooks Using CloudFormation

Many SSM Automation runbooks are currently provided by default.

Systems Manager Automation runbook reference - AWS Systems Manager Automation runbook reference
Learn about the predefined runbooks maintained by AWS, AWS Support, and AWS Config.

However, if there is no runbook that matches your needs, you can create your own runbook.

This page creates a custom runbook.
The contents of the runbook will be based on the sample shown on the official AWS page.

AWS::SSM::Document - AWS CloudFormation
Use the AWS CloudFormation AWS::SSM::Document resource for SSM.

Associate this runbook with an EC2 instance and check its operation.


Diagram of introduction to creating SSM Automation Runbooks using CloudFormation

Create an EC2 instance in a private subnet.
The instance will be the latest Amazon Linux 2.

Create an SSM Automation runbook.
The purpose of this runbook is to execute arbitrary commands on an EC2 instance.
In this case, we will execute the “echo Hello World” command.

It also creates an association between this runbook and the instance.

CloudFormation template files

The above configuration is built with CloudFormation.
The CloudFormation templates are placed at the following URL

Explanation of key points of template files

Automation Runbook

    Type: AWS::SSM::Document
        assumeRole: "{{AutomationAssumeRole}}"
        description: Run a script on Linux instances.
        schemaVersion: "0.3"
            type: String
            description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
            default: ""
            type: String
            description: (Required) The commands to run or the path to an existing script on the instance.
            default: echo Hello World
            type: String
            description: (Required) The instance ID you want to run commands on.
            default: ""
          - name: sayHello
            action: aws:runCommand
              DocumentName: AWS-RunShellScript
                - "{{InstanceId}}"
                  - "{{Commands}}"
      DocumentFormat: YAML
      DocumentType: Automation
      Name: !Sub "${Prefix}-MyRunbook"
      TargetType: /AWS::EC2::Instance
Code language: YAML (yaml)

The Content property describes the contents of the runbook.

Using the sample introduced at the beginning of this section, create a runbook that executes arbitrary commands on an EC2 instance.

Specify a service role for Automation to execute this runbook in the “assumeRole” data element.
The “{{AutomationAssumeRole}}” notation can be used to refer to the parameters of the runbook as described below.

The schemaVersion data element should be “0.3”.
This is a fixed value for creating Automation runbooks, as quoted below.

Documents of type Automation must use schema version 0.3.

SSM document schema features and examples

In the parameters data element, specify the parameters for executing this runbook.
In this case, we receive the following three parameters

  • AutomationAssumeRole: ARN of the service role that Autometion will use to execute this runbook
  • Commands: Commands to be executed on the instance
  • InstanceId: ID of the target instance

The mainSteps data element describes the process to be executed in the runbook.
The process to be executed is defined in units called steps.

Set the Automation action to be executed in action.
The actions that can be specified can be found on the following page.

Systems Manager Automation actions reference - AWS Systems Manager
Automation actions determine the input, behavior, and output of each step in an Automation runbook.

In this case, we will specify aws:runCommand.
This action executes any SSM document on the instance with SSM Run Command.

aws:runCommand – Run a command on a managed instance - AWS Systems Manager
Run the specified commands.

Specify the parameters for executing the action in inputs.
The parameters specified here depend on the action to be executed.
In this case, we will specify three parameters.

The DocumentFormat property allows you to specify the format of the runbook.
In this case, “YAML” is specified.

Specify the type of document to be created with the DocumentType property.
In this case, “Automation” is specified.

The TargetType property allows you to set the target resource for this runbook.
In this case, we will target an EC2 instance, so specify “/AWS::EC2::Instance”.

Service Roles for Automation

    Type: AWS::IAM::Role
    DeletionPolicy: Delete
        Version: 2012-10-17
          - Effect: Allow
            Action: sts:AssumeRole
        - arn:aws:iam::aws:policy/service-role/AmazonSSMAutomationRole
        - PolicyName: PassRolePolicy
            Version: 2012-10-17
              - Effect: Allow
                  - iam:PassRole
                  - "*"
Code language: YAML (yaml)

Normally, if no service role is specified, the default service link role (SLR), AWSServiceRoleforAmazonSSM, is used.
In this case, create the service role according to the following official AWS page.

Method 2: Use IAM to configure roles for Automation - AWS Systems Manager
Create a service role for Systems Manager Automation using IAM.

SSM Association

    Type: AWS::SSM::Association
      AssociationName: !Sub "${Prefix}-MyRunbookAssociation"
      AutomationTargetParameterName: InstanceId
      Name: !Ref MyRunbook
          - !GetAtt MyRunbookRole.Arn
          - "echo Hello World"
          - "{{RESOURCE_ID}}"
        - Key: !Sub "tag:${TagKey}"
            - !Ref TagValue
      WaitForSuccessTimeoutSeconds: !Ref WaitForSuccessTimeoutSeconds
Code language: YAML (yaml)

Create an association between the runbook and the instance described above.

For information on how to create SSM associations and run SSM Automation runbooks on EC2 instances, please see the following page.

In this case, instances with the following tags are targeted for association.

  • Tag Key: MyDocument
  • Tag Value: Group1

Tag instances with the above conditions to make them eligible for association.

Specify the command to be executed on the target instance in the Commands of the Parameters property.
In this case, “echo Hello World” is specified to execute the echo command on the instance.


Use CloudFormation to build this environment and check its actual behavior.

Create CloudFormation stacks and check the resources in the stacks

Create CloudFormation stacks.
For information on how to create stacks and check each stack, please refer to the following pages.

After reviewing the resources in each stack, information on the main resources created in this case is as follows

  • EC2 instance: i-0ffc6032e2eec1e8d
  • Custom SSM Automation runbook: fa-119-MyRunbook
  • SSM association: 01462c07-2c00-46d7-b28e-77f9c844f329

Action Check

Now that you are ready, check each resource from the AWS Management Console.

Custom SSM Automation Runbook

Check the runbook you have created.

Detail of SSM 1.
Detail of SSM 2.
Detail of SSM 3.

You can see that the runbook has been successfully created.

There are three parameters in this runbook, the contents of which execute arbitrary commands to the instance using the SSM document AWS-RunShellScript.

SSM Association

Check association.

Detail of SSM 4.

You can see that an association has been created for the aforementioned runbook.

Detail of SSM 5.

These are the parameters for executing the runbook.
The command to be executed in this instance is the echo command, which outputs “Hello World”.

Detail of SSM 6.

Looking at the target, we can see that the target is the instance whose tag name MyDocument has the value “Group1”.

Check the run history of the runbook.

Detail of SSM 7.

Execution has been completed successfully.

Check the detailed log of executed steps.

Detail of SSM 8.

You can see that the SSM document AWS-RunShellScript was successfully executed for the instance and “Hello World” was output.


Thus, we were able to create a custom runbook and associate this with an EC2 instance.