migrate-to-msk

迁移到 MSK Express

概述

此技能可帮助客户将自管理的 Apache Kafka 工作负载迁移到 Amazon MSK Express。它提供三个阶段——发现、评估和可选的 模拟——客户可根据需求端到端运行，也可单独运行。

范围

此技能涵盖从自管理的 Apache Kafka（本地部署、EC2、 Docker、Kubernetes 或其他非 MSK 部署）迁移到 MSK Express。从 MSK Standard（预置）迁移到 MSK Express不在范围内。

先决条件

建议使用 AWS MCP 服务进行文档查询和信息问答，但并非必需。评估脚本仅处理文件，不会调用 AWS API。

意图路由

根据客户的意图转接其请求：

1. 开放式／探索性问题（“如何迁移到 MSK？”）

说明此技能可提供的帮助：

此技能可分三个阶段帮助你迁移到 MSK Express：

**阶段 1 — 发现：**盘点源 Kafka 集群，包括代理、主题、分区数、配置、身份验证和工作负载指标，以及两个会影响成本的目标决策：使用者机架亲和性和任何协商的 AWS 定价。我可以从 IaC 文件（Terraform、CDK、Docker Compose、Kubernetes 清单）中发现这些信息，提供可在集群上运行的命令，或者你也可以手动提供信息。输出：migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json。

**阶段 2 — 评估：**依据 5 个兼容性支柱（拓扑、Kafka 版本、配置、身份验证、配额）验证集群与 MSK Express 的兼容性，并使用 managing-amazon-msk Skill 的定价逻辑生成目标 Express 规格。我会指出 Express 会拒绝的内容，以及 Express 会静默转换的内容。输出：compatibility.<cluster_name>.json、Markdown 文件 msk_sizing_pricing.md 中的定价结果，以及 msk-sizing-inputs.<cluster_name>.json。

**阶段 3 — 模拟：**启动 MSK Express 集群和负载测试基础设施，查看 Express 在你自己的工作负载上的表现，然后运行一项预置测试（端到端延迟或负载下代理重启），并在 CloudWatch 控制面板上查看结果。

**数据复制：**要将数据迁移到 Express 集群，可以使用 MSK Replicator。我可以提供有关设置和配置的指导。

你想从哪里开始？如果你提供基础设施代码或描述集群，我可以从发现开始；如果你已有 cluster-config.json 文件，我可以直接开始评估；如果你已了解目标 Express 配置，也可以直接开始模拟。

此概述回复的防护措施：

• 此回复仅用于概述和引导问题。请勿开始、模拟或预先执行任何阶段。
• 此处请勿生成或估算评估输出——不得给出判定、支柱检查结果、兼容性结论、代理数量、实例建议或成本数字。这些值只有在针对实际的 cluster-config.json 运行阶段 2 脚本后才会产生。
• 请勿打开、读取或总结 compatibility.py、simulation_load_test_config.py 或参考文件的内部内容来解释阶段如何运作。请仅按上述层级描述各阶段，不要向客户讲解实现细节。
• 客户选择阶段后，请运行该阶段的脚本或流程以生成实际结果。务必实际运行此技能来作答——切勿仅凭阅读其源代码作答。具体命令请参见阶段 2 的“运行评估”和阶段 3 的参考资料。

2. 发现意图（提供 IaC 文件时的默认意图）

如果客户提供目录路径、IaC 文件，或表示“这是我们的基础设施”—— 则属于发现意图。仅运行阶段 1（发现）。不要运行评估， 不要建议迁移步骤，也不要提及阻碍因素或兼容性。 生成 migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json 文件，然后停止。

3. 评估意图

客户明确要求进行评估，或已有生成好的 migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json 文件。 仅运行阶段 2（评估）。

4. 模拟意图

