# 从 Enhanced Container Insights（Classic）迁移到 OTel Container Insights
<a name="container-insights-eks-migrate-from-classic"></a>

Enhanced Container Insights（Classic）和 OTel Container Insights 均使用相同的 `amazon-cloudwatch-observability` Amazon EKS 附加组件。迁移是就地附加组件版本更新，可以在 15-30 分钟内完成。

**警告**  
配置了 Classic 指标名称的 CloudWatch 警报不会自动与 OTel 指标搭配使用。您必须使用基于 PromQL 的警报规则重新创建警报。

## 先决条件
<a name="container-insights-eks-migrate-from-classic-prereqs"></a>

开始迁移之前，请确认已满足以下要求。
+ 运行 Kubernetes 版本 1.28 或更高版本的 Amazon EKS 集群
+ `amazon-cloudwatch-observability` 附加组件已安装并处于 `ACTIVE` 状态
+ Amazon CLI 版本 2.15.0 或更高版本
+ 已配置 `kubectl` 以与目标集群通信
+ 附加了 `CloudWatchAgentServerPolicy` 托管策略的 IAM 角色

## 重大更改
<a name="container-insights-eks-migrate-from-classic-breaking"></a>

在开始迁移之前，请查看以下重大更改。

### 移除的功能
<a name="container-insights-eks-migrate-from-classic-removed"></a>

OTel Container Insights 不提供以下功能：
+ **StatsD 自定义指标**：改为使用 OTel StatsD 接收器。
+ **collectd 插件**：迁移到 OTel 原生埋点。

### 更改的默认值
<a name="container-insights-eks-migrate-from-classic-defaults"></a>

下表显示了 Classic 与 OTel Container Insights 之间变更的默认值。


| 设置 | Classic 默认值 | OTel CI 默认值 | 
| --- | --- | --- | 
| 收集间隔 | 60 秒 | 60 秒 | 
| 增强的可观测性 | 已启用 | 已启用 | 
| 代理 CPU 请求 | 200 m | 100 m | 
| 代理内存请求 | 200 Mi | 128 Mi | 

## 迁移步骤
<a name="container-insights-eks-migrate-from-classic-steps"></a>

此迁移采用分阶段的方法来最大限度地减少监控空白。可以并行运行 Classic 指标流与 OTel 指标流，验证数据，然后禁用经典版指标流。

### 第 1 阶段：确认当前状态（仅限 Classic）
<a name="container-insights-eks-migrate-from-classic-phase1"></a>

进行更改之前，请确认当前的附加组件状态并记录版本以便进行回滚。

**确认当前的附加组件配置**

1. 运行以下命令检查当前附加组件状态。

   ```
   aws eks describe-addon \
     --cluster-name {{cluster-name}} \
     --addon-name amazon-cloudwatch-observability
   ```

1. 确认 `status` 字段是否为 `ACTIVE`。

1. 记录 `addonVersion` 值。若必须回滚，则需要此值。

### 第 2 阶段：启用双重发布（Classic \+ OTel）
<a name="container-insights-eks-migrate-from-classic-phase2"></a>

启用 OTel Container Insights 以及 Enhanced Container Insights（Classic）。这会同时发布两个指标流，以便可以验证数据等价性。

**重要**  
在此阶段期间，两个指标流均会产生费用。建议尽可能缩短双重发布时段，最大限度地降低成本。

**启用双重发布**

1. 运行以下命令，在启用两个指标流的情况下更新附加组件。

   ```
   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
   ```

1. 等待附加组件状态恢复为 `ACTIVE`。

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

1. 通过 PromQL 查询已知指标，确认 OTel 指标是否显示在 CloudWatch 中。

### 第 3 阶段：重新创建警报并更新控制面板
<a name="container-insights-eks-migrate-from-classic-phase3"></a>

为现有的 Classic 警报和控制面板构建 OTel 替代方案。在此阶段期间，将 Classic 警报作为安全网保持活动状态。

**为 OTel 指标重新创建警报**

1. 确定所有引用 Classic Container Insights 指标名称的 CloudWatch 警报。

1. 使用基于 PromQL 的指标数学表达式创建等效警报，这些表达式引用 OTel 指标名称。

1. 确认新警报是否进入 `OK` 状态并生成等效的阈值评估。

1. 更新任何 CloudWatch 控制面板，在现有的 CloudWatch 小组件旁边加入基于 OTel 指标的小组件。

### 第 4 阶段：禁用 Classic（仅切换到 OTel）
<a name="container-insights-eks-migrate-from-classic-phase4"></a>

在验证 OTel 指标、警报和控制面板是否正常运行后，禁用 Classic 流。

**禁用 Classic 并仅保留 OTel**

1. 运行以下命令以禁用 Classic 指标发布。

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

1. 等待附加组件状态恢复为 `ACTIVE`。

1. 移除您在第 3 阶段替换的 Classic 警报。

## 验证
<a name="container-insights-eks-migrate-from-classic-verify"></a>

完成迁移后，请确认可观测性堆栈是否正常运行。
+ **在 Query Studio 中查看指标**：使用 PromQL 查询来确认指标是否来自 OTel 管道。
+ **与基准值比较**：确认指标值是否与您在第 2 阶段记录的 Classic 指标一致。
+ **验证 Container Insights 控制面板**：确认 Container Insights 控制台显示了集群数据。
+ **验证日志传送**：检查容器日志是否继续显示在 CloudWatch Logs 中。
+ **验证警报**：确认没有警报处于 `INSUFFICIENT_DATA` 状态。

## 回滚
<a name="container-insights-eks-migrate-from-classic-rollback"></a>

如果在迁移后遇到问题，可以恢复之前的 Classic 配置。

**回滚到 Enhanced Container Insights（Classic）**

1. 确定您在第 1 阶段记录的先前的附加组件版本。

1. 运行以下命令以将附加组件降级。

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

1. 等待附加组件状态恢复为 `ACTIVE`。

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

1. 重新应用您在先前版本中使用的任何自定义配置值。