Introduction to Creating SSM Automation Runbooks Using CloudFormation
Many SSM Automation runbooks are currently provided by default.
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.
Associate this runbook with an EC2 instance and check its operation.
Environment
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
https://github.com/awstut-an-r/awstut-fa/tree/main/119
Explanation of key points of template files
Automation Runbook
Resources:
MyRunbook:
Type: AWS::SSM::Document
Properties:
Content:
assumeRole: "{{AutomationAssumeRole}}"
description: Run a script on Linux instances.
schemaVersion: "0.3"
parameters:
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
default: ""
Commands:
type: String
description: (Required) The commands to run or the path to an existing script on the instance.
default: echo Hello World
InstanceId:
type: String
description: (Required) The instance ID you want to run commands on.
default: ""
mainSteps:
- name: sayHello
action: aws:runCommand
inputs:
DocumentName: AWS-RunShellScript
InstanceIds:
- "{{InstanceId}}"
Parameters:
commands:
- "{{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.
https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-actions.html
In this case, we will specify aws:runCommand.
This action executes any SSM document on the instance with SSM Run Command.
https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-action-runcommand.html
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
Resources:
MyRunbookRole:
Type: AWS::IAM::Role
DeletionPolicy: Delete
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action: sts:AssumeRole
Principal:
Service:
- ssm.amazonaws.com
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AmazonSSMAutomationRole
Policies:
- PolicyName: PassRolePolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- iam:PassRole
Resource:
- "*"
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.
https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-setup-iam.html
SSM Association
Resources:
MyRunbookAssociation:
Type: AWS::SSM::Association
Properties:
AssociationName: !Sub "${Prefix}-MyRunbookAssociation"
AutomationTargetParameterName: InstanceId
Name: !Ref MyRunbook
Parameters:
AutomationAssumeRole:
- !GetAtt MyRunbookRole.Arn
Commands:
- "echo Hello World"
InstanceId:
- "{{RESOURCE_ID}}"
Targets:
- Key: !Sub "tag:${TagKey}"
Values:
- !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.
Architecting
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.
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.
You can see that an association has been created for the aforementioned runbook.
These are the parameters for executing the runbook.
The command to be executed in this instance is the echo command, which outputs “Hello World”.
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.
Execution has been completed successfully.
Check the detailed log of executed steps.
You can see that the SSM document AWS-RunShellScript was successfully executed for the instance and “Hello World” was output.
Summary
Thus, we were able to create a custom runbook and associate this with an EC2 instance.