Example 1: Creating parent-child runbooks
The following example demonstrates how to create two runbooks that patch tagged groups of Amazon Elastic Compute Cloud (Amazon EC2) instances in stages. These runbooks are used in a parent-child relationship with the parent runbook used to initiate a rate control automation of the child runbook. For more information about rate control automations, see Run automated operations at scale. For more information about the automation actions used in this example, see the Systems Manager Automation actions reference.
Create the child runbook
This example runbook addresses the following scenario. Emily is a Systems Engineer at AnyCompany Consultants, LLC. She needs to configure patching for groups of Amazon Elastic Compute Cloud (Amazon EC2) instances that host primary and secondary databases. Applications access these databases 24 hours a day, so one of the database instances must always be available.
She decides that patching the instances in stages is the best approach. The primary group of database instances will be patched first, followed by the secondary group of database instances. Also, to avoid incurring additional costs by leaving instances running that were previously stopped, Emily wants the patched instances to be returned to their original state before the patching occurred.
Emily identifies the primary and secondary groups of database instances by
the tags associated with the instances. She decides to create a parent
runbook that starts a rate control automation of a child runbook. By doing
that, she can target the tags associated with the primary and secondary
groups of database instances and manage the concurrency of the child
automations. After reviewing the available Systems Manager (SSM) documents for
patching, she chooses the AWS-RunPatchBaseline
document. By
using this SSM document, her colleagues can review the associated patch
compliance information after the patching operation completes.
To start creating her runbook content, Emily reviews the available automation actions and begins authoring the content for the child runbook as follows:
-
First, she provides values for the schema and description of the runbook, and defines the input parameters for the child runbook.
By using the
AutomationAssumeRole
parameter, Emily and her colleagues can use an existing IAM role that allows Automation to perform the actions in the runbook on their behalf. Emily uses theInstanceId
parameter to determine the instance that should be patched. Optionally, theOperation
,RebootOption
, andSnapshotId
parameters can be used to provide values to document parameters forAWS-RunPatchBaseline
. To prevent invalid values from being provided to those document parameters, she defines theallowedValues
as needed. -
With the top-level elements defined, Emily proceeds with authoring the actions that make up the
mainSteps
of the runbook. The first step outputs the current state of the target instance specified in theInstanceId
input parameter using theaws:executeAwsApi
action. The output of this action is used in later actions. -
Rather than manually starting and keeping track of the original state of every instance that needs to be patched, Emily uses the output from the previous action to branch the automation based on the state of the target instance. This allows the automation to run different steps depending on the conditions defined in the
aws:branch
action and improves the overall efficiency of the automation without manual intervention.If the instance state is already
running
, the automation proceeds with patching the instance with theAWS-RunPatchBaseline
document using theaws:runCommand
action.If the instance state is
stopping
, the automation polls for the instance to reach thestopped
state using theaws:waitForAwsResourceProperty
action, starts the instance using theexecuteAwsApi
action, and polls for the instance to reach arunning
state before patching the instance.If the instance state is
stopped
, the automation starts the instance and polls for the instance to reach arunning
state before patching the instance using the same actions. -
After the patching operation completes, Emily wants the automation to return the target instance to the same state it was in before the automation started. She does this by again using the output from the first action. The automation branches based on the original state of the target instance using the
aws:branch
action. If the instance was previously in any state other thanrunning
, the instance is stopped. Otherwise, if the instance state isrunning
, the automation ends. -
Emily reviews the completed child runbook content and creates the runbook in the same AWS account and AWS Region as the target instances. Now she's ready to continue with the creation of the parent runbook's content. The following is the completed child runbook content.
For more information about the automation actions used in this example, see the Systems Manager Automation actions reference.
Create the parent runbook
This example runbook continues the scenario described in the previous section. Now that Emily has created the child runbook, she begins authoring the content for the parent runbook as follows:
-
First, she provides values for the schema and description of the runbook, and defines the input parameters for the parent runbook.
By using the
AutomationAssumeRole
parameter, Emily and her colleagues can use an existing IAM role that allows Automation to perform the actions in the runbook on their behalf. Emily uses thePatchGroupPrimaryKey
andPatchGroupPrimaryValue
parameters to specify the tag associated with the primary group of database instances that will be patched. She uses thePatchGroupSecondaryKey
andPatchGroupSecondaryValue
parameters to specify the tag associated with the secondary group of database instances that will be patched. -
With the top-level elements defined, Emily proceeds with authoring the actions that make up the
mainSteps
of the runbook.The first action starts a rate control automation using the child runbook she just created that targets instances associated with the tag specified in the
PatchGroupPrimaryKey
andPatchGroupPrimaryValue
input parameters. She uses the values provided to the input parameters to specify the key and value of the tag associated with the primary group of database instances she wants to patch.After the first automation completes, the second action starts another rate control automation using the child runbook that targets instances associated with the tag specified in the
PatchGroupSecondaryKey
andPatchGroupSecondaryValue
input parameters. She uses the values provided to the input parameters to specify the key and value of the tag associated with the secondary group of database instances she wants to patch. -
Emily reviews the completed parent runbook content and creates the runbook in the same AWS account and AWS Region as the target instances. Now, she is ready to test her runbooks to make sure the automation operates as desired before implementing them into her production environment. The following is the completed parent runbook content.
For more information about the automation actions used in this example, see the Systems Manager Automation actions reference.