AWS AmazonCloudWatch: CloudWatch agent SSM install: IAM scoping and VPC endpoint notes
Summary
Reorganizes the CloudWatch agent SSM installation guide: removes the duplicate TOC entry and the 'install on additional EC2 instances' section, relaxes the SSM Agent version requirement to 'a current version', adds a note to create an interface VPC endpoint for com.amazonaws.<region>.xray when sending traces/Application Signals, adds guidance that the Parameter Store parameter name must start with 'AmazonCloudWatch-' because CloudWatchAgentServerPolicy can only read those, replaces the inline common-config.toml credential/proxy documentation with a link, and updates several cross-reference links and the Version field instruction.
Security assessment
The added line documents least-privilege IAM behavior: the CloudWatchAgentServerPolicy managed policy can read only Parameter Store parameters prefixed with 'AmazonCloudWatch-', guiding users to scope agent config storage to what the role permits. The new xray interface endpoint note is network-reachability guidance (traces dropped without it), and the removal of the inline common-config.toml credential/proxy text is a doc consolidation (content moved to another page), not a fix for a specific vulnerability or incident.
Evidence
+ 8. In the **Optional Configuration Location** box, enter the name of the Parameter Store parameter that contains your agent configuration file. The name must start with `AmazonCloudWatch-`, because the `CloudWatchAgentServerPolicy` managed policy can read only those parameters. To create the file, see [Create a CloudWatch agent configuration for OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-config.html) or [Create the Classic CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html).
Diff
diff --git a/AmazonCloudWatch/latest/monitoring/installing-cloudwatch-agent-ssm.md b/AmazonCloudWatch/latest/monitoring/installing-cloudwatch-agent-ssm.md index 1ec218b..5b0accd 100644 --- a//AmazonCloudWatch/latest/monitoring/installing-cloudwatch-agent-ssm.md +++ b//AmazonCloudWatch/latest/monitoring/installing-cloudwatch-agent-ssm.md @@ -7 +7 @@ -Install or update SSM AgentVerify Systems Manager prerequisitesVerify internet accessVerifying VPC endpoint prerequisites for private subnetsDownload the CloudWatch agent package to your first instanceCreate and modify the agent configuration fileInstall the CloudWatch agent on EC2 instancesInstall the CloudWatch agent on EC2 instances(Optional) Modify the common configuration and named profile for CloudWatch agent +Install or update SSM AgentVerify Systems Manager prerequisitesVerify internet accessVerifying VPC endpoint prerequisites for private subnetsDownload the CloudWatch agent package to your first instanceCreate and modify the agent configuration fileInstall the CloudWatch agent on EC2 instances(Optional) Modify the common configuration and named profile for CloudWatch agent @@ -27,2 +26,0 @@ Using AWS Systems Manager makes it easier to install the CloudWatch agent on a f - * Install and start the CloudWatch agent on additional EC2 instances using your agent configuration - @@ -38 +36 @@ Using AWS Systems Manager makes it easier to install the CloudWatch agent on a f -On an Amazon EC2 instance, the CloudWatch agent requires that the instance is running version 2.2.93.0 or later of the SSM Agent. Before you install the CloudWatch agent, update or install SSM Agent on the instance if you haven't already done so. +On an Amazon EC2 instance, the CloudWatch agent requires that the instance is running a current version of SSM Agent. Before you install the CloudWatch agent, update or install SSM Agent on the instance if you haven't already done so. @@ -90,0 +89,2 @@ To download the agent package, also create a gateway endpoint for `com.amazonaws +If you send traces or use Application Signals, also create an interface endpoint for `com.amazonaws.`region`.xray`. Without it, the agent can't reach the traces OTLP endpoint and drops the traces that it receives. + @@ -122 +122 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run - 5. In the **Targets** area, choose the instance to install the CloudWatch agent on. If you don't see a specific instance, it might not be configured as a managed instance for use with Systems Manager. For more information, see [Setting Up AWS Systems Manager for Hybrid Environments](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-managedinstances.html) in the _AWS Systems Manager User Guide_. + 5. In the **Targets** area, choose the instance to install the CloudWatch agent on. If you don't see a specific instance, it might not be configured as a managed instance for use with Systems Manager. For more information, see [Managing nodes in hybrid and multicloud environments with Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-hybrid-multicloud.html) in the _AWS Systems Manager User Guide_. @@ -128 +128 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run - 8. Keep **Version** set to **latest** to install the latest version of the agent. + 8. Leave **Version** blank to install the latest version of the agent. @@ -141,27 +141 @@ After you have downloaded the CloudWatch agent, you must create the configuratio -If you're going to save your agent configuration file in the Systems Manager Parameter Store, you must use an EC2 instance to save to the Parameter Store. Additionally, you must first attach to that instance the `CloudWatchAgentAdminRole` IAM role. For more information about attaching roles, see [Attaching an IAM Role to an Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/iam-roles-for-amazon-ec2.html#attach-iam-role) in the _Amazon EC2 User Guide_. - -For more information about creating the CloudWatch agent configuration file, see [Create the CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). - -## Install and start the CloudWatch agent on additional EC2 instances using your agent configuration - -After you have a CloudWatch agent configuration saved in Parameter Store, you can use it when you install the agent on other servers. - -For each of these servers, follow the steps listed previously in this section to verify the Systems Manager prerequisites, the version of the SSM Agent, and internet access. Then use the following instructions to install the CloudWatch agent on the additional instances, using the CloudWatch agent configuration file that you have created. - -**Step 1: Download and install the CloudWatch agent** - -To be able to send the CloudWatch data to a different Region, make sure that the IAM role that you attached to this instance has permissions to write the CloudWatch data in that Region. - -Following is an example of using the `aws configure` command to create a named profile for the CloudWatch agent. This example assumes that you are using the default profile name of `AmazonCloudWatchAgent`. - -###### To create the AmazonCloudWatchAgent profile for the CloudWatch agent - - * On Linux servers, type the following command and follow the prompts: - - sudo aws configure --profile AmazonCloudWatchAgent - -On Windows Server, open PowerShell as an administrator, type the following command and follow the prompts. - - aws configure --profile AmazonCloudWatchAgent - - +If you're going to save your agent configuration file in the Systems Manager Parameter Store, you must use an EC2 instance to save to the Parameter Store. Additionally, you must first attach to that instance the `CloudWatchAgentAdminRole` IAM role. For more information about attaching roles, see [Attach an IAM role to an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/attach-iam-role.html) in the _Amazon EC2 User Guide_. @@ -168,0 +143 @@ On Windows Server, open PowerShell as an administrator, type the following comma +For more information about creating the CloudWatch agent configuration file, see [Create the Classic CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). @@ -205 +180 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run -On all supported operating systems, you can download the CloudWatch agent package using either Systems Manager Run Command or an Amazon S3 download link. +On all supported operating systems, you can download the CloudWatch agent package using either Systems Manager Run Command or an Amazon S3 download link. For information about using an Amazon S3 download link, see [Download the CloudWatch agent package](./download-CloudWatch-Agent-on-EC2-Instance-commandline-first.html). @@ -227 +202 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run - 5. In the **Targets** area, choose the instance on which to install the CloudWatch agent. If you do not see a specific instance, it might not be configured for Run Command. For more information, see [Setting Up AWS Systems Manager for Hybrid Environments](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-managedinstances.html) in the _AWS Systems Manager User Guide_. + 5. In the **Targets** area, choose the instance on which to install the CloudWatch agent. If you do not see a specific instance, it might not be configured for Run Command. For more information, see [Managing nodes in hybrid and multicloud environments with Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-hybrid-multicloud.html) in the _AWS Systems Manager User Guide_. @@ -233 +208 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run - 8. Keep **Version** set to **latest** to install the latest version of the agent. + 8. Leave **Version** blank to install the latest version of the agent. @@ -268 +243 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run - 8. In the **Optional Configuration Location** box, enter the name of the Systems Manager parameter name of the agent configuration file that you created and saved to Systems Manager Parameter Store, as explained in [Create the CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). + 8. In the **Optional Configuration Location** box, enter the name of the Parameter Store parameter that contains your agent configuration file. The name must start with `AmazonCloudWatch-`, because the `CloudWatchAgentServerPolicy` managed policy can read only those parameters. To create the file, see [Create a CloudWatch agent configuration for OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-config.html) or [Create the Classic CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). @@ -281,50 +256 @@ If the AWS Systems Manager home page opens, scroll down and choose **Explore Run -The CloudWatch agent includes a configuration file called `common-config.toml`. You can use this file to optionally specify proxy and Region information. - -On a server running Linux, this file is in the `/opt/aws/amazon-cloudwatch-agent/etc` directory. On a server running Windows Server, this file is in the `C:\ProgramData\Amazon\AmazonCloudWatchAgent` directory. - -The default `common-config.toml` is as follows: - - - # This common-config is used to configure items used for both ssm and cloudwatch access - - - ## Configuration for shared credential. - ## Default credential strategy will be used if it is absent here: - ## Instance role is used for EC2 case by default. - ## AmazonCloudWatchAgent profile is used for onPremise case by default. - # [credentials] - # shared_credential_profile = "{profile_name}" - # shared_credential_file= "{file_name}" - - ## Configuration for proxy. - ## System-wide environment-variable will be read if it is absent here. - ## i.e. HTTP_PROXY/http_proxy; HTTPS_PROXY/https_proxy; NO_PROXY/no_proxy - ## Note: system-wide environment-variable is not accessible when using ssm run-command. - ## Absent in both here and environment-variable means no proxy will be used. - # [proxy] - # http_proxy = "{http_url}" - # https_proxy = "{https_url}" - # no_proxy = "{domain}" - -All lines are commented out initially. To set the credential profile or proxy settings, remove the `#` from that line and specify a value. You can edit this file manually, or by using the `RunShellScript` Run Command in Systems Manager: - - * `shared_credential_profile` – For on-premises servers, this line specifies the IAM user credential profile to use to send data to CloudWatch. If you keep this line commented out, `AmazonCloudWatchAgent` is used. - -On an EC2 instance, you can use this line to have the CloudWatch agent send data from this instance to CloudWatch in a different AWS Region. To do so, specify a named profile that includes a `region` field specifying the name of the Region to send to. - -If you specify a `shared_credential_profile`, you must also remove the `#` from the beginning of the `[credentials]` line. - - * `shared_credential_file` – To have the agent look for credentials in a file located in a path other than the default path, specify that complete path and file name here. The default path is `/root/.aws` on Linux and is `C:\\Users\\Administrator\\.aws` on Windows Server. - -The first example below shows the syntax of a valid `shared_credential_file` line for Linux servers, and the second example is valid for Windows Server. On Windows Server, you must escape the \ characters. - - shared_credential_file= "/usr/username/credentials" - - shared_credential_file= "C:\\Documents and Settings\\username\\.aws\\credentials" - -If you specify a `shared_credential_file`, you must also remove the `#` from the beginning of the `[credentials]` line. - - * Proxy settings – If your servers use HTTP or HTTPS proxies to contact AWS services, specify those proxies in the `http_proxy` and `https_proxy` fields. If there are URLs that should be excluded from proxying, specify them in the `no_proxy` field, separated by commas. - - - +To specify a named profile, proxy, or Region for the agent, edit `common-config.toml`. For the file contents and settings, see [(Optional) Modifying the common configuration and named profile for CloudWatch agent](./install-CloudWatch-Agent-on-premise.html#CloudWatch-Agent-profile-onprem). @@ -340 +266 @@ Manual installation on Amazon EC2 -Install the CloudWatch agent on on-premises servers +Install the CloudWatch agent on new instances using CloudFormation