Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

Managing Windows Instance Configuration

The Amazon EC2 Systems Manager (SSM) Config feature enables you to manage the configuration of your Windows instances while they are running. You create an SSM document, which describes configuration tasks (for example, installing software), and then associate the SSM document with one or more running Windows instances. The configuration agent on the instance processes the SSM document and configures the instance as specified.

If you disassociate an SSM document from an instance, this doesn't change the configuration of the instance. To change the configuration of an instance after you disassociate an SSM document, you must create a new SSM document that describes the configuration tasks (for example, uninstalling software), and then associate it with the instance.

To run scripts at instance launch only, consider using user data execution instead. For more information, see Executing Scripts with User Data.

For more complex automation scenarios, consider using AWS CloudFormation or AWS OpsWorks instead. For more information, see the AWS CloudFormation User Guide or the AWS OpsWorks User Guide.

Prerequisites

The EC2Config service processes SSM documents and configures the instance as specified. Download and install the latest version of the EC2Config service to each server you want to configure with SSM Config. For more information about how to install this service, see Installing the Latest Version of EC2Config.

Limitations

  • SSM Config is supported only for Windows instances.

  • SSM Config is available in the following regions.

To manage the configuration of your Windows instances using SSM Config, complete the following tasks.

Grant IAM Users Access to SSM Config

SSM documents run with administrative privilege on Windows instances because the EC2Config service runs in the Local System account. If a user has permission to execute any of the pre-defined SSM documents then that user also has administrator access to the instance. Delegate access to SSM Config and EC2 Run Command judiciously. This becomes extremely important if you create your own SSM documents. Amazon Web Services does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command actions at your own risk. As a security best practice, we recommend that you create low-level SSM documents for low security tasks and delegate access to non-administrators.

Prepare the Instance

SSM Config and Run Command have the same limitations, prerequisites, and IAM permission requirements. Prepare your environment as described in Systems Manager Prerequisites.

Create the JSON File

Open a text editor, add the JSON to describe the configuration, and then save the file with a .json file extension.

For more information about the structure of the JSON for an SSM document, see SSM document in the Amazon EC2 Systems Manager API Reference.

Example: Install Applications

The following JSON describes applications to install on the instance. For each application, source is the URL of its .msi file.

Copy
{ "schemaVersion": "1.0", "description": "Example instance configuration tasks", "runtimeConfig": { "aws:applications": { "properties": [ { "action": "Install", "source": "http://dev.mysql.com/get/Downloads/MySQLInstaller/mysql-installer-community-5.6.22.0.msi" }, { "action": "Install", "source": "https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi" }, { "action": "Install", "source": "http://download.winzip.com/winzip190-64.msi", "parameters": "INSTALLDIR=\"C:\\Program Files\\WinZipXX\"" } ] } } }

Example: Install PowerShell Modules and Run Commands

The following JSON describes PowerShell modules to install on your instance. For each module, source is the URL of the module and runCommand specifies the PowerShell command to run.

Copy
{ "schemaVersion": "1.0", "description": "Example instance configuration tasks", "runtimeConfig": { "aws:psModule": { "properties": [ { "description": "Example to install windows update PS module and install all .NET 4 updates.", "source": "https://gallery.technet.microsoft.com/scriptcenter/2d191bcd-3308-4edd-9de2-88dff796b0bc/file/41459/43/PSWindowsUpdate.zip", "runCommand": "Get-WUInstall -ServiceID 9482f4b4-e343-43b6-b170-9a65bc822c77 -Title \".NET Framework 4\" -AcceptAll" }, { "description": "Example to install chocolatey package provider and use it to install 7zip and GoogleChrome.", "runCommand": [ "$url = 'https://chocolatey.org/install.ps1'" , "iex ((new-object net.webclient).DownloadString($url))", "choco install -y 7zip", "choco install -y GoogleChrome" ] } ] } } }

Example: Join an AWS Domain

For information about using SSM Config to join a Windows instance to a directory, see Joining a Windows Instance to an AWS Directory Service Domain.

Example: Send Data to Amazon CloudWatch

For information about using SSM Config to send data to Amazon CloudWatch, see Use Systems Manager State Manager to Integrate an Instance and CloudWatch.

Create the SSM document

Use the AWS CLI or the Tools for Windows PowerShell to create a configuration document, specifying the JSON file that you created in the previous task.

AWS CLI

Use the following create-document command to name this configuration and make it available for use.

Copy
aws ssm create-document --content file://my-config.json --name "my-custom-config"

Tools for Windows PowerShell

Use the following New-SSMDocument command to name this configuration and make it available for use.

Copy
$doc = Get-Content my-config.json | Out-String New-SSMDocument -Content $doc -Name "my-custom-config"

Associate the SSM document with the Instance

Use the AWS CLI or the Tools for Windows PowerShell to associate a configuration document with an instance. You'll specify the name of the configuration document that you created in the previous task. An instance can be associated with one configuration document at a time. If you associate a configuration document with an instance that already has an associated configuration document, the new configuration document replaces the existing configuration document.

AWS CLI

Use the following create-association command to associate your configuration document with your Windows instance.

Copy
aws ssm create-association --instance-id i-1a2b3c4d --name "my-custom-config"

Tools for Windows PowerShell

Use the following New-SSMAssociation command to associate your configuration document with your Windows instance.

Copy
New-SSMAssociation -InstanceId i-1a2b3c4d -Name "my-custom-config"

Manually Apply the Configuration

If you need to ensure that your instance is configured as specified in its current SSM document, you can run the ec2config-cli tool on your instance as follows:

Copy
ec2config-cli --apply-configuration

Alternatively, you can use Windows Task Scheduler to run ec2config-cli periodically to ensure that your instance maintains this configuration.

You can verify that ec2config-cli is installed by checking for it in the C:\Program Files\Amazon\Ec2ConfigService directory. If you do not have ec2config-cli, you can get it by installing the current version of the EC2Config service. For more information, see Installing the Latest Version of EC2Config.

Disassociate the SSM document from the Instance

You can't update a configuration document after you create it. To associate a different configuration document with your instance, you can delete the existing association, and then associate a new configuration document with your instance. Note that terminating an instance does not automatically disassociate an associated configuration document.

AWS CLI

Use the following delete-association command to disassociate a configuration document from your Windows instance.

Copy
aws ssm delete-association --instance-id i-1a2b3c4d --name "my-custom-config"

Tools for Windows PowerShell

Use the following Remove-SSMAssociation command to disassociate a configuration document from your Windows instance.

Copy
Remove-SSMAssociation -InstanceId i-1a2b3c4d -Name "my-custom-config"

Delete the SSM document

When you are finished with a configuration document, you can delete it. You must disassociate the configuration document from any instances it is associated with before you can delete it.

AWS CLI

Use the following delete-document command to delete your configuration document.

Copy
aws ssm delete-document --name "my-custom-config"

Tools for Windows PowerShell

Use the following Remove-SSMDocument command to delete your configuration document.

Copy
Remove-SSMDocument -Name "my-custom-config"

Troubleshooting

This section includes information to help you troubleshoot problems with SSM Config.

Log4net Logging

The EC2Config service logs information in the following files using Apache log4net. The information in these files can help you troubleshoot problems.

  • C:\Windows\System32\winevt\Logs\EC2ConfigService.evtx

  • C:\Program Files\Amazon\Ec2ConfigService\Logs

  • LocalSystem %LOCALAPPDATA%

    • Windows Server 2008 or later

      C:\Windows\System32\config\systemprofile\AppData\Local\Amazon\Ec2Config\Logs\Ec2ConfigPluginFramework.txt

    • Windows Server 2003

      C:\Documents and Settings\Default User\Local Settings\Amazon\Ec2Config\InstanceData\Logs\Ec2ConfigPluginFramework.txt

You can enable extended logging by updating the log4net.config file. By default, the configuration file is located here:

C:\Program Files\Amazon\Ec2ConfigService\log4net.config

For more information about log4net configuration, see Apache log4net Manual - Configuration. For examples of log4net configurations, see Apache log4net Config Examples.

Windows Event Logs

The EC2Config service also logs information in a Windows Event log named Ec2ConfigService.

You can extract information from this event log to a log file by executing the following command from an elevated PowerShell command prompt:

Get-EventLog Ec2ConfigService | Sort-Object Index | Format-Table Message -AutoSize -Wrap | Out-File -Width 240 "C:\Program Files\Amazon\Ec2ConfigService\Logs\PluginFramework.txt"

If you want to log Windows Events to a log file with debugging enabled you must update the log4net.config file root element as follows: <root> <level value="DEBUG"/> <appender-ref ref="RollingFileAppender"/> <appender-ref ref="EventLogAppender"/> </root>

EC2 Console System Log

The following output in the EC2 console system log indicates that the EC2Config service was unable to connect to an SSM Config endpoint. These issues indicate problems with authorization and IAM role permissions, as noted in the following output messages:

Copy
Info: EC2Config configuration status:3;region:us-east-1;iam:0;authz:0 The output can help you troubleshoot the cause of the failure: configuration status:3: The calls to (SSM) failed. Ensure that you have granted the required IAM permissions to IAM users. (SSM) also requires an Internet connection from your instance.
Copy
iam:0: The instance was not launched with an IAM role. You cannot download documents if there is no IAM role/credentials associated with the instance.
Copy
authz:0: The instance is not authorized to access SSM. This happens if you launched the instance without an IAM role, or if the role associated with your instance does not have the necessary permissions to access the service.

You can troubleshoot specific reasons for an SSM document execution failure by checking the status of the association using the describe-association (AWS CLI) command or the Get-SSMAssociation (Tools for Windows PowerShell) command.