AWS Cloud Operations Blog
Build AWS Systems Manager Automation runbooks using AWS CDK
AWS Systems Manager Automation runbooks let you deploy, configure, and manage AWS resources safely and at scale. You can use AWS-published runbooks or build your own to enable AWS resource management across multiple accounts and regions. The AWS Cloud Development Kit (AWS CDK v2) is an open-source framework that can build applications with the expressive power of a programming language.
Today, customers using CDK to author runbooks use lower constructs and custom tools to test these authored runbooks. Now, we’ve added high-level constructs to author runbooks and a capability to simulate runbook processing. This post will show how to use the AWS CDK to speed up runbook authoring and test it by locally simulating the processing.
Documents AWS CDK library overview
The Document CDK Library provides constructs for authoring Automation runbooks, Command documents, and simulation for locally testing Automation runbooks.
- The library is available in Maven, NuGet, NPM, and PyPI.
- Documents can export to either YAML or JSON.
- Build document constructs for repeat patterns or standardization.
- Locally simulate execution for existing YAML or JSON documents.
- Provides code completion for some development tools
Prerequisites
The examples in this post use Typescript. Before you get started, make sure you have the following prerequisites:
- An AWS account
- An instance of the AWS Cloud9 IDE or an alternative local development environment, such as your personal computer
- Install the following packages:
- Node Package Manager (npm)
- AWS CDK v2
- TypeScript (version 3.8 or later)
- Bootstrap CDK in your target AWS Account and region.
Creating the CDK application
Create the directory and navigate into that directory.
Next, initialize a new typescript application.
Install the document library that provides the L2 constructs and save the package.json file.
Updating the stack
In the lib sub-directory of the project, edit the automation-runbook-demo-stack.ts file and add the following import statements at the beginning of the file.
Next, you need to expose the runbook for testing. On a new line after the export class AutomationRunbookDemoStack extends cdk.Stack {
statement add the following line.
Directly underneath the call to super(scope, id, props);
paste in the following to create a function the runbook will invoke.
Create the runbook
The runbook will have one input and use an aws:branch step to evaluate if an aws:executeAwsApi
or aws:invokeLambdaFunction
step will execute. Paste the following code after the function.
Next, create three steps by pasting the following code after the new document.
Finally, paste the following to call the steps created in the previous step.
Save and exit the automation-runbook-demo-stack.ts file
Test the runbook
In the test
sub-directory of the project, edit the automation-runbook-demo.test.ts
file and replace the commented import
statements with the following.
When declaring a Simulation
, the library facilitates mocking API calls by assigning an instance of MockAwsInvoker
to the awsInvoker
property. This pattern allows testing of the runbook before deployment. Suppose the awsInvoker
property isn’t specified when you declare a Simulation
. In that case, operations route to the AWS API. Remove the existing test
statement and comments, then paste the following to test ‘API’ as the value of the Step
input.
Next, paste the following to test Script
as the value of the Step
input.
Save the automation-runbook-demo.test.ts file. Run the following command from the root of the project directory to perform the tests.
After successful tests, deploy the stack by running the following command.
Execute the Automation runbook
- In the AWS Systems Manager console, select Automation under Change Management.
- Click the Execute Automation button and select Owned by me tab.
- Select the myAutomationRunbook Automation runbook and select Next.
- Choose Simple execution.
- Navigate to the Action input parameter and select an option from the drop-down.
- Choose Execute.
- Cleanup
To remove the resources created with this application, run the following command.
Conclusion
This post demonstrated creating an Automation runbook using a custom CDK library. You also used the library to simulate and test the runbook before deployment. In addition to Automation runbooks, the library supports the creation of Command documents. The L2 constructs allow customers to build repeatable L3 constructs or patterns. The library is available in Maven, NuGet, NPM, and PyPI. Download today and start building!
About the author: