AWS Security ChangesHomeSearch

AWS AmazonCloudWatch: CloudWatch agent troubleshooting: IMDSv2 hop limit and config updates

Service: AmazonCloudWatch · 2026-11-21 · Documentation medium

File: AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.md · Type: iam

Summary

Updates the CloudWatch agent troubleshooting guide: relaxes the SSM Agent version requirement wording, clarifies the agent configuration file naming and the OpenTelemetry/Classic namespace behavior (PromQL in Query Studio), rewrites the container hop-limit/IMDSv2 error section to recommend setting hop limit to 2 or using EKS Pod Identity / IAM roles for service accounts, removes the aws_sdk_log_level version constraint, and refreshes several cross-reference links and labels.

Security assessment

The only security-relevant edit is the rewritten container hop-limit section, which explains that the agent reads IMDSv2 from inside containers and advises raising the IMDS hop limit to 2 or, preferably, using EKS Pod Identity / IAM roles for service accounts (scoped credential delivery instead of instance metadata). This is security-adjacent hardening guidance about instance metadata and credential access, not a fix for a specific vulnerability or incident, and no CVE/advisory is referenced.

Evidence

+This happens when the agent reads the instance metadata service (IMDSv2) from inside a container and the instance's hop limit is 1. Set the hop limit to 2, or use EKS Pod Identity or IAM roles for service accounts. For more information, see [Installing the CloudWatch agent on Amazon EKS](./CloudWatch-Agent-common-scenarios.html#CloudWatch-Agent-install-on-eks) and [Modify instance metadata options for existing instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-existing-instances.html) in the _Amazon EC2 User Guide_.

Diff

