Using AWS Systems Manager to orchestrate PowerShell DSC

This is the second part in a two-part series discussing the updates within the Microsoft Active Directory Domain Services Quick Start. In the first part, we discussed how and why we use AWS Systems Manager with AWS CloudFormation to centralize logs.

In this part, we will discuss how you can integrate Windows PowerShell Desired State Configuration (PowerShell DSC) with AWS Systems Manager to reduce the number of steps. We will focus on the Run Command documents that we used within the Automation document for the Active Directory Domain Services Quick Start, the Start-DscConfiguration cmdlet and the options used with it to output logs, and the orchestration of reboots on Amazon Elastic Compute Cloud (Amazon EC2) instances.

Streamlining the number of steps

Prior to the update, the Active Directory Domain Services Quick Start orchestrated 48 steps to install and configure Active Directory. We wanted to reduce the number of steps and improve orchestration between steps and reboots. To reduce steps, we knew we needed to use scripting that allowed us to declare the end state of our server as opposed to defining each individual step in the configuration.

Using PowerShell DSC allows you to reduce the number of scripts and steps by combining them. The workflow that we used consists of 12 steps to deploy AD on Amazon EC2 instances.

Systems Manager document types and actions

Systems Manager has different document types you can use. Within the Active Directory Domain Services Quick Start, we use two types, an Automation document and Run Command documents. The Systems Manager Automation document defines actions to perform. One of those actions is aws:executeAwsApi, which we use to make native API calls to AWS services. The aws:executeAWSApi action gets instance IDs, and it signals AWS CloudFormation of the failure or success of the Automation document. The other action we use is the aws:runCommand action, which runs the commands that are in the Systems Manager command documents against a set of Amazon EC2 instances.

We will now consider the two Run Command documents used throughout the Automation document in the Quick Start.

AWS-RunRemoteScript – Download and execute

The AWS-RunRemoteScript Run Command document is integral to reducing the number of steps, because it combines downloading the script and executing the script into a single step. Figure 2 shows a section of code that you can find within the Automation document for the Active Directory Domain Services Quick Start.

Figure 2: The aws:runCommand action for AWS-RunRemoteScript

In this Automation document step, we are generating the Managed Object Format (MOF) file that PowerShell DSC uses to configure the server as a domain controller.

The first arrow in Figure 2 points to the aws:runCommand action. The second and third arrows point to inputs that the aws:runCommand action requires. In this step, we use the AWS-RunRemoteScript Run Command document, and we target the InstanceID for domain controller (DC) 1. Note that this step is outputting logs to Amazon CloudWatch, as covered in our previous blog post.

The highlighted parameters section shows the parameters needed to successfully run this document, the location of the script, and the command line arguments to execute the script. In this case, the script resides in an Amazon Simple Storage Service (Amazon S3) bucket, but it could also be in a GitHub repository.

AWS-RunPowerShellScript – Process config and rebooting

After we have the MOF file generated, we need to process the configuration in the MOF file by using the AWS-RunPowerShellScript Run Command document to run the Start-DscConfiguration cmdlet. The highlighted blue section in the following screenshot shows the options used to run the Start-DscConfiguration cmdlet.

Figure 3: The aws:RunCommand action for AWS-RunPowerShellScript

Notice that the command is run with the Wait parameter. Typically, this parameter is used for testing because it blocks the console until the Start-DscConfiguration cmdlet finishes all configuration tasks. However, this parameter is important when running within a Systems Manager Automation document because it allows Systems Manager to be aware of the result. If we did not use the Wait parameter, the cmdlet would create a job that the Local Configuration Manager (LCM) would process in the background, and Systems Manager would be not be aware of the result.

The other option we use with the Start-DscConfiguration cmdlet is the Verbose option, which allows Systems Manager to output all information of the job to CloudWatch Logs.

As with Figure 2, the arrows in Figure 3 point to the action of the step, which is the aws:runCommand action, and the document and target instance ID. This step is uses the AWS-RunPowershellScript Run Command document, which executes a PowerShell script locally on the instance—or you can define a script to run, as we are doing here.

In addition to running the Start-DscConfiguration cmdlet, this short script includes a short function that orchestrates reboots, which is highlighted in yellow in Figure 3. As PowerShell DSC processes configuration, it might reach steps that require a reboot before it can continue. When this occurs, the LCM will go into a PendingConfiguration or PendingReboot state, and the DscStatusCheck function is run. The DscStatusCheck function checks for these states and, if they exist, exits with a status 3010. A status 3010 tells the Systems Manager Agent (SSM Agent) to reboot the instance and re-run the script that sent that status code.

Because in the Quick Start we use StopConfiguration for the ActionAfterReboot LCM property, we can now control processing configuration and reboot through Systems Manager with this step. When the instance matches the configuration of the MOF file, the LCM state will be idle, and this step will complete and move on to the next step in the Automation document. In the Active Directory Domain Services Quick Start, we perform this same pattern for DC1 and DC2.

AWS-ApplyDSCMofs – Another option

One of the things I like most about working within AWS is that there is never only one way to accomplish a task. In this post we covered the pattern that we used within the Active Directory Domain Services Quick Start. However, another option is the AWS-ApplyDSCMofs Systems Manager document, which applies MOF file to EC2 instances and allows you to use tokens to grab data from the Systems Manager parameter store, Amazon EC2 tags, or AWS Secrets Manager. You can find more information on this in the blog post Run compliance enforcement and view compliant and non-compliant instances using AWS Systems Manager and PowerShell DSC.

Conclusion

In this two-part blog series we covered the following:

• Using Systems Manager to push logs in the Quick Start to Amazon CloudWatch for ease of visibility
• Using AWS CloudFormation and AWS Systems Manager together to improve orchestration and configuration management in the AD Quick Start
• Orchestrating PowerShell DSC configuration with Systems Manager Automation documents and Run Command documents

I hope that you can experiment and start using these same patterns when deploying your workloads. I also hope that these improvements make it easier to use this Quick Starts within your environment or as reference patterns.