客户想使用自己的工作负载测试 MSK Express。他们可以直接提供集群规格 （实例类型、代理数量、Kafka 版本），也可以引用之前的 评估。直接进入 阶段 3 — 模拟。 评估虽有帮助，但并非必需——模拟会直接询问规格输入。

5. 信息咨询

客户询问 Express 的功能、限制、配置差异、 身份验证支持、定价或压缩行为，且未提供特定集群数据。若可用，请使用 AWS 文档工具（aws___search_documentation、 aws___read_documentation）从 MSK Express 文档中查找答案。如果没有 MCP 工具可用，请参考 MSK Express 文档 并根据对 AWS MSK 的了解作答。

6. 迁移策略咨询

客户询问 MSK Replicator 兼容性、版本升级路径、MirrorMaker 2 或迁移策略。MSK Replicator 是 AWS 原生支持的数据复制解决方案，适用于 MSK 到 MSK 以及非 MSK 到 MSK 的迁移。如果可用，请使用 AWS 文档工具（aws___search_documentation、aws___read_documentation） 获取当前要求和支持的配置。如果没有 MCP 工具可用，请参考 MSK Replicator 文档 并根据对 AWS MSK 的了解作答。

---

阶段 1 — 发现

**目的：**盘点源集群，构建迁移配置档案。

**输入：**以下任一项：

• 包含 IaC 文件的目录路径（CDK、CloudFormation、Docker Compose、Kubernetes 清单、Terraform）
• 客户在其集群上运行的 Kafka CLI 命令输出
• 客户在对话中手动提供的信息

输出：migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json — 保存到工作目录。

发现规则

• 在发现过程中进行任何其他操作之前，必须先完整阅读 references/discovery.md。该文件定义了 输入方式、必需的回复模板、禁止内容以及 cluster-config.json 架构。在阅读之前不要回复，并且必须严格遵循 其模板。
• 始终将 migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json 保存到工作目录。
• 未经客户明确确认，不要进入阶段 2。

---

Phase 2 — 评估

目的： 根据 MSK Express 要求评估集群，并生成目标 Express 规格（实例类型、Broker 数量、月度成本预测）。

输入： Phase 1 生成的 migrate-to-msk-skill-artifacts/<cluster_name>/cluster-config.json。

输出：

• migrate-to-msk-skill-artifacts/<cluster_name>/compatibility.<cluster_name>.json — 五大支柱评估结果。
• migrate-to-msk-skill-artifacts/<cluster_name>/msk_sizing_pricing.md — managing-amazon-msk Skill 的定价报告，其中包含 Broker 数量和成本建议。
• migrate-to-msk-skill-artifacts/<cluster_name>/msk-sizing-inputs.<cluster_name>.json — 六项容量规划逻辑输入值的记录。

评估分为两个相互独立的部分，可按任意顺序运行；其中一项失败不会阻止另一项：

• 兼容性 — scripts/compatibility.py 是纯文件处理程序（不调用实时 AWS API），通过带有 PEP 723 内联依赖的 uv run 运行。它从五大支柱——拓扑、Kafka 版本、配置、身份验证和配额——对源集群进行验证，并为每个支柱给出一个判定（INFO、ADVISORY 或 ACTION_REQUIRED）；总体判定取其中最严重的一项。请原样使用这三个字符串。
• 容量规划 — 此 Skill 中没有对应脚本。加载 managing-amazon-msk Skill，并根据 cluster-config.json 中推导出的工作负载输入运行其 scripts/msk_sizing.py，同时传入 --broker-classes express 和目标 Region 的 --region。当凭证可用时，脚本会通过实时 AWS Pricing API 计算价格；否则使用内置的 us-east-1 快照。

评估规则

