本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 升级到 Flink 2.2：完整指南
<a name="flink-2-2-upgrade-guide"></a>

本指南提供了将适用于 Apache Flink 的亚马逊托管服务 Flink 应用程序从 Flink 1.x 升级到 Flink 2.2 的 step-by-step说明。这是一次主要版本升级，其中包含重大更改，需要仔细规划和测试。

**主要版本升级是单向的**  
升级操作可以将您的应用程序从 Flink 1.x 移动到 2.2 并保留状态，但是在 2.2 状态下，您无法从 2.2 移动到 1.x。如果您的应用程序在升级后变得不健康，请使用 Rollback API 以最新快照中的原始 1.x 状态返回到 1.x 版本。

## 先决条件
<a name="upgrade-guide-prerequisites"></a>

在开始升级之前：
+ 回顾 [重大更改和弃用](flink-2-2.md#flink-2-2-breaking-changes)
+ 回顾 [Flink 2.2 升级的状态兼容性指南](state-compatibility.md)
+ 确保您有一个非生产环境进行测试
+ 记录您当前的应用程序配置和依赖关系

## 了解您的迁移路径
<a name="upgrade-guide-migration-paths"></a>

您的升级体验取决于您的应用程序与 Flink 2.2 的兼容性。了解这些路径有助于你做好适当的准备并设定切合实际的期望。

**路径 1：兼容的二进制文件和应用程序状态**

**预期发生的情况：**
+ 调用升级操作
+ 在应用程序状态过渡的情况下完成到 2.2 的迁移：`RUNNING`→ → `UPDATING` `RUNNING`
+ 保留所有应用程序状态，而不会丢失数据或重新处理数据
+ 与次要版本迁移相同的体验

最适合：无状态应用程序或使用兼容序列化的应用程序（Avro，兼容的 Protobuf 架构，不带集合） POJOs 

**路径 2：二进制文件不兼容**

**预期发生的情况：**
+ 调用升级操作
+ 操作失败，并通过操作 API 和日志显示二进制文件不兼容
+ 启用自动回滚后：应用程序可在几分钟内自动回滚，无需您的干预
+ 禁用自动回滚时：应用程序在不处理数据的情况下保持运行状态；您可以手动回滚到旧版本
+ 修复二进制文件后，使用 [UpdateApplication API](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html) 获得类似于 Path 1 的体验

最适合：在 Flink 作业 APIs 启动期间检测到的使用已移除的应用程序

**路径 3：不兼容的应用程序状态**

**预期发生的情况：**
+ 调用升级操作
+ 最初迁移似乎成功
+ 状态恢复失败后，应用程序将在几秒钟内进入重启循环
+ 通过显示持续重启的 CloudWatch 指标来检测故障
+ 手动调用回滚操作
+ 启动回滚后的几分钟内即可恢复生产
+ [州移民](state-compatibility.md#state-compat-migration)审查您的申请

最适合：状态序列化不兼容的应用程序（POJOs 带有集合，某些 kryo 序列化状态）

**注意**  
强烈建议先创建生产应用程序的副本，并在副本上测试以下每个升级阶段，然后再对生产应用程序执行相同的步骤。

## 第 1 阶段：准备
<a name="upgrade-guide-phase-1"></a>

**更新应用程序代码**

更新您的应用程序代码，使其与 Flink 2.2 兼容：
+ 在你的或中@@ **将 Flink 依赖项更新**到版本 2.2.0 `pom.xml` `build.gradle`
+ 将@@ **连接器依赖关系更新**为兼容 Flink 2.2 的版本（请参阅）[连接器可用性](flink-2-2.md#flink-2-2-connectors)
+ **移除已弃用的 API 用法**：
  + 将 DataSet API 替换为 AP DataStream I 或表 API/SQL
  + 用 FLIP-27 Sourc `SinkFunction` e 和 FLIP-143 Sink 替换传统的`SourceFunction`/ APIs
  + 用 Java API 取代 Scala API 的用法
+ **更新到 Java 17**

**上传更新的应用程序代码**
+ 使用 Flink 2.2 依赖项构建您的应用程序 JAR
+ 使用与当前 JAR **不同的文件名**上传到 Amazon S3（例如，`my-app-flink-2.2.jar`）
+ 记下升级步骤中使用的 S3 存储桶和密钥

## 第 2 阶段：启用自动回滚
<a name="upgrade-guide-phase-2"></a>

自动回滚允许适用于 Apache Flink 的亚马逊托管服务在升级失败时自动恢复到之前的版本。

**检查自动回滚状态**

*AWS 管理控制台:*

1. 导航到您的应用程序

1. 选择**配置**

1. 在 **“应用程序设置”** 下，验证是否**启用了系统回滚**

*AWS CLI:*

```
aws kinesisanalyticsv2 describe-application \
    --application-name MyApplication \
    --query 'ApplicationDetail.ApplicationConfigurationDescription.ApplicationSystemRollbackConfigurationDescription.RollbackEnabled'
```

**启用自动回滚（如果未启用）**

```
aws kinesisanalyticsv2 update-application \
    --application-name MyApplication \
    --current-application-version-id <version-id> \
    --application-configuration-update '{
        "ApplicationSystemRollbackConfigurationUpdate": {
            "RollbackEnabledUpdate": true
        }
    }'
```

## 第 3 阶段：拍摄快照（可选）
<a name="upgrade-guide-phase-3"></a>

如果您的应用程序启用了自动快照，则可以跳过此步骤，否则请在升级之前拍摄应用程序的快照以保存应用程序的状态。

**从正在运行的应用程序中拍摄快照**

*AWS 管理控制台:*

1. 导航到您的应用程序

1. 选择**快照**

1. 选择**创建快照**

1. 输入快照名称（例如，`pre-flink-2.2-upgrade`）

1. 选择 **Create**（创建）。

*AWS CLI:*

```
aws kinesisanalyticsv2 create-application-snapshot \
    --application-name MyApplication \
    --snapshot-name pre-flink-2.2-upgrade
```

**验证快照创建**

```
aws kinesisanalyticsv2 describe-application-snapshot \
    --application-name MyApplication \
    --snapshot-name pre-flink-2.2-upgrade
```

等到 `SnapshotStatus` is `READY` 之后再继续。

## 第 4 阶段：升级应用程序
<a name="upgrade-guide-phase-4"></a>

您可以使用[https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html)操作升级 Flink 应用程序。

您可以通过多种方式调用 `UpdateApplication` API：
+ **使用 AWS 管理控制台。**
  + 转至 AWS 管理控制台上的应用程序页面。
  + 选择**配置**。
  + 选择新的运行时和要从中启动的快照，也称为还原配置。使用最新设置作为还原配置，从最新的快照启动应用程序。指向 Amazon S3 JAR/zip 上新升级的应用程序。
+ **使用动 AWS CLI[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kinesisanalyticsv2/update-application.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kinesisanalyticsv2/update-application.html)**作。
+ **使用 CloudFormation。**
  + 更新字`RuntimeEnvironment`段。 CloudFormation 以前会删除该应用程序并创建一个新应用程序，这会导致您的快照和其他应用程序历史记录丢失。现在就`RuntimeEnvironment`地 CloudFormation 更新您的应用程序，并且不会删除您的应用程序。
+ **使用 AWS 软件开发工具包。**
  + 有关您选择的编程语言，请参阅 SDK 文档。请参阅[https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html)。

您可以在应用程序处于 `RUNNING` 状态或应用程序在 `READY` 状态中停止时执行升级。适用于 Apache Flink 的亚马逊托管服务会验证原始运行时版本和目标运行时版本之间的兼容性。此兼容性检查在您处于状态`UpdateApplication`时执行，或者`StartApplication`如果您在`RUNNING`状态下升级，则在下次执行兼容性检查时运行。`READY`

**从 “运行” 状态升级**

```
aws kinesisanalyticsv2 update-application \
    --application-name MyApplication \
    --current-application-version-id <version-id> \
    --runtime-environment-update FLINK-2_2 \
    --application-configuration-update '{
        "ApplicationCodeConfigurationUpdate": {
            "CodeContentUpdate": {
                "S3ContentLocationUpdate": {
                    "FileKeyUpdate": "my-app-flink-2.2.jar"
                }
            }
        }
    }'
```

**从 “就绪” 状态升级**

```
aws kinesisanalyticsv2 update-application \
    --application-name MyApplication \
    --current-application-version-id <version-id> \
    --runtime-environment-update FLINK-2_2 \
    --application-configuration-update '{
        "ApplicationCodeConfigurationUpdate": {
            "CodeContentUpdate": {
                "S3ContentLocationUpdate": {
                    "FileKeyUpdate": "my-app-flink-2.2.jar"
                }
            }
        }
    }'
```

## 第 5 阶段：显示器升级
<a name="upgrade-guide-phase-5"></a>

**兼容性检查**
+ 使用操作 API 检查升级状态。如果存在二进制文件不兼容或作业启动问题，则升级操作将失败并显示日志。
+ 如果升级操作成功但应用程序陷入重启循环，则表示状态与新的 Flink 版本不兼容，或者更新后的代码存在问题。查看[Flink 2.2 升级的状态兼容性指南](state-compatibility.md)如何识别状态不兼容问题。

**监控应用程序运行状况**

*应用程序状态：*
+ 应用程序状态应过渡：`RUNNING`→ `UPDATING` → `RUNNING`
+ 检查应用程序的运行时间。如果是 2.2，则表示升级操作成功。
+ 如果您的应用程序已进入`RUNNING`但仍使用较旧的运行时，则会启动自动回滚。操作 API 会将操作显示为`FAILED`。检查日志以查找失败的异常。

此外，还可以在以下位置监控这些指标 CloudWatch：

*重启指标：*
+ `numRestarts`：监控意外重启 — 如果为零且`uptime`或`numRestarts`正在增加，`runningTime`则升级成功。

*检查点指标：*
+ `lastCheckpointDuration`: 应类似于升级前的值
+ `numberOfFailedCheckpoints`: 应保持在 0

## 第 6 阶段：验证应用程序行为
<a name="upgrade-guide-phase-6"></a>

在 Flink 2.2 上运行应用程序之后：

**功能验证**
+ 验证是否正在从源读取数据
+ 验证数据是否正在写入接收器
+ 验证业务逻辑是否产生预期结果
+ 将输出与升级前的基准进行比较

**性能验证**
+ 监控延迟指标（end-to-end 处理时间）
+ 监控吞吐量指标（每秒记录数）
+ 监控检查点持续时间和大小
+ 监控内存和 CPU 利用率

**运行 24 小时以上**

允许应用程序在生产环境中运行至少 24 小时，以确保：
+ 没有内存泄漏
+ 稳定的检查点行为
+ 不会出现意外重启
+ 一致的吞吐量

## 第 7 阶段：回滚程序
<a name="upgrade-guide-phase-7"></a>

如果升级失败或应用程序正在运行但运行状况不佳，请回滚到以前的版本。

**自动回滚**

如果启用了自动回滚并且在启动期间升级失败，则 Amazon Apache Flink 托管服务会自动恢复到以前的版本。

**手动回滚**

如果应用程序正在运行但运行状况不佳，请使用 `RollbackApplication` API：

*AWS 管理控制台:*

1. 导航到您的应用程序

1. 选择**操作** → **回滚**

1. 确认回滚

*AWS CLI:*

```
aws kinesisanalyticsv2 rollback-application \
    --application-name MyApplication \
    --current-application-version-id <version-id>
```

**回滚期间会发生什么：**
+ 应用程序停止
+ 运行时恢复到之前的 Flink 版本
+ 应用程序代码恢复到以前的 JAR
+ 应用程序从升级**前**最后一次成功拍摄的快照重新启动

**重要**  
你无法在 Flink 1.x 上恢复 Flink 2.2 快照
回滚使用升级前拍摄的快照
升级前请务必拍摄快照（第 3 阶段）

## 后续步骤
<a name="upgrade-guide-next-steps"></a>

升级期间如有疑问或问题，请参阅[Managed Service for Apache Flink 的故障排除](troubleshooting.md)或联系 Supp AWS ort。