Using Document Builder to create runbooks
If the Amazon Systems Manager public runbooks don't support all the actions you want to perform on your Amazon resources, you can create your own runbooks. To create a custom runbook, you can manually create a local YAML or JSON format file with the appropriate automation actions. Alternatively, you can use Document Builder in the Systems Manager Automation console to build a custom runbook.
Using Document Builder, you can add automation actions to your custom runbook and provide the required parameters without having to use JSON or YAML syntax. After you add steps and create the runbook, the system converts the actions you've added into the YAML format that Systems Manager can use to run automation.
Runbooks support the use of Markdown, a markup language, which allows you to add wiki-style descriptions to runbooks and individual steps within the runbook. For more information about using Markdown, see Using Markdown in Amazon.
Create a runbook using Document Builder
Before you begin
We recommend that you read about the different actions that you can use within a runbook. For more information, see Systems Manager Automation actions reference.
To create a runbook using Document Builder
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/
. In the navigation pane, choose Documents.
-
Choose Create automation.
-
For Name, enter a descriptive name for the runbook.
-
For Document description, provide the markdown style description for the runbook. You can provide instructions for using the runbook, numbered steps, or any other type of information to describe the runbook. Refer to the default text for information about formatting your content.
Tip
Toggle between Hide preview and Show preview to see what your description content looks like as you compose.
-
(Optional) For Assume role, enter the name or ARN of a service role to perform actions on your behalf. If you don't specify a role, Automation uses the access permissions of the user who runs the automation.
Important
For runbooks not owned by Amazon that use the
aws:executeScript
action, a role must be specified. For information, see Permissions for using runbooks. -
(Optional) For Outputs, enter any outputs for the automation of this runbook to make available for other processes.
For example, if your runbook creates a new AMI, you might specify ["CreateImage.ImageId"], and then use this output to create new instances in a subsequent automation.
-
(Optional) Expand the Input parameters section and do the following.
-
For Parameter name, enter a descriptive name for the runbook parameter you're creating.
-
For Type, choose a type for the parameter, such as
String
orMapList
. -
For Required, do one of the following:
-
Choose Yes if a value for this runbook parameter must be supplied at runtime.
-
Choose No if the parameter isn't required, and (optional) enter a default parameter value in Default value.
-
-
For Description, enter a description for the runbook parameter.
Note
To add more runbook parameters, choose Add a parameter. To remove a runbook parameter, choose the X (Remove) button.
-
-
(Optional) Expand the Target type section and choose a target type to define the kinds of resources the automation can run on. For example, to use a runbook on EC2 instances, choose
/AWS::EC2::Instance
.Note
If you specify a value of '
/
', the runbook can run on all types of resources. For a list of valid resource types, see Amazon Resource Types Reference in the Amazon CloudFormation User Guide. -
(Optional) Expand the Document tags section and enter one or more tag key-value pairs to apply to the runbook. Tags make it easier to identify, organize, and search for resources.
-
In the Step 1 section, provide the following information.
-
For Step name, enter a descriptive name for the first step of the automation.
-
For Action type, select the action type to use for this step.
For a list and information about the available action types, see Systems Manager Automation actions reference.
-
For Description, enter a description for the automation step. You can use Markdown to format your text.
-
Depending on the Action type selected, enter the required inputs for the action type in the Step inputs section. For example, if you selected the action
aws:approve
, you must specify a value for theApprovers
property.For information about the step input fields, see the entry in Systems Manager Automation actions reference for the action type you selected. For example: aws:executeStateMachine – Run an Amazon Step Functions state machine.
-
(Optional) For Additional inputs, provide any additional input values needed for your runbook. The available input types depend on the action type you selected for the step. (Note that some action types require input values.)
Note
To add more inputs, choose Add optional input. To remove an input, choose the X (Remove) button.
-
(Optional) For Outputs, enter any outputs for this step to make available for other processes.
Note
Outputs isn't available for all action types.
-
(Optional) Expand the Common properties section and specify properties for the actions that are common to all automation actions. For example, for Timeout seconds, you can provide a value in seconds to specify how long the step can run before it's stopped.
For more information, see Properties shared by all actions.
Note
To add more steps, select Add step and repeat the procedure for creating a step. To remove a step, choose Remove step.
-
-
Choose Create automation to save the runbook.
Create a runbook that runs scripts
The following procedure shows how to use Document Builder in the Amazon Systems Manager Automation console to create a custom runbook that runs a script.
The first step of the runbook you create runs a script to launch an Amazon Elastic Compute Cloud
(Amazon EC2) instance. The second step runs another script to monitor for the
instance status check to change to ok
. Then, an overall status of
Success
is reported for the automation.
Before you begin
Make sure you have completed the following steps:
-
Verify that you have administrator privileges, or that you have been granted the appropriate permissions to access Systems Manager in Amazon Identity and Access Management (IAM).
For information, see Verifying user access for runbooks.
-
Verify that you have an IAM service role for Automation (also known as an assume role) in your Amazon Web Services account. The role is required because this walkthrough uses the
aws:executeScript
action.For information about creating this role, see Configuring a service role (assume role) access for automations.
For information about the IAM service role requirement for running
aws:executeScript
, see Permissions for using runbooks. -
Verify that you have permission to launch EC2 instances.
For information, see IAM and Amazon EC2 in the Amazon EC2 User Guide.
To create a custom runbook that runs scripts using Document Builder
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/
. In the navigation pane, choose Documents.
-
Choose Create automation.
-
For Name, type this descriptive name for the runbook:
LaunchInstanceAndCheckStatus
. -
(Optional) For Document description, replace the default text with a description for this runbook, using Markdown. The following is an example.
##Title: LaunchInstanceAndCheckState ----- **Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned. ##Parameters: ----- Name | Type | Description | Default Value ------------- | ------------- | ------------- | ------------- assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | - imageId | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}
-
For Assume role, enter the ARN of the IAM service role for Automation (Assume role) for the automation, in the format
arn:aws-cn:iam::111122223333:role/AutomationServiceRole
. Substitute your Amazon Web Services account ID for 111122223333.The role you specify is used to provide the permissions needed to start the automation.
Important
For runbooks not owned by Amazon that use the
aws:executeScript
action, a role must be specified. For information, see Permissions for using runbooks. -
Expand Input parameters and do the following.
-
For Parameter name, enter
imageId
. -
For Type, choose
String
. -
For Required, choose
No
. -
For Default value, enter the following.
{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}
Note
This value launches an Amazon EC2 instance using the latest Amazon Linux 1 Amazon Machine Image (AMI) ID. If you want to use a different AMI, replace the value with your AMI ID.
-
For Description, enter the following.
(Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID.
-
-
Choose Add a parameter to create the second parameter,
tagValue
, and enter the following.-
For Parameter name, enter
tagValue
. -
For Type, choose
String
. -
For Required, choose
No
. -
For Default value, enter
LaunchedBySsmAutomation
. This adds the tag key-pair valueName:LaunchedBySsmAutomation
to the instance. -
For Description, enter the following.
(Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.
-
-
Choose Add a parameter to create the third parameter,
instanceType
, and enter the following information.-
For Parameter name, enter
instanceType
. -
For Type, choose
String
. -
For Required, choose
No
. -
For Default value, enter
t2.micro
. -
For Parameter description, enter the following.
(Optional) The instance type to use for the instance. The default value is t2.micro.
-
-
Expand Target type and choose
"/"
. -
(Optional) Expand Document tags to apply resource tags to your runbook. For Tag key, enter
Purpose
, and for Tag value, enterLaunchInstanceAndCheckState
. -
In the Step 1 section, complete the following steps.
-
For Step name, enter this descriptive step name for the first step of the automation:
LaunchEc2Instance
. -
For Action type, choose Run a script (
aws:executeScript
). -
For Description, enter a description for the automation step, such as the following.
**About This Step** This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.
-
Expand Inputs.
-
For Runtime, choose the runtime language to use to run the provided script.
-
For Handler, enter
launch_instance
. This is the function name declared in the following script.Note
This is not required for PowerShell.
-
For Script, replace the default contents with the following. Be sure to match the script with the corresponding runtime value.
-
Expand Additional inputs.
-
For Input name, choose InputPayload. For Input value, enter the following YAML data.
image_id: "{{ imageId }}" tag_value: "{{ tagValue }}" instance_type: "{{ instanceType }}"
-
-
Expand Outputs and do the following:
-
For Name, enter
payload
. -
For Selector, enter
$.Payload
. -
For Type, choose
StringMap
.
-
-
Choose Add step to add a second step to the runbook. The second step queries the status of the instance launched in Step 1 and waits until the status returned is
ok
. -
In the Step 2 section, do the following.
-
For Step name, enter this descriptive name for the second step of the automation:
WaitForInstanceStatusOk
. -
For Action type, choose Run a script (
aws:executeScript
). -
For Description, enter a description for the automation step, such as the following.
**About This Step** The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.
-
For Runtime, choose the runtime language to be used for executing the provided script.
-
For Handler, enter
poll_instance
. This is the function name declared in the following script.Note
This is not required for PowerShell.
-
For Script, replace the default contents with the following. Be sure to match the script with the corresponding runtime value.
-
Expand Additional inputs.
-
For Input name, choose InputPayload. For Input value, enter the following:
{{ LaunchEc2Instance.payload }}
-
-
Choose Create automation to save the runbook.