• 回复前请阅读 references/assessment-compatibility.md。其中包含调用命令、各支柱的阈值和证据代码、判定定义、完整的禁止行为列表，以及涵盖两个产物的必需回复模板。脚本运行后的摘要必须严格遵循模板。
• 运行容量规划前请阅读 references/assessment-sizing.md。其中包含输入值的推导方法（有些输入并非一一对应——推导错误会悄然导致 Broker 数量错误）、target 块中用于机架亲和性和协商折扣的标志、Region 与定价来源的处理方式、仅展示 Express 的规则，以及源集群占用情况的比较方法。
• 将任何 ACTION_REQUIRED 证据告知用户，以便其了解情况，但不要因此阻止后续阶段。Express 仍可能通过缓解措施支持该工作负载。
• 不要重新转向发现阶段。 评估应直接使用现有的 cluster-config.json，不得修改。数据不完整也可以——缺少字段时，脚本会生成 ADVISORY 证据（例如 METRICS_MISSING、AZ_COUNT_UNKNOWN 等）；请说明这些发现并停止。不要建议使用 Kafka CLI 命令、遍历 IaC、编写脚本或填写问卷来补齐数据。
• Broker 数量和成本只能照抄容量规划脚本的输出。不得取整、重新推导或估算。报告成本时必须一并报告脚本使用的 pricing source；若其值为 static，则费率来自内置快照，并非经确认的当前定价。

---

Phase 3 — 模拟（可选）

在客户账户中部署一个临时、隔离的 MSK Express 集群和客户端群，让客户了解 Express 在其自身工作负载上的表现，然后运行两种已提供测试中的一种（端到端延迟、负载下的 Broker 重启），并交付 CloudWatch 控制面板。请遵循 references/simulation.md 中的 12 步对话流程，以及所有部署、容量规划和防护措施的详细说明；该流程驱动的确定性产物包括 scripts/simulation_load_test_config.py 和静态文件 assets/simulation-stack.yaml。

---

执行模型

脚本通过 uv run 在客户的本地计算机上运行。它们会声明自己的依赖项（PEP 723），且仅用于处理文件——不调用 AWS API、不访问网络，也不依赖第三方库（仅使用标准库）。

安全注意事项

在每个阶段都应用这些控制措施。更多详情请参阅 MSK 安全最佳实践 和 MSK IAM 访问控制。

1. 传输中加密（强制）。 对 MSK Express 目标集群上的客户端与代理之间的流量强制启用 TLS （EncryptionInTransit.ClientBroker = TLS）。

2. 静态加密（强制）。 使用客户管理的 KMS 密钥配置目标集群（如果合规要求允许，也可使用 AWS 管理的密钥）。

3. 身份验证 — 优先使用 IAM，而非长期凭证。 将 MSK Express 目标集群配置为仅使用 IAM 身份验证作为客户端身份验证方式。 这样可使用临时的、基于角色的凭证，并获得完整的 CloudTrail 覆盖。

4. 凭证存储 — 使用 AWS Secrets Manager。 在 Secrets Manager 中存储用于访问源集群的 SASL/SCRAM 和 TLS 凭证。切勿将密码作为 CLI 参数传递。

5. 网络隔离。 在私有子网中部署 MSK 集群。将安全组规则限制为特定的 CIDR 范围或安全组引用。切勿使用 0.0.0.0/0 入站规则。

6. CloudTrail 日志记录和 CloudWatch 警报。 确保在目标账户中启用 CloudTrail，并覆盖 kafka.amazonaws.com API 调用。配置以下警报：

   • ClientAuthenticationFailure — 激增表示凭证问题或攻击
   • ConnectionCloseCount — 异常激增可能表示连接泛洪攻击
   • 针对被拒绝的 kafka-cluster:* 操作配置 CloudTrail 指标筛选器
   • 当连接速率接近 IAM 限制（每个代理每秒 100 个连接）时触发警报

7. 敏感数据处理。 发现和评估输出包含代理地址、身份验证提示和代理配置值。请将这些信息视为敏感数据——未经脱敏，切勿粘贴到公共频道或工单系统中。

故障排查

有关各项评估的发现，包括源拓扑和超出范围的配置情况，请参阅 references/assessment-compatibility.md。