diff --git a/AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.md b/AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.md
index 1adf373..14f1fc6 100644
--- a//AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.md
+++ b//AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.md
@@ -76 +76 @@ To see the full list of parameters supported by the CloudWatch agent, enter the
-To install the CloudWatch agent using Systems Manager Run Command, the SSM Agent on the target server must be version 2.2.93.0 or later of the SSM Agent agent. If your SSM Agent isn't the correct version, you might see errors that include the following messages:
+To install the CloudWatch agent using Systems Manager Run Command, the SSM Agent on the target server must be a current version. If SSM Agent is out of date, you might see errors that include the following messages:
@@ -173 +173 @@ If the CloudWatch agent has been running but you can't find metrics collected by
-When you first download the CloudWatch agent package, the agent configuration file is `amazon-cloudwatch-agent.json`. This file is in the directory where you ran the configuration wizard, or you might have moved it to a different directory. If you use the configuration wizard, the agent configuration file output from the wizard is named `config.json`. For more information about the configuration file, including the `namespace` field, see [CloudWatch agent configuration file: Metrics section](./CloudWatch-Agent-Configuration-File-Details.html#CloudWatch-Agent-Configuration-File-Metricssection). 
+If you use the `opentelemetry` section, metrics aren't published in a namespace. Query them with PromQL in Query Studio. For the metric names, see [Host metrics that the agent collects](./CloudWatch-Agent-OpenTelemetry-config-collect-host-metrics.html#CloudWatch-Agent-OpenTelemetry-config-host-metrics).
@@ -175 +175 @@ When you first download the CloudWatch agent package, the agent configuration fi
-## The CloudWatch agent takes a long time to run in a container or logs a hop limit error
+The agent configuration file is the file that you pass to the `fetch-config` command. If you used the configuration wizard, the file is named `config.json` by default. For more information about the configuration file, including the `namespace` field, see [CloudWatch agent configuration file: Metrics section](./CloudWatch-Agent-Configuration-File-Details.html#CloudWatch-Agent-Configuration-File-Metricssection). 
@@ -177 +177 @@ When you first download the CloudWatch agent package, the agent configuration fi
-When you run the CloudWatch agent as a container service and want to add Amazon EC2 metric dimensions to all metrics collected by the agent, you might see the following errors in version v1.247354.0 of the agent:
+## The CloudWatch agent takes a long time to run in a container or logs a hop limit error
@@ -178,0 +179 @@ When you run the CloudWatch agent as a container service and want to add Amazon
+When you run the agent in a container and it adds Amazon EC2 metadata to the telemetry, the agent might start slowly or log errors such as the following:
@@ -180,6 +180,0 @@ When you run the CloudWatch agent as a container service and want to add Amazon
-    2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Unable to retrieve Instance Metadata Tags. This plugin must only be used on an EC2 instance.
-    2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Please increase hop limit to 2 by following this document https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#configuring-IMDS-existing-instances.
-    2022-06-07T03:36:11Z E! [telegraf] Error running agent: could not initialize processor ec2tagger: EC2MetadataRequestError: failed to get EC2 instance identity document
-    caused by: EC2MetadataError: failed to make EC2Metadata request
-            status code: 401, request id: 
-    caused by:
@@ -187 +182 @@ When you run the CloudWatch agent as a container service and want to add Amazon
-You might see this error if the agent tries to get metadata from IMDSv2 inside a container without an appropriate hop limit. In versions of the agent earlier than v1.247354.0, you can experience this issue without seeing the log message. 
+    E! [processors.ec2tagger] ec2tagger: Please increase hop limit to 2
@@ -189 +184 @@ You might see this error if the agent tries to get metadata from IMDSv2 inside a
-To solve this, increase the hop limit to 2 by following the instructions in [ Configure the instance metadata options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#configuring-IMDS-existing-instances.).
+This happens when the agent reads the instance metadata service (IMDSv2) from inside a container and the instance's hop limit is 1. Set the hop limit to 2, or use EKS Pod Identity or IAM roles for service accounts. For more information, see [Installing the CloudWatch agent on Amazon EKS](./CloudWatch-Agent-common-scenarios.html#CloudWatch-Agent-install-on-eks) and [Modify instance metadata options for existing instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-existing-instances.html) in the _Amazon EC2 User Guide_.
@@ -211 +206 @@ Agent configuration validation file. |  `/opt/aws/amazon-cloudwatch-agent/logs/c
-The JSON file used to configure the agent immediately after the wizard creates it. For more information, see [Create the CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). |  `/opt/aws/amazon-cloudwatch-agent/bin/config.json` |  `$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\config.json`  
+The JSON file used to configure the agent immediately after the wizard creates it. For more information, see [Create the Classic CloudWatch agent configuration file](./create-cloudwatch-agent-configuration-file.html). |  `/opt/aws/amazon-cloudwatch-agent/bin/config.json` |  `$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\config.json`  
@@ -248 +243 @@ You can configure the agent to log additional details in the `amazon-cloudwatch-
-In versions 1.247350.0 and later of the CloudWatch agent, you can optionally set the `aws_sdk_log_level` field in the `agent` section of the agent configuration file to one or more of the following options. Separate multiple options with the `|` character.
+You can optionally set the `aws_sdk_log_level` field in the `agent` section of the agent configuration file to one or more of the following options. Separate multiple options with the `|` character.
@@ -263,2 +257,0 @@ In versions 1.247350.0 and later of the CloudWatch agent, you can optionally set
-For more information about these options, see [LogLevelType](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType).
-
@@ -307 +300 @@ On a server running Windows Server, enter the following in PowerShell as an admi
-To restart the agent, follow the instructions in [(Optional) Modify the common configuration and named profile for CloudWatch agent](./installing-cloudwatch-agent-ssm.html#CloudWatch-Agent-profile-instance-fleet).
+To restart the agent, follow the instructions in [Starting the CloudWatch agent](./start-CloudWatch-Agent-on-premise-SSM-onprem.html).
@@ -321 +314 @@ If metrics or logs are not appearing in the CloudWatch console, follow this diag
-  * Confirm that the exact log group name and Region that the agent targets match where you are looking in the console. Check the agent's configuration file for `region`, `log_group_name`, and `namespace` values.
+  * Confirm that the exact log group name and Region that the agent targets match where you are looking in the console. Check the agent's configuration file for `region`, `log_group_name`, and, in the Classic configuration, `namespace` values. In the OpenTelemetry configuration, metrics have no namespace. Query them with PromQL in Query Studio.
@@ -385 +378 @@ CloudWatch agent credentials preference
-Embedding metrics within logs
+CloudWatch pipelines