Use AWS Systems Manager Automation to create input parameters that populate AWS resources as a dropdown list

As a Solution Architect at AWS, my customers regularly ask how to automate everyday operations within their cloud environment. Their use cases include a variety of operational needs, such as provisioning new resources within an AWS account, and patching/updating managed Amazon Elastic Compute Cloud (Amazon EC2) instances. They are also focused on cost management with AWS, and seek solutions to turn on/off compute and database resources during non-business hours, or to implement standardized tags on their AWS resources for budgeting and reporting.

Application owners want the speed and agility of provisioning resources in the cloud. Still, they also must meet the security and compliance strategy set within their organization. Meanwhile, infrastructure and security teams are looking to emphasize proactive management and governance to offer application owners a secure and cloud-ready environment.

A common goal between application owners and infrastructure teams within your organization is to enable, provision, and operate AWS resources with automation capabilities across your environment. Therefore, your organization creates a provisioning and distribution process using infrastructure-as-code templates. When creating service templates, your organization may choose naming conventions across your AWS accounts. Furthermore, you may build templates with operational metadata tags and specific parameters to populate in alignment with security and governance guardrails.

Within AWS, you can build, run, and share Automation runbooks to enable AWS resource management using AWS Systems Manager Automation. An Automation runbook is a document in Systems Manager used for everyday maintenance and deployment tasks on your managed nodes or other AWS resources.

This post demonstrates how to create a Systems Manager Automation runbook. This displays pre-filtered AWS resources as a dropdown list for you to choose.

Introducing new parameter types within Systems Manager

Recently, AWS announced the ability to populate input parameters when creating Automation runbooks within Systems Manager. Systems Manager Automation runbooks let you safely automate common and repetitive IT operations and management tasks for your managed nodes and AWS resources. Automation runbooks are also used to automate incident management workflows. You can use Amazon-provided predefined runbooks or build, run, and share Automation runbooks across multiple AWS accounts.

This new release lets you define input parameters as a dropdown list when authoring Automation runbooks within the Systems Manager Document Builder. Previously, you needed additional steps to identify the ARN for AWS resources using the AWS Management Console, AWS Command Line Interface (AWS CLI), or AWS SDKs. This will accelerate the time to build Automation runbooks within your environment..

Optionally, you can filter the available AWS resources using a regular expression statement.

Moreover, the new parameter types can be selected when creating an Automation runbook using the Systems Manager Document Builder. The following figure shows our input parameter types from the Systems Manager Document Builder:

Figure 1. AWS Systems Manager Document Builder

You can select from a list of available resources in your AWS account when triggering an Systems Manager Automation using the console. This feature supports for Amazon EC2 instances, Amazon Simple Storage Service (Amazon S3) buckets, and AWS Identity and Access Management (IAM) roles. AWS plans to support additional resource types in the future.

Automation runbook syntax

Let’s break down the appropriate syntax of a Systems Manager Automation runbook used to populate AWS resources.

The following is a snippet of a Systems Manager Automation runbook using the updated Automation runbook syntax. In this case, you have added an Amazon S3 bucket, a list of multiple Amazon S3 buckets, an Amazon EC2 instance, and a list of multiple IAM roles as accepted parameters within the Automation runbook. The runbook’s execution references these parameters.

schemaVersion: '0.3'
parameters:
S3Bucket:
type: ‘AWS::S3::Bucket::Name’
allowedPattern: ^[0-9a-z][a-z0-9\-\.]{3,63}$|^$
description: ‘Optionally specified Amazon S3 bucket name to which to upload backup. For example, my-backup-bucket'
default: ''
S3Buckets:
type: ‘List<AWS::S3::Bucket::Name>’
allowedPattern: ^[0-9a-z][a-z0-9\-\.]{3,63}$|^$ 
InstanceId:
type: ‘AWS::EC2::Instance::Id’
description: Target SQL Server instance on which to perform the backup operation
IAMRoles:
type: 'List<AWS::IAM::Role::Arn>'
allowedPattern: '(.*:role/s3.*|.*s3)'
description: (Required) IAM Roles which will be granted access to the bucket.
mainSteps:
...

Here are the elements within our Automation runbook which make our dropdown list possible:

parameters are a top-level element within Systems Manager Automation runbooks. Each named parameter accepts a user-defined value during runbook execution.

