Using Microsoft PowerShell DSC with Amazon EC2 Systems Manager

Amazon EC2 Systems Manager is a management service that helps you automatically collect software inventory, apply OS patches, create system images, and configure Windows and Linux operating systems. These capabilities help you define and track system configurations, prevent drift, and maintain software compliance of your EC2 and on-premises configurations.

By providing a management approach that is designed for the scale and agility of the cloud but extends into your on-premises data center, Systems Manager makes it easier for you to seamlessly bridge your existing infrastructure with AWS.

In this post, I show you how you can remotely manage your EC2 Windows instances using a declarative based model for instance configuration management at cloud scale. You use Microsoft PowerShell Desired State Configuration (DSC) to define a configuration and then apply it to your instances using Systems Manager.

Benefits

Systems Manager is built for cloud scale. It can handle applying your PowerShell DSC configuration to thousands of instances at one time.
Systems Manager allows you to send logs (stdout/stderr) offline. When you apply your configuration to an instance, you can have the logs sent directly to an Amazon S3 bucket. There is no need to log in to instances to retrieve logs.
Systems Manager works on your on-premises servers. There are some prerequisites required to get this to work. For more information, see Setting Up Systems Manager.

Microsoft DSC via Run Command

Systems Manager contains many tools, including Run Command. This tool allows you to execute a PowerShell DSC script on your instances remotely.

So how exactly does this work? Run Command uses command documents to accomplish tasks. There are many AWS managed public documents that you can choose from.

In this post, you use the document called AWS-InstallPowerShellModule. Run Command executes this document that downloads a PowerShell module contained within a zip file from the specified URL. It then allows you to issue commands. You issue commands that execute the cmdlets in the downloaded PowerShell Module.

Below is a diagram of the workflow.

Walkthrough

In this post, you can follow these steps using two different approaches:

AWS Management Console
PowerShell

Install IIS on Windows Server via Run Command using the AWS Management Console

In this section, I show you how to use Run Command to install IIS by executing a cmdlet from a PowerShell module on a target instance.

In the EC2 console, create a new Windows Server instance.
Choose Run Command, Run a Command.
Under Target Instance, select the newly created Windows instance. If the instance is not listed, you may need to wait until the instance is ready.
For Source, copy and paste the following URL. This PowerShell module is stored in Amazon S3 and was created by Amazon specifically for this post.
```
https://s3.amazonaws.com/aws-windows-samples-us-east-1/PSModules/SSMDevOps.zip
```

For Commands, copy and paste the following:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force
Import-Module SSMDevOps
Install-SsmDoIIS
Start-DscConfiguration -Path Install-SsmDoIIS -Wait

Choose Run.
Check the status of the Run Command execution.
Choose View Results or Command Id.
Choose Output, View Output.

Install IIS on Windows Server via Run Command using PowerShell

In this section, I show you how to accomplish the same thing programmatically.

On your local PC, download and install the latest version of the AWS Tools for Windows PowerShell.

Import the AWSPowerShell module.

if(-not (Get-Module -Name AWSPowershell)) 
{ 
    Import-Module AWSPowerShell
}

Open PowerShell and load your user profile.

Set-AWSCredentials –AccessKey <yourkey> -SecretKey <yourkey>

Set your AWS region to the region where your Windows Server instance is located. In this example, the region is set to us-east-1. Be sure to set the correct region for your environment.
```
Set-DefaultAWSRegion –Region us-east-1
```

Use Run Command to install IIS onto your instance. You need to update the instanceId with your instances instanceId.

$instanceId = 'Enter-your-instanceId' 
$source = 'https://s3.amazonaws.com/aws-windows-samples-us-east-1/PSModules/SSMDevOps.zip'
$commands = @(
  'Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force',
  'Import-Module SSMDevOps',
  'Install-SsmDoIIS',
  'Start-DscConfiguration -Path Install-SsmDoIIS -Wait'
)
$parameter = @{
  source = $source;
  commands = $commands;
}
$document = 'AWS-InstallPowerShellModule'
$cmd = Send-SSMCommand –InstanceId $instanceId –DocumentName $document –Parameter $parameter

Check the status of the Run Command execution.

$cmd = Get-SSMCommand –CommandId $cmd.CommandId
$cmd

Conclusion

Systems Manager offers a suite of tools to help you manage both your EC2 and on-premises instances. In this post, I showed you how you could use Run Command to remotely execute a PowerShell DSC script on your instances. In the next post in this series, I show you how to perform this same example using a different tool, Systems Manager State Manager.

About the Author

Shaun Breen is a Systems Development Engineer on the Amazon EC2 Windows team. The EC2 Windows team is responsible for producing Windows Server AMI’s and EC2 Systems Manager documents. Shaun enjoys developing solutions that makes AWS EC2 the best place to run Microsoft Windows Server in the cloud. When not working on EC2 Windows based solutions, he enjoys attending sporting events, coaching ice hockey, and spending time with his wife and three children.

AWS Cloud Operations Blog