View a markdown version of this page

Migrate from Enhanced Container Insights (Classic) to OTel Container Insights - Amazon CloudWatch
PrerequisitesBreaking changesMigration stepsVerificationRollback

Migrate from Enhanced Container Insights (Classic) to OTel Container Insights

Both Enhanced Container Insights (Classic) and OTel Container Insights use the same amazon-cloudwatch-observability Amazon EKS add-on. The migration is an in-place add-on version update that you can complete in 15–30 minutes.

Warning

CloudWatch alarms configured with Classic metric names do not automatically work with OTel metrics. You must recreate alarms using PromQL-based alarm rules.

Prerequisites

Before you begin the migration, verify that you meet the following requirements.

  • An Amazon EKS cluster running Kubernetes version 1.28 or later

  • The amazon-cloudwatch-observability add-on installed and in ACTIVE status

  • AWS CLI version 2.15.0 or later

  • kubectl configured to communicate with your target cluster

  • An IAM role with the CloudWatchAgentServerPolicy managed policy attached

Breaking changes

Review the following breaking changes before you begin the migration.

Removed features

The following features are not available in OTel Container Insights:

  • StatsD custom metrics — Use the OTel StatsD receiver instead.

  • collectd plugin — Migrate to OTel-native instrumentation.

Changed defaults

The following table shows default values that change between Classic and OTel Container Insights.

Setting Classic default OTel CI default
Collection interval 60 seconds 60 seconds
Enhanced Observability Enabled Enabled
Agent CPU request 200m 100m
Agent memory request 200Mi 128Mi

Migration steps

This migration uses a phased approach to minimize monitoring gaps. You run both Classic and OTel metrics streams in parallel, validate the data, and then disable the Classic stream.

Phase 1: Confirm current state (Classic only)

Before you make changes, confirm your current add-on state and record the version for rollback.

To confirm your current add-on configuration

  1. Run the following command to check the current add-on status.

    aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability

  2. Verify that the status field is ACTIVE.

  3. Record the addonVersion value. You need this value if you must roll back.

Phase 2: Enable dual publishing (Classic + OTel)

Enable OTel Container Insights alongside Enhanced Container Insights (Classic). This publishes both metric streams simultaneously so that you can validate data equivalence.

Important

Both metric streams incur charges during this phase. We recommend keeping the dual publishing window as short as possible to minimize costs.

To enable dual publishing

  1. Run the following command to update the add-on with both streams enabled.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --addon-version latest-version \
  --configuration-values '{"containerInsights":{"enabled":true},"otelContainerInsights":{"enabled":true}}' \
  --resolve-conflicts OVERWRITE

  2. Wait for the add-on status to return to ACTIVE.

    aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status"

  3. Verify that OTel metrics appear in CloudWatch by querying a known metric with PromQL.

Phase 3: Recreate alarms and update dashboards

Build OTel replacements for your existing Classic alarms and dashboards. Keep Classic alarms active as a safety net during this phase.

To recreate alarms for OTel metrics

  1. Identify all CloudWatch alarms that reference Classic Container Insights metric names.

  2. Create equivalent alarms using PromQL-based metric math expressions that reference OTel metric names.

  3. Verify that the new alarms enter OK state and produce equivalent threshold evaluations.

  4. Update any CloudWatch dashboards to include widgets based on OTel metrics alongside the existing Classic widgets.

Phase 4: Disable Classic (switch to OTel only)

After you validate that OTel metrics, alarms, and dashboards work correctly, disable the Classic stream.

To disable Classic and keep OTel only

  1. Run the following command to disable Classic metrics publishing.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"containerInsights":{"enabled":false},"otelContainerInsights":{"enabled":true}}' \
  --resolve-conflicts OVERWRITE

  2. Wait for the add-on status to return to ACTIVE.

  3. Remove the Classic alarms that you replaced in Phase 3.

Verification

After you complete the migration, verify that your observability stack is working correctly.

  • Check metrics in Query Studio — Use PromQL queries to confirm that metrics flow from the OTel pipeline.

  • Compare with baseline values — Verify that metric values are consistent with the Classic metrics you recorded during Phase 2.

  • Verify Container Insights dashboards — Confirm that the Container Insights console displays data for your cluster.

  • Verify log delivery — Check that container logs continue to appear in CloudWatch Logs.

  • Verify alarms — Confirm that no alarms are in INSUFFICIENT_DATA state.

Rollback

If you encounter issues after migration, you can restore the previous Classic configuration.

To roll back to Enhanced Container Insights (Classic)

  1. Identify the previous add-on version that you recorded in Phase 1.

  2. Run the following command to downgrade the add-on.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --addon-version previous-version \
  --resolve-conflicts OVERWRITE

  3. Wait for the add-on status to return to ACTIVE.

    aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status"

  4. Re-apply any custom configuration values that you used with the previous version.