type defines the data type that your users can enter for the given parameter. New type values have been introduced to populate AWS resources within a dropdown list automatically. You can allow users to choose a single AWS resource or a list of multiple AWS resources:

• AWS::EC2::Instance::Id
• List<AWS::EC2::Instance::Id>
• AWS::S3::Bucket::Name
• List<AWS::S3::Bucket::Name>
• AWS::IAM::Role::Arn
• List<AWS::IAM::Role::Arn>

See AWS documentation for a current list of type values that support the new feature. You can still use other data types, such as String, StringList, Integer, Boolean, MapList, and, StringMap.

Optionally, allowedPattern can be used to filter the available resources using a regular expression statement. This field supports the Google re2 regex syntax, which doesn’t include support for Lookahead and Lookbehind assertions.

Another option is description, which is a description of the parameter.

Using Systems Manager Automation

Using the new parameter types, let’s create a new Systems Manager Automation runbook. Then, you’ll fire off Automation within the console so that you can view your parameters as a dropdown list.

Let’s consider the use case where you would like to enable server-side encryption on an Amazon S3. You can use the AWS-provided runbook AWS-EnableS3BucketEncryption. You can also write a custom Automation runbook similar to the following. New type parameters include letting your user choose an existing Amazon S3 bucket or create a new one.

description: Enables Encryption on S3 Bucket
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
BucketName:
type: 'AWS::S3::Bucket::Name'
description: (Required) The name of the Amazon S3 bucket whose content will be encrypted.
SSEAlgorithm:
type: String
description: (Optional) Server-side encryption algorithm to use for the default encryption.
default: AES256
AutomationAssumeRole:
type: 'AWS::IAM::Role::Arn'
description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
default: ''
mainSteps:
- name: PutBucketEncryption
action: 'aws:executeAwsApi'
inputs:
Service: s3
Api: PutBucketEncryption
Bucket: '{{BucketName}}'
ServerSideEncryptionConfiguration:
Rules:
- ApplyServerSideEncryptionByDefault:
SSEAlgorithm: '{{SSEAlgorithm}}'
isEnd: true

Prerequisites

• You’ll need an IAM user with permissions to build and execute the Systems Manager Automation runbook. Using an IAM administrator user in the following steps. You can optionally configure user access to Automation using an IAM user with the AWS managed policy AmazonSSMFullAccess.
• Optionally, if your user creates or selects an AutomationAssumeRole, then the role must be assumable by Systems Manager. Your end-user must have pass-role permissions for that role when they execute the Automation runbook. Furthermore, that role must have whatever permissions the Automation runbook requires. In this example, the role will need an inline policy to invoke the s3:PutBucketEncryption API for the Amazon S3 bucket. Suppose they decide not to include this parameter. In that case, the resulting automation workflow will use the context of the user who invoked the automation.
• Choose an Amazon S3 bucket where you would like to enable server-side encryption with Amazon S3-managed encryption keys (SS3-S3). Moreover, you can create a new Amazon S3 bucket when executing the Systems Manager Automation runbook within the console.

Creating a Systems Manager Automation runbook using the console

Open the Systems Manager console, find the Shared Resources section on the left-side navigation, and select Documents.

Figure 2. AWS Systems Manager navigation pane

You can see all of your documents. Initially, you can view and edit documents created by Amazon or create your own documents. A Systems Manager Automation runbook is a type of document within Systems Manager. Learn more about the Systems Manager document types within AWS Documentation: AWS Systems Manager documents.

Let’s clone the AWS-provided document AWS-EnableS3BucketEncryption to see the dropdown list in action.

Select the tab Owned by Amazon. You can search for the document by keyword or search through the documents as they appear on your screen – whichever option is easier for you.

Figure 3. AWS Systems Manager Documents

Select the radio button next to the document AWS-EnableS3BucketEncryption. Then, select Actions > Clone Document.

Figure 4. AWS Systems Manager Documents Actions

Choose a Name for your document under Document details. I’m going to use the name ‘ResourceType-AWS-EnableS3BucketEncryption’.

Figure 5. AWS Systems Manager Document details – Name

Under Document attributes, navigate to Input parameters – optional, and select the dropdown arrow.

Look for the Parameter name called ‘BucketName'.

For Type, choose the option 'AWS::S3::Bucket::Name'. This choice will allow your users to select an Amazon S3 bucket from their AWS account or create a new one.

Figure 6. AWS Systems Manager Document details – Input parameters

