Monitoring Memory Metrics for EC2 Windows Instances
While Amazon CloudWatch provides CPU, network and disk usage metrics for Amazon EC2 instances, it doesn't provide memory usage metrics by default. Commander provides the ability to monitor memory usage through the use of custom CloudWatch scripts. When memory usage metrics are enabled for an instance:
- VM owners can monitor memory usage
- Commander can issue memory rightsizing recommendations for the VM
Note: Commander also detects and uses memory metrics for EC2 instances deployed in the AWS console.
This topic explains how to enable memory usage monitoring for new Amazon EC2 Windows instances deployed by Commander. See also Monitoring Memory Metrics for EC2 Linux Instances.
Commander supports memory metrics for the following Windows versions:
- Windows 2016 Base
- Windows 2012 R2
- Windows 2012 Base
- Windows 2008 Base
- Windows 2003 R2
Windows 2016 Nano isn't supported, because it has no CloudWatch plug-in.
- PowerShell v1.0 or higher: Commander runs a PowerShell script to monitor memory metrics, so PowerShell v1.0 or higher must be installed on the deployed Windows instance. You can download PowerShell from the Microsoft download site.
- SSM Agent: The Commander script requires any version of SSM Agent to be installed on the EC2 instance. SSM Agent is installed by default on Windows Server 2016 instances and instances created from Windows Server 2003-2012 R2 AMIs published in November 2016 or higher. If you created your own AMI and it doesn't include SSM Agent, see Installing SSM Agent in the AWS documentation.
- User data: User data execution must be enabled for the source AMI. In other words, the EC2UserDataPlugin field must be set to
<amazon_install_dir>/EC2Config/Settings/Config.xmlfile. If the source AMI was not configured to allow user data execution, you must enable it on the deployed VM. See Troubleshooting below.
When you enable memory usage monitoring for a new VM, during provisioning, Commander installs and runs a PowerShell script as AWS user data. The script is merged with any other user data configured for the new VM.
The PowerShell script which is run by Commander as user data during provisioning is stored in the following location on the Commander server:
The PowerShell script creates a new Simple Service Manager (SSM) Document called auto-enable-cloudwatch-Commander and associates it with the new instance. The SSM Document defines what information is sent to CloudWatch. The VM sends memory usage statistics to AWS every 15 minutes.
SSM Documents are region-specific. The PowerShell script automatically determines the region for the source AMI and replaces a string in the script with the proper region.
The two AWS memory metrics and their Commander equivalents are:
See Monitoring Amazon EC2 in the AWS documentation for more information.
To enable memory usage monitoring for new VMs, the following conditions must be met:
- Memory usage monitoring must be enabled. See Enable memory usage monitoring below.
- The deployed VM must have credentials that allow reading and writing CloudWatch data. See Assign credentials with CloudWatch permissions below.
To configure memory usage monitoring, enable the Monitor Memory Usage option for the service catalog entry. You can find this option on the Infrastructure tab of the Component Blueprint page, as shown below.
For more information, see Monitor Memory Usage(VM templates only).
- You can also enable memory usage monitoring during manual deployment.
- If you're using your own custom script to enable memory usage monitoring, you must disable memory usage monitoring in the service catalog blueprint.
The deployed VM must have credentials that allow reading and writing CloudWatch data.
Assigning an IAM role is the recommended method, to avoid the need for placing plain-text credentials in a script.
There are two ways to assign an IAM role during the Commander provisioning process:
- Assign the IAM role to the service catalog blueprint (see the image in the section above). See Adding AWS Services to the Catalog for more information.
- Assign the IAM role to the deployment destination. This option makes sense if you deploy the same template (AMI) to multiple deployment destinations, or if you have a large number of catalog entries. You can find the IAM Role option on the Resources & Security page of the Automated Deployment Placement wizard, as shown below.
Important: Commander doesn't validate IAM role names, so ensure that role names entered in Commander match those in AWS. IAM role names are not case-sensitive.
See Optionally, enter the name of an IAM Role to assign to the deployed VM. The maximum number of characters is 255. Configuring the IAM role in the deployment destination rather than in the catalog blueprint makes sense if you deploy the same template (AMI) to multiple deployment destinations, or if you have a large number of catalog entries. If an IAM role is also configured in the catalog blueprint, the blueprint takes precedence. Administrators can override the IAM role during manual deployment. Important: Commander doesn't validate IAM role names, so ensure that role names entered in Commander match those in AWS. IAM role names are not case-sensitive. for more information.
Note: If an IAM role is configured in both the deployment destination and the blueprint, the blueprint takes precedence.
Provisioning won't fail if you don't assign an IAM role through one of these methods, because it's possible to assign credentials through a script.
If user data execution was not allowed on the source AMI, the PowerShell monitoring script won't run during deployment, and memory metrics monitoring won't occur. You can enable user data execution after deployment, for example, by using Windows Sysprep to enable user data execution; see the Amazon EC2 documentation for more details.
To verify script execution and view script output, you can view the output log in the following location on the deployed VM: