AWS DSC Toolkit

We have just released a brand new module called the AWS DSC Toolkit!
This module allows you to register AWS EC2 instances as DSC Nodes in Azure Automation.
You can then control your EC2 instances in Azure Automation using PowerShell DSC configurations.

The 4 new cmdlets provided by this module are:

• Register-EC2Instance
• Test-EC2InstanceRegistration
• Set-IAMInstanceProfileForRegistration
• Test-IAMInstanceProfileForRegistration

An example of these cmdlets is available here.

This module is currently in preview.
It is provided as is and is not supported through any Microsoft support program or service.

Installation

The AWS DSC Toolkit is available on the PowerShell Gallery.
You can install it using PSGet:

Install-Module AwsDscToolkit

The source code is also available on GitHub.

Credentials and Region

To use the cmdlets in this module, you will need to log in to your Azure account and provide AWS credentials as well as an AWS region.

You can easily log into your Azure account with this cmdlet:

Add-AzureRmAccount

By default, the cmdlets in this module will use the AWS credentials profile with the name ‘default’.

To specify the AWS credentials profile with the name ‘default':

Set-AWSCredentials -AccessKey 'MyAccessKey' -SecretKey 'MySecretKey' -StoreAs 'default'

To set the default AWS region:

Set-DefaultAWSRegion 'myRegion'

You can also specify your AWS credentials and region through the AwsAccessKey, AwsSecretKey, AwsProfile, and AwsRegion parameters on each of the cmdlets.

Register-EC2Instance

Registering a New Instance

To register a new instance to Azure Automation, use the Register-EC2Instance cmdlet with the New flag:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -New -InstanceProfile_Name 'MyInstanceProfileName' -SecurityGroup 'MySecurityGroup'

When the New flag is set, this cmdlet acts as a proxy for the AWS cmdlet New-EC2Instance. All parameters of New-EC2Instance are included in Register-EC2Instance -New except for those pertaining to user data (UserData, UserDataFile).

By default, Register-EC2Instance will create a t2.micro instance with the latest version of the AMI (Amazon Machine Image) with the name WINDOWS_2012R2_BASE.

Your new instance must have access to an AWS encryption key through the instance profile with the name specified by the InstanceProfile_Name parameter. For more information on this see the ‘IAM Instance Profile Requirements’ section below.

You new instance must also have a security group which will allow it to download the AWS DSC Bootstrapper and talk to Azure Automation. The default security create by this command will suffice:

New-EC2SecurityGroup -GroupName 'MySecurityGroup' -Description 'Security group for registration to Azure Automation'

This creates a default security with all outbound ports open and all inbound ports closed.

Registering an Existing Instance

To register an existing instance to Azure Automation, use the Register-EC2Instance cmdlet with the InstanceId parameter:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId'

Unfortunately, not all existing EC2 instances can be registered due to limitation with AWS permissions on existing instances. For more information on this, see the ‘Checking If an Existing Instance Can Register’ section.

Specifying a DSC Node Configuration at Registration Time

You can specify a DSC Node configuration on your Azure Automation account to apply to an EC2 instance immediately after registration using the NodeConfigurationName parameter:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId' -NodeConfigurationName 'MyConfiguration.Webserver'

You can also modify the behavior of DSC immediately after registration using the ConfigurationMode, ConfigurationModeFrequencyMins, RefreshFrequencyMins, RebootNodeIfNeeded, AllowModuleOverwrite, and ActionAfterReboot parameters.

By default these are set to the following values:

For more information on these values, see the PowerShell DSC documentation.

Test-EC2InstanceRegistration

This cmdlet will return an EC2InstanceRegistrationStatus enum value.
This new type is included with the module.

The 4 possible values are:

• CannotRegister
• NotReadyToRegister
• ReadyToRegister
• Registered

Checking If an Existing Instance Can Register

To check if your EC2 instance can register, use the Test-EC2InstanceRegistration cmdlet:

Test-EC2InstanceRegistration -InstanceId 'ExistingInstanceId'

If an Azure Automation account is not provided, this cmdlet will return CannotRegister, NotReadyToRegister, or ReadyToRegister.

CannotRegister

This value indicates that your instance does not have an IAM instance profile. AWS currently does not allow you to assign an IAM instance profile to an existing EC2 instance. To work around this, you can create an image of your existing instance and then create a new EC2 instance with an IAM instance profile from that image.

NotReadyToRegister

This value indicates that your instance has an IAM instance profile, but the instance profile does not have the correct permissions to register this instance. For more information on how to fix your IAM instance profile, see the ‘IAM Instance Profile Requirements’ section below.

Before a new instance created by Register-EC2Instance has finished registering, it may also return the NotReadyToRegister status since new instances do not require permission to use the AWS Run Commmand feature.

ReadyToRegister

This value indicates that the instance is correctly configured to register.
Before an existing instance has finished registering, it should return ReadyToRegister.

Checking If an Instance is Registered

To check if an instance is registered with your Azure Automation account, use the Test-EC2InstanceRegistration cmdlet with an Azure Automation account specified:

Test-EC2InstanceRegistration -AzureAutomationAccount 'MyAzureAutomationAccount' -InstanceId 'MyInstanceId'

This cmdlet will return an EC2InstanceRegistrationStatus enum value.

If the instance is registered, this value will be Registered.
If the instance is not registered or is still in the process of registering, it may return NotReadyToRegister or ReadyToRegister.

Please keep in mind that it usually takes about 10-20 minutes for an instance to register.
If you are using an instance that has an older WMF, it may take longer since the instance’s WMF will need to be updated to work with Azure Automation.

Registered

This value indicates that the instance is registered as a DSC node with the provided Azure Automation account.
Test-EC2InstanceRegistration will not check for the Registered status unless you provide an Azure Automation account.

IAM Instance Profile Requirements

In order to register any EC2 instance to Azure Automation, the Register-EC2Instance cmdlet will retrieve the registration key associated with your Azure Automation account. To keep this key safe, the cmdlet encrypts your key using an AWS encryption key associated with your AWS account. Any EC2 instances registering to Azure Automation Register-EC2Instance cmdlet must also have access to this encryption key in order to decrpyt your RegistrationKey. This access is given through an IAM instance profile.

In order to register an existing EC2 instance, the Register-EC2Instance cmdlet uses the AWS Run Command feature.
This means that to register an existing instance, the attached instance profile must have permission to use the Run Command feature. This is not required for instances created by the Register-EC2Instance cmdlet

Set-IAMInstanceProfileForRegistration

Once you have an encryption key on your AWS account, the Set-IAMInstanceProfileForRegistration cmdlet can create or modify an IAM instance profile to have the correct permissions to register a new or existing EC2 instance.

More information on how to create an encryption key is available here.

To modify or create a new IAM instance profile with the correct key access to register a new EC2 instance:

Set-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'

This will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile.

If an IAM instance profile with the name provided does not exist, this cmdlet will create one.
If the IAM instance profile with the name provided does exist, the profile will be modified with the proper permissions for registration.

The Set-IAMInstanceProfileForRegistration cmdlet will only provide access to Run Command when the ExistingInstance flag is set.
For example, to modify or create an IAM instance profile with access to encryption keys and permission to use run command:

Set-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance

If access has not already been granted, this will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile. This will also attached the AWS managed policy called ‘AmazonEC2RoleforSSM’ to a role in the specified instance profile.

This cmdlet returns an AWS IAM instance profile.

Test-IAMInstanceProfileForRegistration

To check if an IAM instance profile has the correct permissions to register a new EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet:

Test-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'

To check if an IAM instance profile has the correct permissions to register an existing EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet with the ExistingInstance flag:

Test-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance

This cmdlet will return a boolean value.
The permission to use Run Command may be removed from the instance profile once the instance has registered.