Next, navigate to the Parameter name called ‘AutomationAssumeRole’.

For Type, choose the option ‘AWS::IAM::Role::Arn'. This choice will allow our users to select an IAM bucket from their AWS account. This type will let the automation update the properties of your Amazon S3 bucket.

Navigate to the bottom of your screen, and select Create automation once you’re ready to proceed.

Figure 7. AWS Systems Manager document – Create automation

Similarly, you can create the Automation runbook using an AWS CLI command:

aws ssm create-document --content file://EnableS3BucketEncryption.yaml \
--name "ResourceType-EnableS3BucketEncryption" \
--document-type Automation \
--document-format YAML \

Executing a Systems Manager Automation runbook using the console

You must create an IAM service role for automation, known as an AutomationAssumeRole, before you execute our Systems Manager Automation runbook. Follow the instructions in AWS documentation to create a service role for Automation.

Your service role for automation will also need an inline policy to let it perform the s3:PutBucketEncryption API for the Amazon S3 bucket. You can use the JSON Policy document similar to the following when setting up your IAM service role. Replace the ARN in red with the ARN of your Amazon S3 bucket:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutEncryptionConfiguration"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET"
        }
    ]
}

Let’s execute our newly created Automation runbook to see our dropdown list in action. Open the Systems Manager console, find the Change Management section on the left-side navigation, and select Automation.

Figure 8. AWS Systems Manager navigation pane

On this page, I see all of the previous executions of my Automation runbooks. Select Execute automation.

Figure 9. AWS Systems Manager Automation – Execute automation

Let’s search for the Automation runbook you created in the previous section. Select the tab Owned by me. You can search for the document by keyword or search through the documents as they appear on your screen – whichever option is easier for you.

Select the radio button next to the document that you created earlier. I’m looking for the document ‘ResourceType-AWS-EnableS3BucketEncryption’. Then, select Next at the bottom of your screen.

For Input Parameters, choose the BucketName where you’d like to enable server-side encryption (SS3-S3).

Optionally, choose the AutomationAssumeRole that you created earlier. If none is selected, then Systems Manager will use the context of your current IAM principal.

Select Execute on the bottom of your screen once you’re finished. You’ll be taken to your execution detail, where you can review the executed steps from your automation.

Figure 10. AWS Systems Manager Automation – Executed steps

Similarly, you can also execute this automation by following AWS CLI command. Replace the values in red with your own Amazon S3 bucket name and the ARN of your AutomationAssumeRole.

aws ssm start-automation-execution --document-name ResourceType-AWS-EnableS3BucketEncryption \
--parameters "BucketName=DOC-EXAMPLE-BUCKET, AutomationAssumeRole= arn:aws:iam::123456789012:role/AmazonSSMAutomationRole"

Cleanup

To delete the document you just created, open the Systems Manager console, find the Shared Resources section on the left-side navigation, and select Documents.

Select the tab Owned by me, then enter a keyword or navigate to the document on your screen. Left-click the radio button next to the document that you created. I’m looking for the document ‘ResourceType-AWS-EnableS3BucketEncryption’.

Under Actions, select Delete document. You’ll see a confirmation screen appear. Select Delete once you’ve reviewed that the correct Document name is selected.

To delete the IAM service role for automation, open the IAM console, find the Access management section on the left-side navigation, and select Roles.

Search for the name of the IAM role that you created earlier. Left-click the checkbox next to the IAM Role, then select Delete on the upper right-hand portion of your screen.

Figure 11. AWS Identity and Access Management Roles

Enter the role name in the text input field to confirm the deletion.

Conclusion

This post reviewed how you can select from a list of available resources in your AWS account when triggering a Systems Manager Automation using the console. You created a custom Automation runbook using the Amazon-provided AWS-EnableS3BucketEncryption as a starting point. Furthermore, you edited the automation to let your end-users select their own Amazon S3 bucket and IAM service role for automation.

You can find more information about this feature within AWS Documentation: Creating input parameters that populate AWS resources.

Head over to the AWS Well-Architected Management and Governance Lens to learn prescriptive guidance on implementing the event, incident, and problem management across your environment.

Want to learn more about creating Automation runbooks in Systems Manager? Head over to AWS Documentation: Creating SSM documents. Finally, reach out to your local AWS account team if you’d like to gain hands-on experience with Systems Manager Automation capabilities to simplify repeatable operations and resource provisioning.

Author: