本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon MSK 的关键功能和概念
预置 Amazon MSK 集群具有多种特性和功能，可帮助优化集群的性能并满足流需求。以下主题详细描述了这些功能。
+ 这些区域有：[AWS 管理控制台](https://console.aws.amazon.com/msk)
+ [Amazon MSK API Reference](https://docs.aws.amazon.com/msk/1.0/apireference)
+ [Amazon MSK CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/kafka/index.html)
**Topics**
+ [
# Amazon MSK 代理类型
](broker-instance-types.md)
+ [
# Amazon MSK 代理大小
](broker-instance-sizes.md)
+ [
# 标准代理的存储管理
](msk-storage-management.md)
+ [
# 预置 Amazon MSK 配置
](msk-configuration.md)
+ [
# 集群的智能再平衡
](intelligent-rebalancing.md)
+ [
# 在预置 MSK 集群上进行修补
](patching-impact.md)
+ [
# 代理离线和客户端失效转移
](troubleshooting-offlinebroker-clientfailover.md)
+ [
# Amazon MSK 中的安全性
](security.md)
+ [
# Amazon MSK 日志记录
](msk-logging.md)
+ [
# 元数据管理
](metadata-management.md)
+ [
# 主题操作
](msk-topic-operations-information.md)
+ [
# Amazon MSK 资源
](resources.md)
+ [
# Apache Kafka 版本
](kafka-versions.md)
+ [
# 排查 Amazon MSK 集群的问题
](troubleshooting.md)
# Amazon MSK 代理类型
预置 MSK 提供两种代理类型：标准和快速。标准代理为您提供了配置集群的最大灵活性，而 Express 代理则提供了更大的弹性、吞吐量、弹性，可以运行高性能 ease-of-use的流媒体应用程序。
有关各个产品的更多详细信息，请参阅以下主题。下表还重点介绍了标准和快速代理之间的主要功能比较。
| 功能 | 标准代理 | 快速代理 |
| --- | --- | --- |
| [存储管理](msk-storage-management.md) | 客户托管式（功能包括 EBS 存储、分层存储、预置存储吞吐量、自动扩缩、存储容量警报） | 完全由 MSK 托管 |
| [支持的实例](broker-instance-sizes.md) | T3、M5、m7g | M7g |
| [调整大小和扩缩注意事项](bestpractices-intro.md) | 吞吐量、连接、分区、存储 | 吞吐量、连接、分区 |
| [代理扩缩](msk-update-broker-count.md) | 垂直和水平扩缩 | 垂直和水平扩缩 |
| [Kafka 版本](kafka-versions.md) | 请参阅 [Apache Kafka 版本](kafka-versions.md)。 | 起始版本为 3.6 版 |
| [Apache Kafka 配置](msk-configuration.md) | 更易于配置 | 大多数情况下由 MSK 托管，以增强弹性 |
| [安全性](security.md) | 加密、 Private/Public 访问、身份验证和授权——IAM、SASL/SCRAM、mTLS、纯文本、Kafka ACLs | 加密、 Private/Public 访问、身份验证和授权——IAM、SASL/SCRAM、mTLS、纯文本、Kafka ACLs |
| [监控](monitoring.md) | CloudWatch，打开监控 | CloudWatch，打开监控 |
**注意**
无法通过使用 MSK API 切换代理类型，将预置 MSK 集群从标准代理类型更改为快速代理类型。必须使用所需的代理类型（标准或快速）创建新集群。
**Topics**
+ [
# Amazon MSK 标准代理
](msk-broker-types-standard.md)
+ [
# Amazon MSK 快速代理
](msk-broker-types-express.md)
# Amazon MSK 标准代理
预置 MSK 的标准代理具有配置集群性能的最大灵活性。您可以从多种集群配置中选择配置，实现应用程序所需的可用性、持久性、吞吐量和延迟特性。您还可以预置存储容量，并根据需要增加容量。Amazon MSK 负责标准代理和附加存储资源的硬件维护，可自动修复可能出现的硬件问题。有关标准代理的各种相关主题的更多详细信息，包括[存储管理](msk-storage-management.md)、[配置](msk-configuration-standard.md)和[维护](patching-impact.md#patching-standard-brokers)主题，可参见本文档。
# Amazon MSK 快速代理
预置 MSK 的快速代理简化了 Apache Kafka 的管理，提高了大规模运行的成本效益，并在预期的低延迟下更具弹性。代理包括可自动扩展的 pay-as-you-go存储，无需调整规模、配置或主动监控。根据所选实例大小，每个代理节点相较于标准 Apache Kafka 代理，可提供高达 3 倍的单代理吞吐量、20 倍的扩展速度，并将恢复速度提高 90%。快速代理预配置了 Amazon MSK 的最佳实践默认值，并强制执行客户端吞吐量配额，以最大限度地减少客户端与 Kafka 后台操作之间的资源争用。
以下是使用快速代理时需要考虑的一些关键因素和功能。
+ **无需管理存储**：快速代理无需[预配置或管理任何存储资源](msk-storage-management.md)。您可以获得弹性、几乎无限量且完全托管的存储。 pay-as-you-go对于高吞吐量用例，无需考虑计算实例与存储卷之间的交互以及相关的吞吐量瓶颈。这些功能简化了集群管理，并消除了存储管理的操作开销。
+ **更快的扩展速度**：快速代理扩展集群和移动分区的速度最高比标准代理快 20 倍。当需要横向扩展集群以应对即将到来的负载峰值，或横向缩减集群以降低成本时，此功能至关重要。有关扩展集群的更多详细信息，请参阅[扩展集群](msk-update-broker-count.md)、[移除代](msk-remove-broker.md)理、[重新分配分区和](msk-update-broker-type.md)[设置 LinkedIn Cruise Control 进行再平衡](cruise-control.md)的部分。
+ **更高的吞吐量**：快速代理为提供的单代理吞吐量是标准代理的三倍之多。例如，您可以安全地 MBps 使用每个 m7g.16xlarge 大小 Express broker 以 500 的速度写入数据，而同等标准代理 MBps 上的数据写入速度为 153.8（这两个数字都假设为后台操作（例如复制和重新平衡）分配了足够的带宽）。
+ **采用高弹性配置**：快速代理会自动提供各种最佳实践，以提高集群的弹性。其中包括针对关键 Apache Kafka 配置的安全护栏、吞吐量配额以及用于后台操作和计划外修复的容量预留。借助于这些功能，可以更安全、更轻松地运行大规模的 Apache Kafka 应用程序。有关更多详细信息，请参阅[快速代理配置](msk-configuration-express.md)和[Amazon MSK 快速代理配额](limits.md#msk-express-quota)部分。
+ **无维护窗口**：快速代理没有维护窗口。Amazon MSK 会持续自动更新集群硬件。有关更多详细信息，请参阅[为快速代理打补丁](https://docs.aws.amazon.com/msk/latest/developerguide/patching-impact.html#patching-express-brokers)。
## 有关快速代理的其他信息
+ 快递代理使用 Apache Kafka APIs，但尚未完全支持 KStreams API。
+ 快递经纪商仅在 3 种AZs 配置中可用。
+ 快速代理仅适用于特定实例大小。有关更新的列表，请参阅 [Amazon MSK 定价](https://aws.amazon.com/msk/pricing/)。
+ 以下 Apache Kafka 版本支持 Express 代理：3.6、3.8 和 3.9。
+ 可以使用 Apache Kafka 版本 3.9 及以后的 KRaft 模式创建快递代理。
**查看这些博客**
有关 MSK 快速代理的更多信息，以及要查看在用快速代理的真实示例，请阅读以下博客：
[引入 Amazon MSK 快速代理为 Kafka 集群带来高吞吐量和更快的扩缩](https://aws.amazon.com/blogs/aws/introducing-express-brokers-for-amazon-msk-to-deliver-high-throughput-and-faster-scaling-for-your-kafka-clusters/)
[Amazon MSK 快速代理：增强版 Kafka 扩缩将速度性能提升 20 倍之多](https://aws.amazon.com/blogs/big-data/express-brokers-for-amazon-msk-turbo-charged-kafka-scaling-with-up-to-20-times-faster-performance/)
这篇博客演示了快速代理如何：
提供更快的吞吐量、快速扩展以及更短的故障恢复时间
消除存储管理的复杂性
# Amazon MSK 代理大小
在创建预置 Amazon MSK 集群时，您可以指定其要使用的代理大小。Amazon MSK 支持以下代理大小，具体视[代理类型](broker-instance-types.md)而定。
**标准代理大小**
+ kafka.t3.small
+ kafka.m5.large、kafka.m5.xlarge、kafka.m5.2xlarge、kafka.m5.4xlarge、kafka.m5.8xlarge、kafka.m5.12xlarge、kafka.m5.16xlarge、kafka.m5.24xlarge
+ kafka.m7g.large、kafka.m7g.xlarge、kafka.m7g.2xlarge、kafka.m7g.4xlarge、kafka.m7g.8xlarge、kafka.m7g.12xlarge、kafka.m7g.16xlarge
**快速代理大小**
+ express.m7g.large、express.m7g.xlarge、express.m7g.2xlarge、express.m7g.4xlarge、express.m7g.8xlarge、express.m7g.12xlarge、express.m7g.16xlarge
**注意**
某些 AWS 地区可能不提供某些经纪商规模。有关各区域的最新可用实例列表，请参阅 [Amazon MSK 定价页面](https://aws.amazon.com/msk/pricing/)上更新的代理实例定价表。
## 关于代理大小的其他说明
+ M7g 经纪商使用 G AWS raviton 处理器（由 Amazon Web Services 构建的基于 ARM 的定制处理器）。与同类 M5 实例相比，M7g 代理提供更好的性价比。M7g 代理比同类 M5 实例消耗更少的电量。
+ Amazon MSK 在运行 2.8.2 和 3.3.2 及更高版本 Kafka 的预置 MSK 集群上支持 m7g 代理。
+ M7g 和 M5 代理具有比 T3 代理更高的基准吞吐量性能，建议用于生产工作负载。M7g 和 M5 代理还可具有比 T3 代理更多的每代理分区。如果您正在运行较大的生产级工作负载或需要更多的分区，请使用 M7g 和 M5 代理。要了解有关 M7g 和 M5 实例大小的更多信息，请参阅 A [mazon EC2 通用](https://aws.amazon.com/ec2/instance-types/)型实例。
+ T3 代理可以使用 CPU 积分来临时提高性能。如果您正在测试中小型流式处理工作负载，或者您的低吞吐量流式处理工作负载会临时出现吞吐量高峰，则可以使用 T3 代理进行低成本开发。我们建议您 proof-of-concept进行测试，以确定 T3 代理是否足以应对生产或关键工作负载。要了解有关 T3 代理规模的更多信息，请参阅 [Amazon EC2 T3 实例](https://aws.amazon.com/ec2/instance-types/t3/)。
有关如何选择代理大小的更多信息，请参阅[标准代理和快速代理的最佳实践](bestpractices-intro.md)。
# 标准代理的存储管理
Amazon MSK 提供的功能可帮助您管理 MSK 集群的存储。
**注意**
使用[快速代理](msk-broker-types-express.md)，就无需配置或管理用于数据的存储资源。这简化了集群管理，并消除了 Apache Kafka 集群运行问题的常见诱因之一。此外还可以减少支出，因为无需配置空闲存储容量，而且只需按使用量付费。
**标准代理类型**
使用[标准代理](msk-broker-types-standard.md)，可以选择多种存储选项和功能。Amazon MSK 提供的功能可帮助您管理 MSK 集群的存储。
有关管理吞吐量的信息，请参阅[为 Amazon MSK 集群中的标准代理预置存储吞吐量](msk-provision-throughput.md)。
**Topics**
+ [
# 标准代理的分层存储
](msk-tiered-storage.md)
+ [
# 纵向扩展 Amazon MSK 标准代理存储
](msk-update-storage.md)
+ [
# 为 Amazon MSK 集群中的标准代理管理存储吞吐量
](msk-provision-throughput-management.md)
# 标准代理的分层存储
分层存储是 Amazon MSK 的低成本存储层，可扩展到几乎无限的存储空间，支持经济高效地构建流数据应用程序。
您可以创建配置有能平衡性能和成本的分层存储的 Amazon MSK 集群。Amazon MSK 将流数据存储在性能优化型主存储层中，直到数据达到 Apache Kafka 主题的保留期限。然后，Amazon MSK 会自动将数据移入新的低成本存储层。
当应用程序开始从分层存储中读取数据时，前几个字节的读取延迟可能会增加。开始按顺序从低成本层读取其余数据时，可能会出现与主存储层类似的延迟。您无需为低成本分层存储预置任何存储，也不需要管理基础设施。您可以存储任意数量的数据，但只需按实际用量付费。此功能与 [KIP-405：Kafka 分层存储](https://cwiki.apache.org/confluence/display/KAFKA/KIP-405%3A+Kafka+Tiered+Storage)中 APIs 引入的功能兼容。
有关 MSK 分层存储集群调整大小、监控和优化的信息，请参阅[使用 Amazon MSK 分层存储运行生产工作负载的最佳实践](https://aws.amazon.com/blogs/big-data/best-practices-for-running-production-workloads-using-amazon-msk-tiered-storage/)。
以下是分层存储的一些功能：
+ 您可以扩展到几乎无限的存储空间，不必猜测如何扩展 Apache Kafka 基础设施。
+ 您可以在 Apache Kafka 主题中延长数据保留时间，也可以增加主题存储空间，不必增加代理数量。
+ 其提供了持续时间更长的安全缓冲区来应对处理中的意外延迟。
+ 您可以使用现有的流处理代码和 Kafka APIs 按精确的生产顺序重新处理旧数据。
+ 分区重新平衡速度更快，因为二级存储上的数据不需要跨代理磁盘进行复制。
+ 代理和分层存储之间的数据只会在 VPC 内移动，而不会通过互联网进行传输。
+ 客户端计算机连接到启用了分层存储的新集群的过程，与连接到未启用分层存储的集群的过程相同。请参阅[创建客户端计算机](https://docs.aws.amazon.com/msk/latest/developerguide/create-client-machine.html)。
## Amazon MSK 集群的分层存储要求
+ 您必须使用 Apache Kafka 客户端版本 3.0.0 或更高版本来创建启用了分层存储的新主题。要将现有主题过渡到分层存储，您可以重新配置使用低于 3.0.0 的 Kafka 客户端版本（支持的最低 Apache Kafka 版本为 2.8.2.tiered）的客户端计算机来启用分层存储。请参阅[步骤 4：在 Amazon MSK 集群中创建主题](create-topic.md)。
+ 启用了分层存储的 Amazon MSK 集群必须使用 3.6.0 或更高版本或者 2.8.2.tiered。
## Amazon MSK 集群的分层存储约束和限制
分层存储存在以下约束和限制：
+ 确保客户端在从 Amazon MSK 中的 remote\$1tier 读取时未配置为 `read_committed`，除非应用程序正在主动使用事务功能。
+ 分层存储在 AWS GovCloud （美国）地区不可用。
+ 分层存储仅适用于预置模式集群。
+ 分层存储不支持代理大小 t3.small。
+ 低成本存储的最短保留期为 3 天。主存储不存在最短保留期。
+ 分层存储不支持代理上的多个日志目录（与 JBOD 相关的功能）。
+ 分层存储不支持压缩主题。确保所有已开启分层存储的主题已将 cleanup.policy 配置为只能 “删除”。
+ 分层存储集群不支持在主题创建后更改其 log.cleanup.policy 策略。
+ 可以为单个主题禁用分层存储，但不能禁用整个集群的分层存储。一旦禁用，就无法再为主题启用分层存储。
+ 如果使用 Amazon MSK 版本 2.8.2.tiered，则只能迁移到另一个支持分层存储的 Apache Kafka 版本。如果不想继续使用支持分层存储的版本，请创建一个新的 MSK 集群并将您的数据迁移到该集群。
+ 该 kafka-log-dirs工具无法报告分层存储数据大小。该工具只会报告主存储中日志段的大小。
有关在主题级别配置分层存储时必须注意的默认设置与限制的信息，请参阅[Amazon MSK 分层存储主题级别的配置指南](msk-guidelines-tiered-storage-topic-level-config.md)。
# 如何将日志段复制到 Amazon MSK 主题的分层存储
当您为新主题或现有主题启用分层存储时，Apache Kafka 会将已关闭的日志段从主存储复制到分层存储。
+ Apache Kafka 仅复制已关闭的日志段。它将日志段中的所有消息复制到分层存储。
+ 活动区段不符合分层条件。日志段大小 (segment.bytes) 或段滚动时间 (segment.ms) 控制数据段关闭的速率，以及 Apache Kafka 随后将段复制到分层存储的速率。
启用了分层存储的主题的保留设置与未启用分层存储的主题的保留设置不同。以下规则控制启用了分层存储的主题中消息的保留情况：
+ 您可以在 Apache Kafka 中使用两个设置来定义保留期：log.retention.ms（时间）和 log.retention.bytes（大小）。这些设置决定了 Apache Kafka 在集群中保留的数据的总时长和总大小。无论是否启用分层存储模式，都需要在集群级设置这些配置。您可以使用主题配置覆盖主题级别的设置。
+ 启用分层存储时，还可以指定高性能主存储层存储数据的时长。例如，如果主题的总体保留期 (log.retention.ms) 设置为 7 天，本地保留期 (local.retention.ms) 设置为 12 小时，则集群主存储仅保留前 12 小时的数据。低成本存储层可将数据保留整整 7 天。
+ 一般的保留设置适用于完整日志。这包括其分层和主要部分。
+ local.retention.ms 或 local.retention.bytes 设置控制消息在主存储中的保留情况。Apache Kafka 在关闭的日志段后立即将其复制到分层存储（基于 segment.bytes 或 segment.ms），与本地保留设置无关。将数据段复制到分层存储后，它们将保留在主存储中，直到达到 local.retention.ms 或 local.retention.bytes 阈值。此时，数据将从主存储中删除，但在分层存储中仍可用。这使您可以将最新数据保存在高性能主存储上，以便快速访问，而较旧的数据则由低成本的分层存储提供。
+ 当 Apache Kafka 将日志段中的消息复制到分层存储时，会根据 retention.ms 或 retention.bytes 设置将该消息从集群中删除。
## Amazon MSK 分层存储场景示例
此场景说明了启用分层存储后，主存储中包含消息的现有主题的行为方式。在将 remote.storage.enable 设置为 `true` 后，您可以启用本主题的分层存储。在此示例中，retention.ms 设置为 5 天，local.rete ntion.ms 设置为 2 天。以下是段过期时的事件序列。
**时间 T0 – 启用分层存储之前。**
在为本主题启用分层存储之前有两个日志段。对于现有主题分区 0，其中一个日志段处于活动状态。
![\[时间 T0 – 启用分层存储之前。\]](http://docs.aws.amazon.com/zh_cn/msk/latest/developerguide/images/tiered-storage-segments-1.png)
**时间 T1（< 2 天）– 启用了分层存储。段 0 已复制到分层存储。**
为本主题启用分层存储后，Apache Kafka 会在关闭的日志段 0 关闭后立即将其复制到分层存储。区段根据分段.bytes 或 segment.ms 设置关闭，而不是基于保留设置。Apache Kafka 还会在主存储器中保留一份副本。活动分段 1 还没有资格复制到分层存储，因为它仍处于活动状态且尚未关闭。在此时间表中，Amazon MSK 尚未对区段 0 和区段 1 中的任何消息应用任何保留设置。 （本地。保留。 bytes/ms, retention.ms/bytes)
![\[时间 T1（< 2 天）– 启用了分层存储。段 0 已复制到分层存储。\]](http://docs.aws.amazon.com/zh_cn/msk/latest/developerguide/images/tiered-storage-segments-2.png)
**时间 T2 – 本地保留设置生效。**
2 天后，将达到分段 0 的本地保留阈值。这是因为 local.retention.ms 设置为了 2 天。Segment 0 现已从主存储中删除，但在分层存储中仍可用。请注意，分段 0 在分层存储关闭时已在时间 T1 被复制到分层存储，而不是在本地保留期到期时 T2。Active Segment 1 既不符合删除条件，也没有资格复制到分层存储，因为它仍然处于活动状态。
![\[时间 T2 – 本地保留设置生效。\]](http://docs.aws.amazon.com/zh_cn/msk/latest/developerguide/images/tiered-storage-segments-3.png)
**时间 T3 – 总体保留设置生效。**
五天后，保留设置生效，Kafka 会从分层存储中清除日志段 0 和关联消息。段 1 既不满足过期要求，也不符合复制到分层存储的条件，因为它处于活动状态。段 1 尚未关闭，因此不符合段滚动的条件。
![\[时间 T3 – 总体保留设置生效。\]](http://docs.aws.amazon.com/zh_cn/msk/latest/developerguide/images/tiered-storage-segments-4.png)
# 使用创建具有分层存储的 Amazon MSK 集群 AWS 管理控制台
此过程介绍了如何使用 AWS 管理控制台创建分层存储 Amazon MSK 集群。
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 选择**创建集群**。
1. 为分层存储选择**自定义创建**。
1. 指定集群的名称。
1. 在**集群类型**中选择**预置**。
1. 为 Amazon MSK 选择支持分层存储的 Amazon Kafka 版本，用于创建集群。
1. 指定 **kafka.t3.small** 以外的代理大小。
1. 指定您希望 Amazon MSK 在每个可用区中创建的代理数量。每个可用区最少一个代理，每个集群最多 30 个代理。
1. 指定代理分布的可用区的数量。
1. 指定每个可用区部署的 Apache Kafka 代理的数量。
1. 选择**存储选项**。其中包括可启用分层存储模式的**分层存储和 EBS 存储**。
1. 按照集群创建向导中的剩余步骤操作。完成后，**分层存储和 EBS 存储**将作为集群存储模式显示在**检查并创建**视图中。
1. 选择 **Create cluster（创建集群）**。
# 使用创建具有分层存储的 Amazon MSK 集群 AWS CLI
要在集群上启用分层存储，请使用正确的 Apache Kafka 版本和分层存储属性创建集群。请按照以下代码示例操作。此外，请完成下一节中的步骤，[创建启用分层存储的 Kafka 主题 AWS CLI](#msk-create-topic-tiered-storage-cli)。
有关创建集群的支持属性的完整列表，请参阅 [create-cluster](https://docs.aws.amazon.com//cli/latest/reference/kafka/create-cluster.html)。
```
aws kafka create-cluster \
—cluster-name "MessagingCluster" \
—broker-node-group-info file://brokernodegroupinfo.json \
—number-of-broker-nodes 3 \
--kafka-version "3.6.0" \
--storage-mode "TIERED"
```
## 创建启用分层存储的 Kafka 主题 AWS CLI
要完成在创建启用了分层存储的集群时开始的过程，您还要创建一个启用了分层存储的主题，其中包含后文代码示例中的属性。分层存储的专门属性如下：
+ `local.retention.ms`（例如 10 分钟）为基于时间的保留设置，`local.retention.bytes` 为日志段大小限制。
+ `remote.storage.enable` 设置为 `true` 即可启用分层存储。
以下配置使用 local.retention.ms，但此属性可替换为 local.retention.bytes。此属性控制 Apache Kafka 将数据从主存储复制到分层存储之前可以经过的时长或 Apache Kafka 可以复制的字节数。有关支持的配置属性的更多详细信息，请参阅 [Topic-level configuration](https://docs.aws.amazon.com//msk/latest/developerguide/msk-configuration-properties.html#msk-topic-confinguration)。
**注意**
您必须使用 Apache Kafka 客户端版本 3.0.0 及更高版本。这些版本仅在 `kafka-topics.sh` 的这些客户端版本中名为 `remote.storage.enable` 的设置。要对使用早期版本的 Apache Kafka 的现有主题启用分层存储，请参阅[在现有 Amazon MSK 主题上启用分层存储](msk-enable-disable-topic-tiered-storage-cli.md#msk-enable-topic-tiered-storage-cli)小节。
```
bin/kafka-topics.sh --create --bootstrap-server $bs --replication-factor 2 --partitions 6 --topic MSKTutorialTopic --config remote.storage.enable=true --config local.retention.ms=100000 --config retention.ms=604800000 --config segment.bytes=134217728
```
# 在现有 Amazon MSK 主题上启用和禁用分层存储
这些小节介绍如何在已创建的主题上启用和禁用分层存储。要创建启用了分层存储的新集群和主题，请参阅[使用 AWS 管理控制台创建启用了分层存储的集群](https://docs.aws.amazon.com//msk/latest/developerguide/msk-create-cluster-tiered-storage-console)。
## 在现有 Amazon MSK 主题上启用分层存储
要在现有主题上启用分层存储，请使用以下示例中的 `alter` 命令语法。在已经存在的主题上启用分层存储后，您不会受到某个 Apache Kafka 客户端版本的限制。
```
bin/kafka-configs.sh --bootstrap-server $bsrv --alter --entity-type topics --entity-name msk-ts-topic --add-config 'remote.storage.enable=true, local.retention.ms=604800000, retention.ms=15550000000'
```
## 在现有 Amazon MSK 主题上禁用分层存储
要在现有主题上禁用分层存储，请按照启用分层存储时的顺序使用 `alter` 命令语法。
```
bin/kafka-configs.sh --bootstrap-server $bs --alter --entity-type topics --entity-name MSKTutorialTopic --add-config 'remote.log.msk.disable.policy=Delete, remote.storage.enable=false'
```
**注意**
禁用分层存储后，就会完全删除分层存储中的主题数据。Apache Kafka 会保留主存储数据，但仍会应用基于 `local.retention.ms` 的主保留规则。禁用主题的分层存储后，便无法再次启用分层存储。要在现有主题上禁用分层存储，您不会受到某个 Apache Kafka 客户端版本的限制。
# 使用 AWS CLI 在现有 Amazon MSK 集群上启用分层存储
**注意**
只有在集群的 log.cleanup.policy 设置为 `delete` 时，才能启用分层存储，因为分层存储不支持压缩主题。如果未在该特定主题上启用分层存储，稍后可以将该主题的 log.cleanup.policy 配置为 `compact`。有关支持的配置属性的更多详细信息，请参阅 [Topic-level configuration](https://docs.aws.amazon.com//msk/latest/developerguide/msk-configuration-properties.html#msk-topic-confinguration)。
1. **更新 Kafka 版本**：集群版本并非简单的整数。要查找集群的当前版本，请使用`DescribeCluster`操作或 `describe-cluster` AWS CLI 命令。示例版本是 `KTVPDKIKX0DER`。
```
aws kafka update-cluster-kafka-version --cluster-arn ClusterArn --current-version Current-Cluster-Version --target-kafka-version 3.6.0
```
1. 编辑集群存储模式。以下代码示例显示如何使用 [https://docs.aws.amazon.com/cli/latest/reference/kafka/update-storage.html](https://docs.aws.amazon.com/cli/latest/reference/kafka/update-storage.html) API 将集群存储模式编辑为 `TIERED`。
```
aws kafka update-storage --current-version Current-Cluster-Version --cluster-arn Cluster-arn --storage-mode TIERED
```
# 使用控制台更新现有 Amazon MSK 集群上的分层存储
此过程介绍了如何使用 AWS 管理控制台更新分层存储 Amazon MSK 集群。
确保 MSK 集群当前的 Apache Kafka 版本是 2.8.2.tiered。如果您需要将 MSK 集群升级到 2.8.2.tiered 版本，请参阅[更新 Apache Kafka 版本](https://docs.aws.amazon.com/msk/latest/developerguide/version-upgrades.html)。
**注意**
只有在集群的 log.cleanup.policy 设置为 `delete` 时，才能启用分层存储，因为分层存储不支持压缩主题。如果未在该特定主题上启用分层存储，稍后可以将该主题的 log.cleanup.policy 配置为 `compact`。有关支持的配置属性的更多详细信息，请参阅 [Topic-level configuration](https://docs.aws.amazon.com//msk/latest/developerguide/msk-configuration-properties.html#msk-topic-confinguration)。
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 转到集群摘要页面，再选择**属性**。
1. 转到**存储**部分，再选择**编辑集群存储模式**。
1. 先选择**分层存储和 EBS 存储**，再选择**保存更改**。
# 纵向扩展 Amazon MSK 标准代理存储
您可以增加每个代理的 EBS 存储空间。您无法减少存储。
在此扩展操作期间，存储卷仍然可用。
**重要**
扩展 MSK 集群的存储空间后，立即可以使用额外的存储空间。不过，在每次存储扩展事件之后，集群都需要一段冷却期。Amazon MSK 使用此冷却期来优化集群，再对其进行扩展。这段时间从最少 6 小时到超过 24 小时不等，具体取决于集群的存储大小和利用率以及流量。这既适用于 auto scaling 事件，也适用于使用该[UpdateBrokerStorage](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-nodes-storage.html#UpdateBrokerStorage)操作进行手动缩放。有关正确调整存储空间大小的信息，请参阅 [标准代理的最佳实践](bestpractices.md)。
您可以使用分层存储为代理纵向扩展到无限量的存储空间。请参阅 [标准代理的分层存储](msk-tiered-storage.md)。
**Topics**
+ [
# Amazon MSK 集群的自动扩缩
](msk-autoexpand.md)
+ [
# 标准代理的手动扩缩
](manually-expand-storage.md)
# Amazon MSK 集群的自动扩缩
要自动扩展集群存储容量以应对使用量增加，您可以为 Amazon MSK 配置应用程序自动扩缩策略。在自动扩缩策略中，您可以设置目标磁盘利用率和最大扩展容量。
在为 Amazon MSK 使用自动扩缩之前，您应考虑以下几点：
+
**重要**
存储扩展操作每 6 小时只能发生一次。
建议您从大小合适的存储卷开始，以满足存储需求。有关调整集群大小的指导，请参阅[调整集群的大小：每个集群的标准代理数量](bestpractices.md#brokers-per-cluster)。
+ Amazon MSK 不会因使用量减少而减小集群存储容量。Amazon MSK 不支持减小存储卷的大小。如果您需要减小集群存储大小，则必须将现有集群迁移到存储容量较小的集群。有关迁移集群的信息，请参阅[迁移至 MSK 集群](migration.md)。
+ 在亚太地区（大阪）、非洲（开普敦）和亚太地区（马来西亚）区域，Amazon MSK 不支持自动扩缩。
+ 当您将自动扩展策略与集群关联时，Amazon EC2 Auto Scaling 会自动创建用于目标跟踪的亚马逊 CloudWatch 警报。如果您使用自动缩放策略删除集群，则此 CloudWatch 警报仍然存在。要删除 CloudWatch 警报，您应该先从集群中移除自动缩放策略，然后再删除该集群。要了解有关目标跟踪的更多信息，请参阅《Amazon EC2 Auto Scaling用户指南》**中的 [Target tracking scaling policies for Amazon EC2 Auto Scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-scaling-target-tracking.html)。
**Topics**
+ [
# Amazon MSK 的自动扩缩策略详细信息
](msk-autoexpand-details.md)
+ [
# 为 Amazon MSK 集群设置自动扩缩
](msk-autoexpand-setup.md)
# Amazon MSK 的自动扩缩策略详细信息
自动扩缩策略为集群定义以下参数：
+ **存储利用率目标**：Amazon MSK 用于触发自动扩缩操作的存储利用率阈值。您可以将此利用率目标设置为当前存储容量的 10% 到 80% 之间。建议您将“存储利用率目标”设置为 50% 到 60% 之间。
+ **最大存储容量**：Amazon MSK 可以为代理存储设置的最大扩展限值。您可以将每个代理的最大存储容量设置为最多 16TiB。有关更多信息，请参阅 [Amazon MSK 限额](limits.md)。
当 Amazon MSK 检测到 `Maximum Disk Utilization` 指标等于或大于 `Storage Utilization Target` 设置时，它会将存储容量增加 10GiB 或当前存储容量的 10%（以较大者为准）。例如，如果您有 1000GiB，则该数量为 100GiB。该服务每分钟检查一次存储利用率。进一步的扩展操作会继续增加存储容量，增幅为 10GiB 或当前存储容量的 10%（以较大者为准）。
要确定是否发生了自动缩放操作，请使用该[ ListClusterOperations](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-operations.html#ListClusterOperations)操作。
# 为 Amazon MSK 集群设置自动扩缩
您可以使用亚马逊 MSK 控制台、亚马逊 MSK API，也可以 CloudFormation 实现存储的自动扩展。 CloudFormation 可通过以下方式获得支持[Application Auto Scaling](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-applicationautoscaling-scalabletarget.html)。
**注意**
创建集群时，您无法实现自动扩缩。您必须先创建集群，然后为其创建并启用自动扩缩策略。但是，您可以在 Amazon MSK 服务创建集群时创建该策略。
**Topics**
+ [
# 使用 Amazon MSK 设置自动缩放 AWS 管理控制台
](msk-autoexpand-setup-console.md)
+ [
# 使用 CLI 设置自动扩缩
](msk-autoexpand-setup-cli.md)
+ [
# 使用 API 为 Amazon MSK 设置自动扩缩
](msk-autoexpand-setup-api.md)
# 使用 Amazon MSK 设置自动缩放 AWS 管理控制台
此过程介绍了如何使用 Amazon MSK 控制台为存储实现自动扩缩。
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择集群。这会将您引导至列出集群详细信息的页面。
1. 在**存储自动扩缩**部分中，选择**配置**。
1. 创建并命名自动扩缩策略。指定存储利用率目标、最大存储容量和目标指标。
1. 选择 `Save changes`。
保存并启用新策略后，该策略将针对该集群变为活动状态。然后，当达到存储利用率目标时，Amazon MSK 会扩展集群的存储。
# 使用 CLI 设置自动扩缩
此过程介绍了如何使用 Amazon MSK CLI 为存储实现自动扩缩。
1. 使用[ RegisterScalableTarget](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/#available-commands)命令注册存储利用率目标。
1. 使用[ PutScalingPolicy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/#available-commands)命令创建自动扩展策略。
# 使用 API 为 Amazon MSK 设置自动扩缩
此过程介绍了如何使用 Amazon MSK API 为存储实现自动扩缩。
1. 使用 [ RegisterScalableTarget](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_RegisterScalableTarget.html)API 注册存储利用率目标。
1. 使用 [ PutScalingPolicy](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_PutScalingPolicy.html)API 创建自动扩展策略。
# 标准代理的手动扩缩
要增加存储空间，请等待集群进入 `ACTIVE` 状态。存储扩展在两次事件之间至少有六个小时的冷却期。虽然该操作会立即提供更多存储空间，但该服务仍会需要 24 小时或更长时间对您的集群执行优化。这些优化会耗费的时长与存储的大小成正比。
## 使用扩展代理存储 AWS 管理控制台
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 选择要更新代理存储的 MSK 集群。
1. 在**存储**部分中选择**编辑**。
1. 指定所需存储量。您只能增加存储量，不能减少存储量。
1. 选择**保存更改**。
## 使用扩展代理存储 AWS CLI
运行以下命令，并将 *ClusterArn* 替换为创建集群时所获取的 Amazon 资源名称（ARN）。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
将 *Current-Cluster-Version* 替换为集群的当前版本。
**重要**
集群版本不是简单的整数。要查找集群的当前版本，请使用[DescribeCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)操作或 desc [ribe-](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI cluster 命令。示例版本是 `KTVPDKIKX0DER`。
该*Target-Volume-in-GiB*参数表示您希望每个经纪商拥有的存储量。只能更新所有代理的存储。您不能指定要更新存储的单个代理。您为指定的值*Target-Volume-in-GiB*必须是大于 100 GiB 的整数。更新操作后每个代理的存储不能超过 16384 GiB。
```
aws kafka update-broker-storage --cluster-arn ClusterArn --current-version Current-Cluster-Version --target-broker-ebs-volume-info '{"KafkaBrokerNodeId": "All", "VolumeSizeGB": Target-Volume-in-GiB}'
```
## 使用 API 纵向扩展代理存储空间
要使用 API 更新代理存储，请参阅[UpdateBrokerStorage](https://docs.aws.amazon.com//msk/1.0/apireference/clusters-clusterarn-nodes-storage.html#UpdateBrokerStorage)。
# 为 Amazon MSK 集群中的标准代理管理存储吞吐量
有关如何使用 Amazon MSK 控制台、CLI 和 API 预置吞吐量的信息，请参阅[为 Amazon MSK 集群中的标准代理预置存储吞吐量](msk-provision-throughput.md)。
**Topics**
+ [
## Amazon MSK 代理吞吐量瓶颈和最大吞吐量设置
](#throughput-bottlenecks)
+ [
## 衡量 Amazon MSK 集群的存储吞吐量
](#throughput-metrics)
+ [
## Amazon MSK 集群中预置存储的配置更新值
](#provisioned-throughput-config)
+ [
# 为 Amazon MSK 集群中的标准代理预置存储吞吐量
](msk-provision-throughput.md)
## Amazon MSK 代理吞吐量瓶颈和最大吞吐量设置
代理吞吐量出现瓶颈的原因有很多：卷吞吐量、Amazon EC2 到 Amazon EBS 的网络吞吐量以及 Amazon EC2 的出口吞吐量。您可以启用预置存储吞吐量来调整卷吞吐量。不过，代理吞吐量限制可能是由 Amazon EC2 到 Amazon EBS 的网络吞吐量和 Amazon EC2 出口吞吐量造成。
Amazon EC2 出口吞吐量受使用器组数量和各使用器组使用器数量的影响。此外，对于较大代理大小，Amazon EC2 到 Amazon EBS 网络吞吐量和 Amazon EC2 出口吞吐量都更高。
对于 10GiB 或更大的卷大小，您可以将存储吞吐量预置为每秒 250MiB 或更高值。默认为每秒 250MiB。要预置存储吞吐量，您必须选择代理大小 kafka.m5.4xlarge 或更大（或 kafka.m7g.2xlarge 或更大），并且您可以指定最大吞吐量，如下表所示。
****
| 代理大小 | 最大存储吞吐量（MiB/s） |
| --- | --- |
| kafka.m5.4xlarge | 593 |
| kafka.m5.8xlarge | 850 |
| kafka.m5.12xlarge | 1000 |
| kafka.m5.16xlarge | 1000 |
| kafka.m5.24xlarge | 1000 |
| kafka.m7g.2xlarge | 312.5 |
| kafka.m7g.4xlarge | 625 |
| kafka.m7g.8xlarge | 1000 |
| kafka.m7g.12xlarge | 1000 |
| kafka.m7g.16xlarge | 1000 |
## 衡量 Amazon MSK 集群的存储吞吐量
您可以使用 `VolumeReadBytes` 和 `VolumeWriteBytes` 指标来衡量集群的平均存储吞吐量。使用这两个指标的总和得出以字节为单位的平均存储吞吐量。要获取集群的平均存储吞吐量，请将这两个指标设置为 SUM，将时长设置为 1 分钟，然后使用以下公式。
```
Average storage throughput in MiB/s = (Sum(VolumeReadBytes) + Sum(VolumeWriteBytes)) / (60 * 1024 * 1024)
```
有关 `VolumeReadBytes` 和 `VolumeWriteBytes` 指标的信息，请参阅[`PER_BROKER` 级别监控](metrics-details.md#broker-metrics)。
## Amazon MSK 集群中预置存储的配置更新值
您可以在开启预置吞吐量之前或之后更新 Amazon MSK 配置。不过，要想看到所需的吞吐量，您必须先执行这两个操作：更新 `num.replica.fetchers` 配置参数和开启预置吞吐量。
在默认 Amazon MSK 配置中，`num.replica.fetchers` 的值为 2。要更新 `num.replica.fetchers`，您可以使用下表中的建议值。这些值仅供参考。建议您根据自己的用例调整这些值。
****
| 代理大小 | num.replica.fetchers |
| --- | --- |
| kafka.m5.4xlarge | 4 |
| kafka.m5.8xlarge | 8 |
| kafka.m5.12xlarge | 14 |
| kafka.m5.16xlarge | 16 |
| kafka.m5.24xlarge | 16 |
更新后的配置可能无法在 24 小时内生效，并且如果源卷未得到充分利用，则可能需要更长时间。不过，在迁移期间，过渡卷的性能至少等于源存储卷的性能。如果 1TiB 卷得到充分利用，通常约需六小时就能迁移到更新后的配置。
# 为 Amazon MSK 集群中的标准代理预置存储吞吐量
Amazon MSK 代理会将数据保存在存储卷上。当生产者向集群写入数据、在代理之间复制数据以及使用者读取不在内存中的数据时，存储空间 I/O 就会被消耗。卷存储吞吐量是指是向存储卷写入数据和从存储卷读取数据的速率。预置存储吞吐量是指可为集群中的代理指定该速率的能力。
您可以为代理大小为 `kafka.m5.4xlarge` 或更大且存储容量为 10GiB 或更高的集群指定预置吞吐量速率（以每秒 MiB 为单位）。可以在创建集群期间指定预置吞吐量。您也可以为处于 `ACTIVE` 状态的集群启用或禁用预置吞吐量。
有关管理吞吐量的信息，请参阅[为 Amazon MSK 集群中的标准代理管理存储吞吐量](msk-provision-throughput-management.md)。
**Topics**
+ [
## 使用预配置 Amazon MSK 集群存储吞吐量 AWS 管理控制台
](#provisioned-throughput-console)
+ [
## 使用预配置 Amazon MSK 集群存储吞吐量 AWS CLI
](#provisioned-throughput-cli)
+ [
## 使用 API 创建 Amazon MSK 集群时预置存储吞吐量
](#provisioned-throughput-api)
## 使用预配置 Amazon MSK 集群存储吞吐量 AWS 管理控制台
此过程显示了一个示例，说明如何使用创建启用预配置吞吐量的 Amazon MSK 集群。 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 选择**创建集群**。
1. 选择**自定义创建**。
1. 指定集群的名称。
1. 在**存储**部分中选择**启用**。
1. 为各代理的存储吞吐量选择一个值。
1. 选择 VPC、可用区、子网和安全组。
1. 选择**下一步**。
1. 在**安全**步骤的底部，选择**下一步**。
1. 在**监控和标记**步骤的底部，选择**下一步**。
1. 检查集群设置，然后选择**创建集群**。
## 使用预配置 Amazon MSK 集群存储吞吐量 AWS CLI
此过程显示了一个示例，说明如何使用创建启用了 AWS CLI 预配置吞吐量的集群。
1. 复制以下 JSON 并将其粘贴到文件中。用您账户中的值替换子网 IDs 和安全组 ID 占位符。为文件 `cluster-creation.json` 命名并保存文件。
```
{
"Provisioned": {
"BrokerNodeGroupInfo":{
"InstanceType":"kafka.m5.4xlarge",
"ClientSubnets":[
"Subnet-1-ID",
"Subnet-2-ID"
],
"SecurityGroups":[
"Security-Group-ID"
],
"StorageInfo": {
"EbsStorageInfo": {
"VolumeSize": 10,
"ProvisionedThroughput": {
"Enabled": true,
"VolumeThroughput": 250
}
}
}
},
"EncryptionInfo": {
"EncryptionInTransit": {
"InCluster": false,
"ClientBroker": "PLAINTEXT"
}
},
"KafkaVersion":"2.8.1",
"NumberOfBrokerNodes": 2
},
"ClusterName": "provisioned-throughput-example"
}
```
1. 从上一步中保存 JSON 文件的目录中运行以下 AWS CLI 命令。
```
aws kafka create-cluster-v2 --cli-input-json file://cluster-creation.json
```
## 使用 API 创建 Amazon MSK 集群时预置存储吞吐量
要在创建集群时配置预配置的存储吞吐量，请使用 [CreateClusterV](https://docs.aws.amazon.com/MSK/2.0/APIReference/v2-clusters.html#CreateClusterV2) 2。
# 预置 Amazon MSK 配置
Amazon MSK 为代理、主题和元数据节点提供默认的配置。您还可以创建自定义配置，并使用这些配置来创建新的 MSK 集群或更新现有集群。MSK 配置由一组属性及其相应的值构成。根据在集群中使用的代理类型，您可以修改一组不同的配置默认值和一组不同的配置。有关如何配置标准代理和快速代理的更多详细信息，请参阅以下部分。
**Topics**
+ [
# 标准代理配置
](msk-configuration-standard.md)
+ [
# 快速代理配置
](msk-configuration-express.md)
+ [
# 代理配置操作
](msk-configuration-operations.md)
# 标准代理配置
本部分介绍了标准代理的配置属性。
**Topics**
+ [
# 自定义 Amazon MSK 配置
](msk-configuration-properties.md)
+ [
# 默认 Amazon MSK 配置
](msk-default-configuration.md)
+ [
# Amazon MSK 分层存储主题级别的配置指南
](msk-guidelines-tiered-storage-topic-level-config.md)
# 自定义 Amazon MSK 配置
您可以使用 Amazon MSK 来创建自定义 MSK 配置，并可以在该配置中设置以下 Apache Kafka 配置属性。未显式设置的属性将获得其在 [默认 Amazon MSK 配置](msk-default-configuration.md) 中具有的值。有关配置属性的更多信息，请参阅 [Apache Kafka 配置](https://kafka.apache.org/documentation/#configuration)。
| Name | 说明 |
| --- | --- |
| allow.everyone.if.no.acl.found | 如果要将此属性设置为false，请先确保为集群定义 Apache Ka ACLs fka。如果将此属性设置为，false但没有先定义 Apache Kafka ACLs，则将失去对集群的访问权限。如果发生这种情况，您可以再次更新配置并将此属性设置为 true，以重新获得对集群的访问权限。 |
| auto.create.topics.enable | 在服务器上启用主题自动创建。 |
| compression.type | 给定主题的最终压缩类型。可以将此属性设置为标准压缩编解码器（gzip、snappy、lz4 和 zstd）。它还接受 uncompressed。此值等同于不压缩。如果将该值设置为 producer，则意味着保留生成器设置的原始压缩编解码器。 |
| connections.max.idle.ms | 空闲连接超时（以毫秒为单位）。如果连接的空闲时间超过您为此属性设置的值，服务器套接字处理器线程会关闭这些连接。 |
| default.replication.factor | 自动创建的主题的默认复制因子。 |
| delete.topic.enable | 启用删除主题操作。如果禁用此设置，则无法通过管理工具删除主题。 |
| group.initial.rebalance.delay.ms | 在组协调器执行第一次重新平衡之前，组协调器等待更多数据使用器加入新组的时间。更长的延迟时间意味着重新平衡可能会更少，但这会增加处理开始之前的时间。 |
| group.max.session.timeout.ms | 注册使用器的最长会话超时时间。超时时间越长，可供使用器用来处理检测信号之间的消息的时间就越多，但这会导致需要花更多时间来检测故障。 |
| group.min.session.timeout.ms | 注册使用器的最短会话超时时间。超时时间越短，故障检测的速度就会越快，但需要更频繁的使用器检测信号。这可能会使代理资源不堪重负。 |
| leader.imbalance.per.broker.percentage | 各代理允许的领导节点不平衡比率。如果各代理超过了此值，则控制器将触发领导平衡操作。此值以百分比的形式指定。 |
| log.cleaner.delete.retention.ms | 您希望 Apache Kafka 保留已删除的记录的时间量。最小值为 0。 |
| log.cleaner.min.cleanable.ratio | 此配置属性的值可介于 0 到 1 之间。此值决定日志压缩器尝试清理日志的频率（如果日志压缩已启用）。默认情况下，如果已压缩超过 50% 的日志，Apache Kafka 会避免清理日志。这一比率限制了日志因重复项浪费的最大空间（该值为 50%，这意味着最多有 50% 的日志可能是重复的）。更高的比率意味着更少、更高效的清理，但也意味着会浪费更多的日志空间。 |
| log.cleanup.policy | 超出保留时段的分段的默认清除策略。有效策略的逗号分隔列表。有效策略为 delete 和 compact。对于启用了分层存储的集群，有效策略为仅 delete。 |
| log.flush.interval.messages | 将消息刷新到磁盘之前，日志分区上累积的消息的数量。 |
| log.flush.interval.ms | 任何主题中的消息在刷新到磁盘之前保存在内存中的最长时间（以毫秒为单位）。如果未设置此值，则使用 log.flush.scheduler.interval.ms 中的值。最小值为 0。 |
| log.message.timestamp.difference.max.ms | Kafka 3.6.0 中已弃用此配置。添加了两种配置，即 log.message.timestamp.before.max.ms 和 log.message.timestamp.after.max.ms。代理收到消息时的时间戳与消息中指定的时间戳之间的最大时间差。如果 log.message.timestamp.type=CreateTime，则如果时间戳的差异超过此阈值，则消息将被拒绝。如果 log.message.timestamp.type LogAppendTime =，则忽略此配置。 |
| log.message.timestamp.type | 指定消息中的时间戳是消息创建时间还是日志追加时间。允许的值是 CreateTime 和 LogAppendTime。 |
| log.retention.bytes | 删除日志前的最大日志大小。 |
| log.retention.hours | 删除日志文件前保留日志文件的小时数，它是 log.retention.ms 属性的三级属性。 |
| log.retention.minutes | 删除日志文件前保留日志文件的分钟数，它是 log.retention.ms 属性的二级属性。如果未设置此值，则使用 log.retention.hours 中的值。 |
| log.retention.ms | 删除日志文件前保留日志文件的毫秒数（以毫秒为单位）。如果未设置，则使用 log.retention.minutes 中的值。 |
| log.roll.ms | 推出新日志段之前的最长时间（以毫秒为单位）。如果未设置此属性，则使用 log.roll.hours 中的值。此属性的最小可能值为 1。 |
| log.segment.bytes | 单个日志文件的最大大小。 |
| max.incremental.fetch.session.cache.slots | 维护的增量提取会话的最大数量。 |
| message.max.bytes | Kafka 允许的最大记录批处理大小。如果增加此值，并且存在大于 0.10.2 的使用器，则使用器的提取大小也必须增加，以便它们能够提取如此大的记录批处理。 最新的消息格式版本总是将消息分组到批处理中来提高效率。以前的消息格式版本不会将未压缩的记录分组到批处理中，在此情况下，此限制仅适用于单条记录。 可使用主题级别 max.message.bytes 配置为每个主题设置此值。 |
| min.insync.replicas | 当生成器将 acks 设置为 `"all"`（或 `"-1"`）时，min.insync.replicas 中的值会指定为使写入被视为成功而必须确认写入的最小副本数。如果无法达到此最低限度，则生产者会引发异常（ NotEnoughReplicas 或 NotEnoughReplicasAfterAppend）。 您可以使用 min.insync.replicas 和 acks 中的值来强制执行更大的持久性保证。例如，您可以创建复制因子为 3 的主题，将 min.insync.replicas 设置为 2，并在 acks 为 `"all"` 的情况下进行生成。这可确保在大多数副本未收到写操作时，创建器将引发异常。 |
| num.io.threads | 服务器用于处理请求的线程的数目，其中可能包括磁盘 I/O。 |
| num.network.threads | 服务器用于接收来自网络的请求并向其发送响应的线程数量。 |
| num.partitions | 每个主题的默认日志分区数。 |
| num.recovery.threads.per.data.dir | 在启动时用于日志恢复以及在关闭时用于刷新的每个数据目录的线程数量。 |
| num.replica.fetchers | 用于从源代理复制消息的提取器线程数。如果您增加此值，则可以提高关注者经纪人的 I/O 并行程度。 |
| offsets.retention.minutes | 当一个使用器组丢失其所有使用器（即变空）后，其偏移量将在此保留期内保留，然后被丢弃。对于独立使用器（即，使用手动分配的使用器），偏移量会在最后一次提交时间加上此保留期后过期。 |
| offsets.topic.replication.factor | 偏移量主题的复制因子。将此值设置得更高可以确保可用性。内部主题创建失败，直到集群大小满足此复制因子要求。 |
| replica.fetch.max.bytes | 尝试为每个分区提取的消息的字节数。这不是绝对最大值。如果提取的第一个非空分区中的第一个记录批处理大于此值，则将返回该记录批处理以确保取得进展。message.max.bytes（代理配置）或 max.message.bytes（主题配置）定义代理接受的最大记录批处理大小。 |
| replica.fetch.response.max.bytes | 整个提取响应预期的最大字节数。记录是分批提取的，如果提取的第一个非空分区中的第一个记录批处理大于此值，则仍将返回该记录批处理以确保取得进展。这不是绝对最大值。message.max.bytes（代理配置）或 max.message.bytes（主题配置）属性指定代理接受的最大记录批处理大小。 |
| replica.lag.time.max.ms | 如果跟踪器没有发送任何提取请求，或者至少在此毫秒数内没有使用到领导的日志结束偏移量，则领导会从 ISR 中删除追随者。MinValue: 10000MaxValue = 30000 |
| replica.selector.class | 实现 ReplicaSelector的完全限定类名。代理使用此值来查找首选读取副本。如果您使用的是 Apache Kafka 版本 2.4.1 或更高版本，并且希望允许使用器从最近的副本提取，请将此属性设置为 org.apache.kafka.common.replica.RackAwareReplicaSelector。有关更多信息，请参阅 [Apache Kafka 版本 2.4.1（改用 2.4.1.1 版）](supported-kafka-versions.md#2.4.1)。 |
| replica.socket.receive.buffer.bytes | 网络请求的套接字接收缓冲区。 |
| socket.receive.buffer.bytes | 套接字服务器套接字的 SO\$1RCVBUF 缓冲区。可为此属性设置的最小值为 -1。如果该值为 -1，则 Amazon MSK 使用 OS 默认值。 |
| socket.request.max.bytes | 套接字请求中的最大字节数。 |
| socket.send.buffer.bytes | 套接字服务器套接字的 SO\$1SNDBUF 缓冲区。可为此属性设置的最小值为 -1。如果该值为 -1，则 Amazon MSK 使用 OS 默认值。 |
| transaction.max.timeout.ms | 事务的最大超时时间。如果客户请求的交易时间超过此值，则经纪商会在中返回错误 InitProducerIdRequest。这可防止客户端的超时时间过长，且此情况可能会导致使用器无法阅读事务中包含的主题。 |
| transaction.state.log.min.isr | 事务主题的已覆盖 min.insync.replicas 配置。 |
| transaction.state.log.replication.factor | 事务主题的复制因子。将此属性设置为较高的值可提高可用性。内部主题创建失败，直到集群大小满足此复制因子要求。 |
| transactional.id.expiration.ms | 事务协调器在其事务 ID 过期之前，等待接收当前事务的任何事务状态更新的时间（以毫秒为单位）。此设置还会影响生产者 ID 的过 IDs期，因为它会导致生产者在最后一次使用给定生产者 ID 写入后过期时过期。如果由于主题的保留设置而删除了制作人 ID 的最后一次写入内容，则制作人 IDs 可能会提前过期。此属性的最小值为 1 毫秒。 |
| unclean.leader.election.enable | 表示不在 ISR 集中的副本是否应作为最后手段充当领导，即使这可能会导致数据丢失。 |
| zookeeper.connection.timeout.ms | ZooKeeper 模式集群。客户端等待与之建立连接的最长时间。 ZooKeeper如果未设置此值，则使用 zookeeper.session.timeout.ms 中的值。 MinValue = 6000 MaxValue （含）= 18000 建议在 t3.small 上将此值设置为 10,000，以防止集群停机。 |
| zookeeper.session.timeout.ms | ZooKeeper 模式集群。Apache ZooKeeper 会话超时时间（以毫秒为单位）。 MinValue = 6000 MaxValue （含）= 18000 |
要了解如何创建自定义 MSK 配置、列出所有配置或描述它们，请参阅[代理配置操作](msk-configuration-operations.md)。要使用自定义 MSK 配置创建 MSK 集群或使用新的自定义配置更新集群，请参阅[Amazon MSK 的关键功能和概念](operations.md)。
当您使用自定义 MSK 配置更新现有 MSK 集群时，Amazon MSK 会在必要时重新开始滚动，并使用最佳实践来最大程度地减少客户停机时间。例如，在 Amazon MSK 重新启动每个代理后，Amazon MSK 会尝试让代理获得其在配置更新期间可能缺失的数据，然后再移至下一个代理。
## 动态 Amazon MSK 配置
除了 Amazon MSK 提供的配置属性之外，您还可以动态设置不要求代理重新启动的集群级别和代理级别的配置属性。您可以动态设置一些配置属性。这些是 Apache Kafka 文档中[代理配置](https://kafka.apache.org/documentation/#brokerconfigs)下的表中未标记为只读的属性。有关动态配置和示例命令的信息，请参阅 Apache Kafka 文档中的[更新代理配置](https://kafka.apache.org/documentation/#dynamicbrokerconfigs)。
**注意**
您可以设置 `advertised.listeners` 属性，但不能设置 `listeners` 属性。
## 主题级别的 Amazon MSK 配置
您可以使用 Apache Kafka 命令为新主题和现有主题设置或修改主题级别的配置属性。有关主题级别的配置属性以及如何设置这些属性之示例的更多信息，请参阅 Apache Kafka 文档中的 [Topic-Level Configs](https://kafka.apache.org/documentation/#topicconfigs)。
# 默认 Amazon MSK 配置
在未指定自定义 MSK 配置的情况下创建 MSK 集群时，Amazon MSK 会创建默认配置，并将此配置与下表中显示的值结合使用。对于不在此表中的属性，Amazon MSK 将使用与您的 Apache Kafka 版本关联的默认值。有关这些默认值的列表，请参阅 [Apache Kafka 配置](https://kafka.apache.org/documentation/#configuration)。
| Name | 说明 | 非分层存储集群的默认值 | 启用了分层存储的集群的默认值 |
| --- | --- | --- | --- |
| allow.everyone.if.no.acl.found | 如果没有资源模式与特定资源匹配，则该资源没有关联 ACLs。在本例中，如果将此属性设置为 true，则所有用户（而不仅仅是超级用户）均可访问该资源。 | true | true |
| auto.create.topics.enable | 在服务器上启用主题的自动创建。 | false | false |
| auto.leader.rebalance.enable | 启用自动领导平衡。如果需要，后台线程会定期检查并启动领导平衡。 | true | true |
| default.replication.factor | 自动创建的主题的默认复制因子。 | 3 表示位于 3 个可用区中的集群，2 表示位于 2 个可用区中的集群。 | 3 表示位于 3 个可用区中的集群，2 表示位于 2 个可用区中的集群。 |
| local.retention.bytes | 分区在删除旧日志段之前的最大本地日志段大小。如果未设置此值，则使用 log.retention.bytes 中的值。有效值应始终小于或等于 log.retention.bytes 值。默认值 -2 表示对本地保留没有限制。这与 retention.ms/bytes 的设置 -1 相对应。local.retention.ms 和 local.retention.bytes 属性与 log.retention 类似，因为它们用于确定日志段应在本地存储中保留多长时间。现有的 log.retention.\$1 配置是主题分区的保留配置。这包括本地存储和远程存储。有效值：[-2; \$1Inf] 中的整数 | -2 表示无限制 | -2 表示无限制 |
| local.retention.ms | 删除之前保留本地日志段的毫秒数。如果未设置此值，Amazon MSK 使用 log.retention.ms 中的值。有效值应始终小于或等于 log.retention.bytes 值。默认值 -2 表示对本地保留没有限制。这与 retention.ms/bytes 的设置 -1 相对应。local.retention.ms 和 local.retention.bytes 值类似于 log.retention。MSK 使用此配置确定日志段应在本地存储中保留多长时间。现有的 log.retention.\$1 配置是主题分区的保留配置。这包括本地存储和远程存储。有效值为大于 0 的整数。 | -2 表示无限制 | -2 表示无限制 |
| log.message.timestamp.difference.max.ms | Kafka 3.6.0 中已弃用此配置。添加了两种配置，即 log.message.timestamp.before.max.ms 和 log.message.timestamp.after.max.ms。代理收到消息时的时间戳与消息中指定的时间戳之间允许的最大差异。如果 log.message.timestamp.type=CreateTime，则如果时间戳的差异超过此阈值，则消息将被拒绝。如果 log.message.timestamp.type LogAppendTime =，则忽略此配置。允许的最大时间戳差异不应大于 log.retention.ms，以避免不必要的频繁日志滚动。 | 9223372036854775807 | Kafka 2.8.2 分层存储和 Kafka 3.7.x 分层存储为 86400000。 |
| log.segment.bytes | 单个日志文件的最大大小。 | 1073741824 | 134217728 |
| min.insync.replicas | 当生成器将 acks 的值（确认生成器从 Kafka 代理获得）设置为 `"all"`（或 `"-1"`）时，min.insync.replicas 中的值会指定为使写入被视为成功而必须确认写入的最小副本数。如果此值未达到此最小值，则生产者会引发异常（ NotEnoughReplicas 或 NotEnoughReplicasAfterAppend）。 当您同时使用 min.insync.replicas 和 acks 中的值时，可以强制执行更大的持久性保证。例如，您可以创建复制因子为 3 的主题，将 min.insync.replicas 设置为 2，并在 acks 为 `"all"` 的情况下进行生成。这可确保在大多数副本未收到写操作时，创建器将引发异常。 | 2 表示位于 3 个可用区中的集群，1 表示位于 2 个可用区中的集群。 | 2 表示位于 3 个可用区中的集群，1 表示位于 2 个可用区中的集群。 |
| num.io.threads | 服务器用于生成请求的线程的数量，其中可能包括磁盘 I/O。 | 8 | max (8, vCPUs) 其中 v CPUs 取决于代理的实例大小 |
| num.network.threads | 服务器用于接收来自网络的请求并向网络发送响应的线程数量。 | 5 | max (5, v CPUs /2) 其中 v CPUs 取决于代理的实例大小 |
| num.partitions | 每个主题的默认日志分区数。 | 1 | 1 |
| num.replica.fetchers | 用于从源代理复制消息的提取器线程数。如果增加此值，则可以提高关注者代理中的 I/O 并行度。 | 2 | max (2, v CPUs /4) 其中 v CPUs 取决于代理的实例大小 |
| remote.log.msk.disable.policy | 与 remote.storage.enable 一起使用以禁用分层存储。将此策略设置为“删除”，以表示在将 remote.storage.enable 设置为 false 时，分层存储中的数据将被删除。 | 不适用 | 无 |
| remote.log.reader.threads | 远程日志读取器线程池大小，用于安排任务以从远程存储中提取数据。 | 不适用 | max (10, v CPUs \$1 0.67) 其中 v CPUs 取决于代理的实例大小 |
| remote.storage.enable | 如果设置为 true，则为主题启用分层（远程）存储。如果设置为 false，且 remote.log.msk.disable.policy 设置为“删除”，则禁用主题级别的分层存储。禁用分层存储时，会从远程存储中删除数据。禁用主题的分层存储时，无法再次启用分层存储。 | false | false |
| replica.lag.time.max.ms | 如果跟踪器没有发送任何提取请求，或者至少在此毫秒数内没有使用到领导的日志结束偏移量，则领导会从 ISR 中删除追随者。 | 30000 | 30000 |
| retention.ms | 必填字段。最短时间为 3 天。该设置是强制性的，因此没有默认值。 Amazon MSK 使用 retention.ms value 与 local.retention.ms 来确定数据何时从本地存储移动到分层存储。local.retention.ms 值指定何时将数据从本地存储移动到分层存储。retention.ms 值指定何时从分层存储中删除数据（即从集群中删除）。有效值：[-1; \$1Inf] 中的整数 | 最少 259,200,000 毫秒（3 天）。-1 表示无限保留。 | 最少 259,200,000 毫秒（3 天）。-1 表示无限保留。 |
| socket.receive.buffer.bytes | 套接字服务器套接字的 SO\$1RCVBUF 缓冲区。如果值为 -1，则使用操作系统默认值。 | 102400 | 102400 |
| socket.request.max.bytes | 套接字请求中的最大字节数。 | 104857600 | 104857600 |
| socket.send.buffer.bytes | 套接字服务器套接字的 SO\$1SNDBUF 缓冲区。如果值为 -1，则使用操作系统默认值。 | 102400 | 102400 |
| unclean.leader.election.enable | 表示您是否希望不在 ISR 集中的副本作为最后手段充当领导，即使这可能会导致数据丢失。 | true | false |
| zookeeper.session.timeout.ms | Apache ZooKeeper 会话超时时间（以毫秒为单位）。 | 18000 | 18000 |
| zookeeper.set.acl | 设置为安全使用的客户端 ACLs。 | false | false |
有关如何指定自定义配置值的信息，请参阅[自定义 Amazon MSK 配置](msk-configuration-properties.md)。
# Amazon MSK 分层存储主题级别的配置指南
以下是在主题级别配置分层存储时的默认设置和限制。
+ 对于已激活分层存储的主题，Amazon MSK 不支持较小的日志段大小。如果要创建日志段，则最小段大小为 48MiB，或最短段滚动时间为 10 分钟。这些值映射到 segment.bytes 和 segment.ms 属性。
+ 本地保留的价值。 ms/bytes can't equal or exceed the retention.ms/bytes。这是分层存储保留设置。
+ local.retention 的默认值。 ms/bytes is -2. This means that the retention.ms value is used for local.retention.ms/bytes。在这种情况下，数据将同时保留在本地存储和分层存储中（每个存储中各有一个副本），且会一起过期。对于此选项，本地数据的副本会保留到远程存储中。在这种情况下，从使用流量中读取的数据来自本地存储。
+ retention.ms 的默认值为 7 天。retention.bytes 没有默认大小限制。
+ retention.ms/bytes 的最小值为 -1。这意味着无限保留。
+ 本地保留的最小值。 ms/bytes is -2. This means infinite retention for local storage. It matches with the retention.ms/bytes设置为 -1。
+ 对于已激活分层存储的主题，必须使用主题级别配置 retention.ms。最小 retention.ms 为 3 天。
有关分层存储限制的更多信息，请参阅[Amazon MSK 集群的分层存储约束和限制](msk-tiered-storage.md#msk-tiered-storage-constraints)。
# 快速代理配置
Apache Kafka 有几百种代理配置，您可以使用这些配置调整预置 MSK 集群的性能。设置值错误或不太理想可能会影响集群的可靠性和性能。快速代理通过为关键配置设置最佳值并防止出现常见配置错误，提高了预置 MSK 集群的可用性和持久性。基于读写访问的配置分为三类：[读/写（可编辑）](msk-configuration-express-read-write.md)、[只读](msk-configuration-express-read-only.md)和非读/写配置。对于集群正在运行的 Apache Kafka 版本，某些配置仍使用 Apache Kafka 的默认值。我们将其标记为 Apache Kafka 默认值。
**Topics**
+ [
# 自定义 MSK 快速代理配置（读/写访问）
](msk-configuration-express-read-write.md)
+ [
# 快速代理的只读配置
](msk-configuration-express-read-only.md)
# 自定义 MSK 快速代理配置（读/写访问）
您可以使用亚马逊 MSK 的更新配置[功能或 Apache Kafka 的 API 来更新 read/write 代理配置](msk-update-cluster-config.md)。 AlterConfig Apache Kafka 的代理配置是静态的，也可以是动态的。静态配置需要重新启动代理才能应用配置，而动态配置不需要重启代理。有关配置属性和更新模式的更多信息，请参阅[更新代理配置](https://kafka.apache.org/documentation/#dynamicbrokerconfigs)。
**Topics**
+ [
## MSK 快速代理的静态配置
](#msk-configuration-express-static-configuration)
+ [
## 快速代理的动态配置
](#msk-configuration-express-dynamic-configuration)
+ [
## 快速代理上的主题级别配置
](#msk-configuration-express-topic-configuration)
## MSK 快速代理的静态配置
您可以使用 Amazon MSK 来创建自定义 MSK 配置文件，以设置以下静态属性。Amazon MSK 可设置并管理其他所有未设置的属性。可以从 MSK 控制台或使用[配置命令](msk-configuration-operations-create.md)创建并更新静态配置文件。
| 属性 | 说明 | 默认值 |
| --- | --- | --- |
| allow.everyone.if.no.acl.found | 如果要将此属性设置为 false，请首先确保 ACLs 为集群定义 Apache Kafka。如果您将此属性设置为 false 并且没有首先定义 Apache Kafka ACLs，则将失去对集群的访问权限。如果发生这种情况，您可以再次更新配置并将此属性设置为 true，以重新获得对集群的访问权限。 | true |
| auto.create.topics.enable | 在服务器上启用主题的自动创建。 | false |
| compression.type | 指定给定主题的最终压缩类型。此配置接受以下标准压缩编解码器：gzip、snappy、lz4、zstd。 该配置还接受 `uncompressed` 和 `producer`，前者相当于没有压缩，后者意味着保留由创建器设置的原始压缩编解码器。 | Apache Kafka 默认值 |
| connections.max.idle.ms | 空闲连接超时（以毫秒为单位）。如果连接的空闲时间超过您为此属性设置的值，服务器套接字处理器线程会关闭这些连接。 | Apache Kafka 默认值 |
| delete.topic.enable | 启用删除主题操作。如果禁用此设置，则无法通过管理工具删除主题。 | Apache Kafka 默认值 |
| group.initial.rebalance.delay.ms | 在组协调器执行第一次重新平衡之前，组协调器等待更多数据使用器加入新组的时间。更长的延迟时间意味着重新平衡可能会更少，但这会增加处理开始之前的时间。 | Apache Kafka 默认值 |
| group.max.session.timeout.ms | 注册使用器的最长会话超时时间。超时时间越长，可供使用器用来处理检测信号之间的消息的时间就越多，但这会导致需要花更多时间来检测故障。 | Apache Kafka 默认值 |
| leader.imbalance.per.broker.percentage | 各代理允许的领导节点不平衡比率。如果各代理超过了此值，则控制器将触发领导平衡操作。此值以百分比的形式指定。 | Apache Kafka 默认值 |
| log.cleanup.policy | 超出保留时段的分段的默认清除策略。有效策略的逗号分隔列表。有效策略为 delete 和 compact。对于启用了分层存储的集群，有效策略为仅 delete。 | Apache Kafka 默认值 |
| log.message.timestamp.after.max.ms | 消息时间戳和代理时间戳之间允许的时间戳差。消息时间戳可晚于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。 如果 `log.message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `log.message.timestamp.type=LogAppendTime`，此配置将被忽略。 | 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天） |
| log.message.timestamp.before.max.ms | 代理时间戳和消息时间戳之间允许的时间戳差。消息时间戳可早于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。 如果 `log.message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `log.message.timestamp.type=LogAppendTime`，此配置将被忽略。 | 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天） |
| log.message.timestamp.type | 指定消息中的时间戳是消息创建时间还是日志追加时间。允许的值是 CreateTime 和 LogAppendTime。 | Apache Kafka 默认值 |
| log.retention.bytes | 删除日志前的最大日志大小。 | Apache Kafka 默认值 |
| log.retention.ms | 日志文件删除之前保留的毫秒数。 | Apache Kafka 默认值 |
| max.connections.per.ip | 每个 IP 地址经许可的最大连接数。如果使用 max.connections.per.ip.overrides 属性配置了覆盖，则可以将其设置为 0。如果达到限制，来自该 IP 地址的新连接将被丢弃。 | Apache Kafka 默认值 |
| max.incremental.fetch.session.cache.slots | 维护的增量提取会话的最大数量。 | Apache Kafka 默认值 |
| message.max.bytes | Kafka 允许的最大记录批处理大小。如果增加此值，并且存在大于 0.10.2 的使用器，则使用器的提取大小也必须增加，以便它们能够提取如此大的记录批处理。 最新的消息格式版本总是将消息分组到批处理中来提高效率。以前的消息格式版本不会将未压缩的记录分组到批处理中，在此情况下，此限制仅适用于单条记录。可使用主题级别 `max.message.bytes` 配置为每个主题设置此值。 | Apache Kafka 默认值 |
| num.partitions | 每个主题的默认分区数。 | 1 |
| offsets.retention.minutes | 当一个使用器组丢失其所有使用器（即变空）后，其偏移量将在此保留期内保留，然后被丢弃。对于独立使用器（即，使用手动分配的使用器），偏移量会在最后一次提交时间加上此保留期后过期。 | Apache Kafka 默认值 |
| replica.fetch.max.bytes | 尝试为每个分区提取的消息的字节数。这不是绝对最大值。如果提取的第一个非空分区中的第一个记录批处理大于此值，则将返回该记录批处理以确保取得进展。message.max.bytes（代理配置）或 max.message.bytes（主题配置）定义代理接受的最大记录批处理大小。 | Apache Kafka 默认值 |
| replica.selector.class | 实现 ReplicaSelector的完全限定类名。代理使用此值来查找首选读取副本。如果您希望允许使用者从最近的副本提取，请将此属性设置为 `org.apache.kafka.common.replica.RackAwareReplicaSelector`。 | Apache Kafka 默认值 |
| socket.receive.buffer.bytes | 套接字服务器套接字的 SO\$1RCVBUF 缓冲区。如果值为 -1，则使用操作系统默认值。 | 102400 |
| socket.request.max.bytes | 套接字请求中的最大字节数。 | 104857600 |
| socket.send.buffer.bytes | 套接字服务器套接字的 SO\$1SNDBUF 缓冲区。如果值为 -1，则使用操作系统默认值。 | 102400 |
| transaction.max.timeout.ms | 事务的最大超时时间。如果客户请求的交易时间超过此值，则经纪商会在中返回错误 InitProducerIdRequest。这可防止客户端的超时时间过长，且此情况可能会导致使用器无法阅读事务中包含的主题。 | Apache Kafka 默认值 |
| transactional.id.expiration.ms | 事务协调器在其事务 ID 过期之前，等待接收当前事务的任何事务状态更新的时间（以毫秒为单位）。此设置还会影响生产者 ID 的过期，因为它会导致生产者 IDs 在最后一次使用给定生产者 ID 写入后过期时过期。如果由于主题的保留设置而删除了制作人 ID 的最后一次写入内容，则制作人 IDs 可能会提前过期。此属性的最小值为 1 毫秒。 | Apache Kafka 默认值 |
## 快速代理的动态配置
你可以使用 Apache Kafka AlterConfig API 或 Kafka-configs.sh 工具来编辑以下动态配置。Amazon MSK 可设置并管理其他所有未设置的属性。您可以动态设置不要求代理重新启动的集群级别和代理级别的配置属性。
| 属性 | 说明 | 默认 值 |
| --- | --- | --- |
| advertised.listeners | 发布以供客户端使用的侦听器（如果与 `listeners` 配置属性不同）。在 IaaS 环境中，这可能需要与代理绑定的接口不同。如果未指定，则将使用侦听器的值。与侦听器不同，传播 0.0.0.0 元地址是无效的。 此外与 `listeners` 不同的是，此属性中可能存在重复的端口，因此可配置一个侦听器来传播另一个侦听器的地址。在使用外部负载均衡器的某些情况下，这可能很有用。 此属性是根据每个代理设置的。 | null |
| compression.type | 给定主题的最终压缩类型。可以将此属性设置为标准压缩编解码器（`gzip`、`snappy`、`lz4` 和 `zstd`）。它还接受 `uncompressed`。此值等同于不压缩。如果将该值设置为 `producer`，则意味着保留生成器设置的原始压缩编解码器。 | Apache Kafka 默认值 |
| log.cleaner.delete.retention.ms | 为日志压缩主题保留删除逻辑标记的时间。此设置还规定了使用者从偏移量 0 开始时必须完成读取的时间限制，以确保获得最后阶段的有效快照。否则，删除逻辑可能会在完成扫描之前进行收集。 | 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天），Apache Kafka 默认值 |
| log.cleaner.min.compaction.lag.ms | 消息在日志中保持未压缩状态的最短时间。此设置仅适用于当前压缩的日志。 | 0，Apache Kafka 默认值 |
| log.cleaner.max.compaction.lag.ms | 消息在日志中一直不符合压缩条件的最长时间。此设置仅适用于当前压缩的日志。该配置将限制在 [7 天，Long.Max] 范围内。 | 9223372036854775807，Apache Kafka 默认值 |
| log.cleanup.policy | 超出保留时段的分段的默认清除策略。有效策略的逗号分隔列表。有效策略为 `delete` 和 `compact`。对于启用了分层存储的集群，有效策略为仅 `delete`。 | Apache Kafka 默认值 |
| log.message.timestamp.after.max.ms | 消息时间戳和代理时间戳之间允许的时间戳差。消息时间戳可晚于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。如果 `log.message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `log.message.timestamp.type=LogAppendTime`，此配置将被忽略。 | 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天） |
| log.message.timestamp.before.max.ms | 代理时间戳和消息时间戳之间允许的时间戳差。消息时间戳可早于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。如果 `log.message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `log.message.timestamp.type=LogAppendTime`，此配置将被忽略。 | 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天） |
| log.message.timestamp.type | 指定消息中的时间戳是消息创建时间还是日志追加时间。允许的值是 `CreateTime` 和 `LogAppendTime`。 | Apache Kafka 默认值 |
| log.retention.bytes | 删除日志前的最大日志大小。 | Apache Kafka 默认值 |
| log.retention.ms | 日志文件删除之前保留的毫秒数。 | Apache Kafka 默认值 |
| max.connection.creation.rate | 代理在任何时间经许可的最大连接创建速率。 | Apache Kafka 默认值 |
| max.connections | 代理在任何时间经许可的最大连接数。此限制叠加在使用 `max.connections.per.ip` 配置的每个 IP 限制之上。 | Apache Kafka 默认值 |
| max.connections.per.ip | 每个 IP 地址经许可的最大连接数。如果使用 max.connections.per.ip.overrides 属性配置了覆盖，则可以将其设置为 `0`。如果达到限制，来自该 IP 地址的新连接将被丢弃。 | Apache Kafka 默认值 |
| max.connections.per.ip.overrides | 用逗号分隔的列表，支持按 IP 地址或主机名覆盖默认最大连接数。示例值为 `hostName:100,127.0.0.1:200`。 | Apache Kafka 默认值 |
| message.max.bytes | Kafka 允许的最大记录批处理大小。如果增加此值，并且存在大于 0.10.2 的使用器，则使用器的提取大小也必须增加，以便它们能够提取如此大的记录批处理。最新的消息格式版本总是将消息分组到批处理中来提高效率。以前的消息格式版本不会将未压缩的记录分组到批处理中，在此情况下，此限制仅适用于单条记录。可使用主题级别 `max.message.bytes` 配置为每个主题设置此值。 | Apache Kafka 默认值 |
| producer.id.expiration.ms | 主题分区负责人在制作 IDs人到期之前等待的时间（以毫秒为单位）。当与其关联的交易仍在进行时，Producer IDs 不会过期。请注意，如果由于主题的保留设置而删除了制作人 ID 的最后一次写入内容，则创建者 IDs 可能会提前过期。此值设置为等于或大于 `delivery.timeout.ms` 有助于防止在重试期间过期并避免消息重复，但是对于大多数用例来说，默认值应该是合理的设置。 | Apache Kafka 默认值 |
## 快速代理上的主题级别配置
您可以使用 Apache Kafka 命令为新主题和现有主题设置或修改主题级别的配置属性。如果无法提供任何主题级别的配置，Amazon MSK 会使用代理默认值。与代理级别的配置一样，Amazon MSK 可保护某些主题级别的配置属性免受更改。例如复制因子 `min.insync.replicas` 和 `unclean.leader.election.enable`。如果尝试创建复制因子值不为 `3` 的主题，Amazon MSK 将默认创建复制因子为 `3` 的主题。有关主题级别的配置属性以及如何设置这些属性之示例的更多信息，请参阅 Apache Kafka 文档中的 [Topic-Level Configs](https://kafka.apache.org/documentation/#topicconfigs)。
| 属性 | 说明 |
| --- | --- |
| cleanup.policy | 此配置指定要在日志段上使用的保留策略。“删除”策略（默认设置）将在达到保留时间或大小限制时丢弃旧分段。“压缩”策略将启用日志压缩，保留每个键的最新值。也可以在逗号分隔的列表中指定这两个策略（例如，“删除、压缩”）。在这种情况下，将根据保留时间和大小配置丢弃旧分段，而对保留的分段进行压缩。分区中的数据达到 256 MB 后将触发快速代理上的压缩。 |
| compression.type | 指定给定主题的最终压缩类型。此配置接受标准压缩编解码器（`gzip`、`snappy`、`lz4`、`zstd`）。此外，它还接受 `uncompressed` 和 `producer`，前者相当于没有压缩，后者意味着保留由创建器设置的原始压缩编解码器。 |
| delete.retention.ms | 为日志压缩主题保留删除逻辑标记的时间。此设置还规定了使用者从偏移量 0 开始时必须完成读取的时间限制，以确保获得最后阶段的有效快照。否则，删除逻辑可能会在完成扫描之前进行收集。 此设置的默认值为 86400000（24 \$1 60 \$1 60 \$1 1000 毫秒，即 1 天），Apache Kafka 默认值 |
| max.message.bytes | Kafka 允许的最大记录批处理大小（启用压缩时的压缩后值）。如果增加此数量，并且存在大于 `0.10.2` 的使用器，则使用器的提取大小也必须增加，以便它们能够提取如此大的记录批处理。在最新的消息格式版本中，总是将记录分组到批处理中来提高效率。在以前的消息格式版本中，未压缩的记录不会分组到批处理中，在此情况下，此限制仅适用于单条记录。可使用主题级别 `max.message.bytes config`，根据各个主题进行设置。 |
| message.timestamp.after.max.ms | 此配置设置了消息时间戳和代理时间戳之间允许的时间戳差。消息时间戳可晚于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。如果 `message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `message.timestamp.type=LogAppendTime`，此配置将被忽略。 |
| message.timestamp.before.max.ms | 此配置设置了代理时间戳和消息时间戳之间允许的时间戳差。消息时间戳可早于代理时间戳，也可以为同一时间，允许的最大差值取决于此配置中设置的值。如果 `message.timestamp.type=CreateTime`，则当时间戳差超过此指定阈值时，消息将被拒绝。如果 `message.timestamp.type=LogAppendTime`，此配置将被忽略。 |
| message.timestamp.type | 定义消息中的时间戳是消息创建时间还是日志追加时间。该值应该是 `CreateTime` 或 `LogAppendTime`。 |
| min.compaction.lag.ms | 消息在日志中保持未压缩状态的最短时间。此设置仅适用于当前压缩的日志。 此设置的默认值为 0，Apache Kafka 默认值 |
| max.compaction.lag.ms | 消息在日志中一直不符合压缩条件的最长时间。此设置仅适用于当前压缩的日志。该配置将限制在 [7 天，Long.Max] 范围内。 此设置的默认值为 9223372036854775807，Apache Kafka 默认值。 |
| retention.bytes | 如果使用“删除”保留策略，此配置可控制分区（由日志段组成）在丢弃旧日志段释放空间之前可以增长到的最大大小。默认没有大小限制，只有时间限制。由于此限制是在分区级别强制执行的，因此将其乘以分区数即可计算出主题保留容量（以字节为单位）。此外，`retention.bytes configuration` 独立于 `segment.ms` 和 `segment.bytes` 配置运行。此外，如果将 `retention.bytes` 配置为零，则会触发新分段的滚动出现。 |
| retention.ms | 如果使用“删除”保留策略，此配置可控制在丢弃旧日志段释放空间之前保留日志的最长时间。这代表使用者必须在多长时间内读取其数据的 SLA。如果设置为 `-1`，则不应用时间限制。此外，`retention.ms` 配置独立于 `segment.ms` 和 `segment.bytes` 配置运行。此外，如果满足 `retention.ms` 条件，还会触发新分段的滚动出现。 |
# 快速代理的只读配置
Amazon MSK 会为这些配置设置值，并防止遭到更改，以免影响集群的可用性。这些值可能会根据集群上运行的 Apache Kafka 版本而变化，因此请记住检查特定集群的值。
下表列出了快速代理的只读配置。
| 属性 | 说明 | 快速代理的值 |
| --- | --- | --- |
| broker.id | 该服务器的代理 ID。 | 1,2,3... |
| broker.rack | 代理的机架。这将用于机架感知复制分配，以确保具有容错能力。示例：`、`us-east-1dRACK1` | 可用区 ID 或子网 ID |
| default.replication.factor | 所有主题的默认复制因子。 | 3 |
| fetch.max.bytes | 为读取请求返回的最大字节数。 | Apache Kafka 默认值 |
| group.max.size | 单个使用者组可以容纳的最大使用者数量。 | Apache Kafka 默认值 |
| inter.broker.listener.name | 用于代理之间通信的侦听器的名称。 | REPLICATION\$1SECURE 或 REPLICATION |
| inter.broker.protocol.version | 指定使用哪个版本的代理间协议。 | Apache Kafka 默认值 |
| 侦听器 | 监听器列表-以逗号分隔的 URIs 我们将要监听的列表和监听器名称。您可以设置 advertised.listeners property，但不能设置 listeners 属性。 | MSK 生成 |
| log.message.format.version | 指定代理用于将消息追加到日志的消息格式版本。 | Apache Kafka 默认值 |
| min.insync.replicas | 当生成器将 acks 设置为 `all`（或 `-1`）时，`min.insync.replicas` 中的值会指定为使写入被视为成功而必须确认写入的最小副本数。如果无法达到这一最小值，生成器将引发异常（`NotEnoughReplicas` 或 `NotEnoughReplicasAfterAppend`）。 可使用来自生成器的 acks 值，强制执行更高的持久性保证。通过将 acks 设置为 “全部”。这可确保在大多数副本未收到写操作时，创建器将引发异常。 | 2 |
| num.io.threads | 服务器用于生成请求的线程数，其中可能包括磁盘 I/O。（m7g.large，8）、（m7g.xlarge，8）、（m7g.2xlarge，16）、（m7g.4xlarge，32）、（m7g.8xlarge，64）、（m7g.12xlarge，96）、（m7g.16xlarge，128） | 基于实例类型。=math.max (8, 2 \$1 v) CPUs |
| num.network.threads | 服务器用于接收网络请求并向网络发送响应的线程数量。（m7g.large，8）、（m7g.xlarge，8）、（m7g.2xlarge，8）、（m7g.4xlarge，16）、（m7g.8xlarge，32）、（m7g.12xlarge，48）、（m7g.16xlarge，64） | 基于实例类型。=math.max (8, v) CPUs |
| replica.fetch.response.max.bytes | 整个提取响应预期的最大字节数。记录是分批提取的，如果提取的第一个非空分区中的第一个记录批处理大于此值，则仍将返回该记录批处理以确保取得进展。这不是绝对最大值。message.max.bytes（代理配置）或 max.message.bytes（主题配置）属性指定代理接受的最大记录批处理大小。 | Apache Kafka 默认值 |
| request.timeout.ms | 此配置控制客户端等待请求响应的最长时间。如果在超时结束之前未收到响应，客户端将在必要时重新发送请求，如果重试次数用尽，请求则会失败。 | Apache Kafka 默认值 |
| transaction.state.log.min.isr | 已覆盖事务主题的 min.insync.replicas 配置。 | 2 |
| transaction.state.log.replication.factor | 事务主题的复制因子。 | Apache Kafka 默认值 |
| unclean.leader.election.enable | 允许将不在 ISR 集中的副本作为最后手段充当领导，即使这可能会导致数据丢失。 | FALSE |
# 代理配置操作
Apache Kafka 的代理配置是静态的，也可以是动态的。静态配置需重启代理才能应用配置。动态配置不需要重启代理即可更新配置。有关配置属性和更新模式的更多信息，请参阅 Apache Kafka 配置。
本主题说明如何创建自定义 MSK 配置以及如何对这些配置执行操作。有关如何使用 MSK 配置创建或更新集群的信息，请参阅[Amazon MSK 的关键功能和概念](operations.md)。
**Topics**
+ [
# 创建配置
](msk-configuration-operations-create.md)
+ [
# 更新配置
](msk-configuration-operations-update.md)
+ [
# 删除配置
](msk-configuration-operations-delete.md)
+ [
# 获取配置元数据
](msk-configuration-operations-describe.md)
+ [
# 获取有关配置修订的详细信息
](msk-configuration-operations-describe-revision.md)
+ [
# 列出您的账户中当前区域的配置
](msk-configuration-operations-list.md)
+ [
# Amazon MSK 配置状态
](msk-configuration-states.md)
# 创建配置
此过程介绍了如何创建自定义 Amazon MSK 配置以及如何对其执行操作。
1. 创建一个文件，可在其中指定要设置的配置属性以及要分配给这些属性的值。以下是示例配置文件的内容。
```
auto.create.topics.enable = true
log.roll.ms = 604800000
```
1. 运行以下 AWS CLI 命令，并*config-file-path*替换为上一步中保存配置的文件的路径。
**注意**
您为配置选择的名称必须符合以下正则表达式："^[0-9A-Za-z][0-9A-Za-z-]\$10,\$1\$1"。
```
aws kafka create-configuration --name "ExampleConfigurationName" --description "Example configuration description." --kafka-versions "1.1.1" --server-properties fileb://config-file-path
```
以下是运行此命令后的成功响应示例。
```
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-1234-abcd-1234-abcd123e8e8e-1",
"CreationTime": "2019-05-21T19:37:40.626Z",
"LatestRevision": {
"CreationTime": "2019-05-21T19:37:40.626Z",
"Description": "Example configuration description.",
"Revision": 1
},
"Name": "ExampleConfigurationName"
}
```
1. 上一条命令会返回新配置的 Amazon 资源名称（ARN）。保存此 ARN，因为您需要使用它来在其他命令中引用此配置。如果您丢失了配置 ARN，则可列出账户中的所有配置来重新找到它。
# 更新配置
此过程介绍了如何更新自定义 Amazon MSK 配置。
1. 创建一个文件，可在其中指定要更新的配置属性以及要分配给这些属性的值。以下是示例配置文件的内容。
```
auto.create.topics.enable = true
min.insync.replicas = 2
```
1. 运行以下 AWS CLI 命令，并*config-file-path*替换为上一步中保存配置的文件的路径。
*configuration-arn*替换为您在创建配置时获得的 ARN。如果您在创建配置时未保存 ARN，则可使用 `list-configurations` 命令列出账户中的所有配置。您想要在列表中显示的配置将显示在响应中。配置的 ARN 也将显示在该列表中。
```
aws kafka update-configuration --arn configuration-arn --description "Example configuration revision description." --server-properties fileb://config-file-path
```
1. 以下是运行此命令后的成功响应示例。
```
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-1234-abcd-1234-abcd123e8e8e-1",
"LatestRevision": {
"CreationTime": "2020-08-27T19:37:40.626Z",
"Description": "Example configuration revision description.",
"Revision": 2
}
}
```
# 删除配置
以下程序展示如何删除未附加到集群的配置。您无法删除附加到集群的配置。
1. 要运行此示例，请*configuration-arn*替换为在创建配置时获得的 ARN。如果您在创建配置时未保存 ARN，则可使用 `list-configurations` 命令列出账户中的所有配置。您想要在列表中显示的配置将显示在响应中。配置的 ARN 也将显示在该列表中。
```
aws kafka delete-configuration --arn configuration-arn
```
1. 以下是运行此命令后的成功响应示例。
```
{
"arn": " arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-1234-abcd-1234-abcd123e8e8e-1",
"state": "DELETING"
}
```
# 获取配置元数据
以下过程演示了如何描述 Amazon MSK 配置来获取有关配置的元数据。
1. 以下命令会返回有关配置的元数据。要获取配置的详细说明，请运行 `describe-configuration-revision`。
要运行此示例，请*configuration-arn*替换为在创建配置时获得的 ARN。如果您在创建配置时未保存 ARN，则可使用 `list-configurations` 命令列出账户中的所有配置。您想要在列表中显示的配置将显示在响应中。配置的 ARN 也将显示在该列表中。
```
aws kafka describe-configuration --arn configuration-arn
```
1. 以下是运行此命令后的成功响应示例。
```
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-abcd-1234-abcd-abcd123e8e8e-1",
"CreationTime": "2019-05-21T00:54:23.591Z",
"Description": "Example configuration description.",
"KafkaVersions": [
"1.1.1"
],
"LatestRevision": {
"CreationTime": "2019-05-21T00:54:23.591Z",
"Description": "Example configuration description.",
"Revision": 1
},
"Name": "SomeTest"
}
```
# 获取有关配置修订的详细信息
此过程将为您提供对 Amazon MSK 配置修订的详细描述。
如果您使用 `describe-configuration` 命令描述 MSK 配置，您将看到配置的元数据。要获得配置的描述，请使用 `describe-configuration-revision` 命令。
+ 运行以下命令并*configuration-arn*替换为在创建配置时获得的 ARN。如果您在创建配置时未保存 ARN，则可使用 `list-configurations` 命令列出账户中的所有配置。您想要在列表中显示的配置将显示在响应中。配置的 ARN 也将显示在该列表中。
```
aws kafka describe-configuration-revision --arn configuration-arn --revision 1
```
以下是运行此命令后的成功响应示例。
```
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-abcd-1234-abcd-abcd123e8e8e-1",
"CreationTime": "2019-05-21T00:54:23.591Z",
"Description": "Example configuration description.",
"Revision": 1,
"ServerProperties": "YXV0by5jcmVhdGUudG9waWNzLmVuYWJsZSA9IHRydWUKCgp6b29rZWVwZXIuY29ubmVjdGlvbi50aW1lb3V0Lm1zID0gMTAwMAoKCmxvZy5yb2xsLm1zID0gNjA0ODAwMDAw"
}
```
`ServerProperties` 的值已使用 base64 进行编码。如果您使用 base64 解码器（例如 https://www.base64decode.org/）手动对其进行解码，则将获得用于创建自定义配置的原始配置文件的内容。在此情况下，您将获得以下内容：
```
auto.create.topics.enable = true
log.roll.ms = 604800000
```
# 列出您的账户中当前区域的配置
此过程介绍如何列出您账户中当前 AWS 区域的所有 Amazon MSK 配置。
+ 运行如下命令。
```
aws kafka list-configurations
```
以下是运行此命令后的成功响应示例。
```
{
"Configurations": [
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-abcd-1234-abcd-abcd123e8e8e-1",
"CreationTime": "2019-05-21T00:54:23.591Z",
"Description": "Example configuration description.",
"KafkaVersions": [
"1.1.1"
],
"LatestRevision": {
"CreationTime": "2019-05-21T00:54:23.591Z",
"Description": "Example configuration description.",
"Revision": 1
},
"Name": "SomeTest"
},
{
"Arn": "arn:aws:kafka:us-east-1:123456789012:configuration/SomeTest/abcdabcd-1234-abcd-1234-abcd123e8e8e-1",
"CreationTime": "2019-05-03T23:08:29.446Z",
"Description": "Example configuration description.",
"KafkaVersions": [
"1.1.1"
],
"LatestRevision": {
"CreationTime": "2019-05-03T23:08:29.446Z",
"Description": "Example configuration description.",
"Revision": 1
},
"Name": "ExampleConfigurationName"
}
]
}
```
# Amazon MSK 配置状态
Amazon MSK 配置可以处于以下某种状态。要对配置执行操作，该配置必须处于 `ACTIVE` 或 `DELETE_FAILED` 状态：
+ `ACTIVE`
+ `DELETING`
+ `DELETE_FAILED`
# 集群的智能再平衡
Amazon MSK 为所有带有 Express 代理的新 MSK 预配置集群提供智能再平衡。此功能可自动管理分区分配和集群扩展操作，无需使用第三方工具。当您向上或向下扩展集群时，智能再平衡会自动重新平衡分区。它还会持续监控集群的运行状况，以防资源失衡或过载，并重新分配工作负载。
智能再平衡提供在 30 分钟内完成的快速扩展操作，并且在扩展期间不会影响集群的可用性。对于所有新的基于 MSK Express 的预配置集群，它默认处于启用状态，建议的最大分区限制为每个代理 20,000 个分区。此外，此功能无需支付额外费用，也不需要任何配置。
自 2025 年 11 月 20 日起，智能再平衡将在支持亚马逊 MSK Express 经纪商的所有 AWS 地区推出。
**Topics**
+ [
## 智能再平衡的工作原理
](#how-intelligent-rebalancing-works)
+ [
## 监控智能再平衡指标
](#intelligent-rebalancing-metrics)
+ [
## 使用智能再平衡的注意事项
](#intelligent-rebalancing-considerations)
+ [
# 只需一次操作即可向上和向下扩展 Amazon MSK 集群
](intelligent-rebalancing-scaling-clusters.md)
+ [
# Amazon MSK 集群的稳定状态再平衡
](intelligent-rebalancing-self-balancing-paritions.md)
## 智能再平衡的工作原理
默认情况下，所有带有 Express 代理的新 MSK 预配置集群的智能再平衡处于启用状态。它包括对以下情况的支持：
+ 向@@ **上和向下扩展**：只需单击一下，即可在基于 MSK Express 的集群中添加或删除代理。指定要添加或删除的代理后，智能再平衡会根据内部 AWS 最佳实践自动在新集群设置中重新分配分区。
+ **稳定状态重新平衡**：在稳定状态下，此功能会持续监控集群的运行状况，并在以下情况下自动重新平衡分区：
+ 资源利用率因代理而异。
+ 经纪商变得过度配置或利用不足。
+ 添加了新的经纪人或删除了现有的经纪人。
**注意**
如果启用了智能重新平衡，您将无法使用第三方工具（例如 Cruise Control）进行分区重新平衡。您必须先暂停智能重新平衡，才能使用这些第三方工具提供的分区重新分配 API。
您可以在 Amazon MSK 控制台中使用此功能。您也可以使用 AWS CLI、Amazon M AWS SK APIs 或 SDK 来使用此功能，以及。 AWS CloudFormation有关更多信息，请参阅[扩展 Amazon MSK 集群](intelligent-rebalancing-scaling-clusters.md)和[稳态再平衡](intelligent-rebalancing-self-balancing-paritions.md)。
## 监控智能再平衡指标
您可以使用以下 Amazon CloudWatch 指标监控正在进行的和历史的智能再平衡操作的状态：
+ `RebalanceInProgress`：此指标每分钟发布一次，重新平衡时值为 1，否则为 0。
+ `UnderProvisioned`：表示集群当前处于配置不足状态，无法执行任何分区重新平衡。您要么需要添加更多代理，要么扩大集群的实例类型。
有关监控 MSK 预配置集群的信息，请参阅[](monitoring.md)和。[](cloudwatch-metrics.md)
## 使用智能再平衡的注意事项
+ 对智能再平衡的支持仅适用于带有 Express 代理的新 MSK 预配置集群。
+ 对于自动分区重新分配，每个代理最多可支持 20,000 个分区。
+ 启用智能重新平衡后，您不能使用分区重新分配 APIs 或第三方重新平衡工具。要使用此类工具 APIs 或第三方工具，必须先暂停基于 MSK Express 的集群的智能再平衡。
# 只需一次操作即可向上和向下扩展 Amazon MSK 集群
借助智能再平衡，您只需一次操作即可编辑集群中的代理数量，从而向上或向下扩展集群。您可以在 Amazon MSK 控制台中执行此操作，也可以使用 Amazon MSK APIs 或 AWS SDK 和。 AWS CLI AWS CloudFormation当您更改经纪人数量时，Amazon MSK 会执行以下操作：
+ 自动将分区分配给新的代理。
+ 从正在删除的代理中移出分区。
在向上和向下扩展集群时，客户端生成和使用数据的集群可用性不会受到影响。
**Topics**
------
#### [ Scaling clusters using AWS 管理控制台 ]
1. 在[https://console.aws.amazon.com/msk/家打开亚马逊 MSK 控制台？ region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在**集群**页面上，选择新创建的基于 Express 的集群。有关创建预配置的基于 Express 的集群的信息，请参阅。[步骤 1：创建预置 MSK 集群](create-cluster.md)
1. 在**操作**下拉列表中，选择**编辑经纪商数量**。
1. 在 **“编辑每个区域的代理数量**” 页面上，执行以下任一操作：
+ 要在集群中添加更多**代理，请选择向每个可用区添加**代理，然后输入要添加的代理数量。
+ 要从集群中移除代理，请选择**从每个可用区移除一个代理**。
1. 选择**保存更改**。
------
#### [ Scaling clusters using AWS CLI ]
您可以通过编辑集群的代理数量来向上或向下扩展集群。要在中执行此操作 AWS CLI，请使用[update-broker-count](https://docs.aws.amazon.com/cli/latest/reference/kafka/update-broker-count.html)命令，如以下示例所示。在此命令中，在`target-broker-count`参数中指定集群中想要的代理数量。
```
aws msk update-broker-count --cluster-arn arn:aws:kafka:us-east-1:123456789012:cluster/myCluster/abcd1234-5678-90ef-ghij-klmnopqrstuv-1 --current-version ABCDEF1GHIJK0L --target-broker-count 6
```
------
#### [ Scaling clusters using AWS SDK ]
您可以通过编程方式编辑代理数量来向上或向下扩展集群。要使用 AWS SDK 执行此操作，请使用 [UpdateBrokerCount](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-nodes-count.html#UpdateBrokerCount)API，如以下示例所示。对于`TargetNumberOfBrokerNodes`参数，请指定集群中想要的代理数量。
```
update_broker_count_response = client.update_broker_count(
ClusterArn='arn:aws:kafka:us-east-1:123456789012:cluster/myCluster/abcd1234-5678-90ef-ghij-klmnopqrstuv-1',
CurrentVersion='ABCDEF1GHIJK0L',
TargetNumberOfBrokerNodes=6
)
```
------
# Amazon MSK 集群的稳定状态再平衡
稳定状态再平衡是智能再平衡功能的一部分，对于所有带有 Express 代理的新 MSK Provisioned 集群，该功能默认处于启用状态。当您向上或向下扩展集群时，Amazon MSK 会自动处理分区管理，方法是将分区分配给新的代理，并从代理中移出待删除的分区。为确保跨经纪商的最佳工作负载分配，智能再平衡使用 Amazon MSK 最佳实践来确定自动启动经纪人再平衡的阈值。
需要时，您可以暂停和恢复稳定状态的再平衡。稳定状态再平衡会持续监控您的集群，并执行以下操作：
+ 跟踪代理资源使用情况（CPU、网络、存储）。
+ 在不影响数据可用性的情况下自动调整分区位置。
+ 与标准经纪商相比，Express经纪商完成再平衡操作的速度最多可快180倍。
+ 保持集群性能。
**Topics**
------
#### [ Pause and resume steady state rebalancing in AWS 管理控制台 ]
1. 在[https://console.aws.amazon.com/msk/家打开亚马逊 MSK 控制台？ region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在**集群**页面上，选择基于 Express 的集群。有关创建预配置的基于 Express 的集群的信息，请参阅。[步骤 1：创建预置 MSK 集群](create-cluster.md)
1. 在集群详细信息页面上，验证**智能重新平衡**状态是否为 “**活动**”。如果智能重新平衡不可用或状态为已**暂停**，请创建一个新的基于 Express 的集群。
1. 在 “**操作**” 下拉列表中，选择 “**编辑智能再平衡**”。
1. 在 **“编辑智能再平衡**” 页面上，执行以下操作：
1. 选择 “**已暂停**”。
1. 选择**保存更改**。
------
#### [ Pause and resume steady state rebalancing using AWS CLI ]
要使用将集群的重新平衡状态设置为 AWS CLI，请**ACTIVE**使用 [update-re](https://docs.aws.amazon.com/cli/latest/reference/kafka/update-rebalancing.html) balancing 命令，如下例所示。在此命令中，使用`rebalancing`参数指定状态。
```
aws msk update-rebalancing --cluster-arn arn:aws:kafka:us-east-1:123456789012:cluster/myCluster/abcd1234-5678-90ef-ghij-klmnopqrstuv-1 --current-version ABCDEF1GHIJK0L --rebalancing "{\"Rebalancing\":{\"Status\":\"ACTIVE\"}}"
```
------
#### [ Pause and resume steady state rebalancing using AWS SDK ]
您还可以使用 [UpdateRebalancingRequest](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-rebalancing.html#UpdateRebalancing)API 设置集群的重新平衡状态，以编程方式修改代理计数。以下示例说明如何将重新平衡状态设置为**ACTIVE**和。**PAUSED**
```
final UpdateRebalancingRequest updateRebalancingRequest = new UpdateRebalancingRequest()
.withClusterArn(arn:aws:kafka:us-east-1:123456789012:cluster/myCluster/abcd1234-5678-90ef-ghij-klmnopqrstuv-1)
.withCurrentVersion(ABCDEF1GHIJK0L)
.withRebalancing(new Rebalancing().withStatus("ACTIVE"));
```
```
final UpdateRebalancingRequest updateRebalancingRequest = new UpdateRebalancingRequest()
.withClusterArn(arn:aws:kafka:us-east-1:123456789012:cluster/myCluster/abcd1234-5678-90ef-ghij-klmnopqrstuv-1)
.withCurrentVersion(ABCDEF1GHIJK0L)
.withRebalancing(new Rebalancing().withStatus("PAUSED"));
```
------
# 在预置 MSK 集群上进行修补
Amazon MSK 会定期更新集群中代理上的软件。维护包括计划内更新或计划外修复。计划内维护包括操作系统更新、安全更新以及维护集群运行状况、安全和性能所需的其他软件更新。进行计划外维护是为了解决基础设施性能突然退化的问题。我们对标准代理和快速代理进行维护，但体验有所不同。
## 标准代理修补
如果您遵循[最佳实践](bestpractices.md)，标准代理更新不会对您的应用程序的写入和读取产生影响。
Amazon MSK 使用软件的滚动更新来维持集群的高可用性。在此过程中，代理将逐个重启，并且 Kafka 会自动将领导权转移给另一个在线代理。在 AWS 管理控制台 或通过`DescribeClusterOperation`和查看集群操作时 `ListClusterOperations` APIs，这些维护操作的操作类型为`SECURITY_PATCHING`。Kafka 客户端具有内置机制，可自动检测分区领导权的变化，并继续将数据写入和读取到 MSK 集群中。在任何时候（包括在修补期间）都要遵照[Apache Kafka 客户端的最佳实践](bestpractices-kafka-client.md)，以使集群平稳运行。
当代理离线后，客户端上出现暂时断开连接错误是正常的。您还会观察到在短暂时段内（最多 2 分钟，通常更少）p99 读写延迟出现一些峰值（通常为几毫秒，最多约 2 秒）。这些峰值是预料之中的，是由于客户端重新连接到新的领导代理引起的；它不会影响您的生产或消费，并且会在重新连接后解决。有关更多信息，请参阅[代理离线和客户端失效转移](https://docs.aws.amazon.com/msk/latest/developerguide/troubleshooting-offlinebroker-clientfailover.html)。
您还将观察到指标 `UnderReplicatedPartitions` 增加，这是预期的，因为已关闭的代理上的分区不再复制数据。这对应用程序的写入和读取没有影响，因为托管在其他代理上的这些分区的副本现在正在处理请求。
软件更新后，当代理恢复在线时，它需要“赶上”离线期间生成的消息。在追赶过程中，您可能还会观察到卷吞吐量和 CPU 使用率增加。如果您的代理上有足够的 CPU、内存、网络和卷资源，这些应该不会对集群的写入和读取产生影响。
## 快速代理修补
快速代理没有维护窗口。Amazon MSK 会以分时的方式持续自动更新集群，这意味着在一个月内可能偶尔会有单个代理重启。这样可以确保无需针对一次性集群范围的维护窗口制定任何计划或做出任何调整。与往常一样，在代理重启期间流量仍将保持不中断，因为领导者将切换到继续处理请求的其他代理。在 AWS 管理控制台 或通过`DescribeClusterOperation`和查看集群操作时 `ListClusterOperations` APIs，这些维护操作的操作类型为`BROKER_UPDATE`。
快速代理配置了最佳实践设置和安全护栏，这使集群能够灵活适应维护期间可能发生的负载变化。Amazon MSK 为快速代理设置了吞吐量配额，以减轻集群过载的影响，过载可能会导致在代理重启期间出现问题。借助这些改进，在使用快速代理时就无需提前通知、计划和维护窗口。
快速代理始终以三种方式复制数据，确保客户端在重启期间自动进行失效转移。您无需担心因为复制因子设置为 1 或 2 导致主题不可用的问题。此外，快速代理重启后的同步速度也比标准代理更快。快速代理的修补速度更快，这意味着您可能为集群安排的任何控制面板活动，其计划性中断会降至最短。
与所有 Apache Kafka 应用程序一样，连接到快速代理的客户端仍存在共用的客户端-服务器合约。配置客户端以处理代理之间的领导者失效转移仍然至关重要。在任何时候（包括在修补期间）都要遵照[Apache Kafka 客户端的最佳实践](bestpractices-kafka-client.md)，以使集群平稳运行。当代理重新启动后，客户端上出现暂时[断开连接错误](troubleshooting-offlinebroker-clientfailover.md)是正常的。这不会影响生成和使用，因为跟随者代理将接管分区领导权。Apache Kafka 客户端将自动进行失效转移，并开始向新的领导者代理发送请求。
# 代理离线和客户端失效转移
Kafka 允许使用离线代理；在正常且平衡的集群中，遵循最佳实践的单个离线代理不会产生影响或导致生产或消费失败。这是因为另一个代理将接管分区领导权，也因为 Kafka 客户端库将自动进行失效转移并开始向新的领导者代理发送请求。
**客户端服务器合约**
这会导致客户端库和服务器端行为之间形成共享合约；服务器必须成功分配一个或多个新的领导者，而客户端必须更改代理以及时向新的领导者发送请求。
Kafka 使用异常来控制此流：
**过程示例**
1. 代理 A 进入离线状态。
1. Kafka 客户端收到异常（通常是网络断开连接或者 not\$1leader\$1for\$1partition）。
1. 这些异常会触发 Kafka 客户端更新其元数据，以便它知道最新的领导者。
1. Kafka 客户端恢复向其他代理上新的分区领导者发送请求。
使用公开发布的 Java 客户端和默认配置，此过程通常需要不到 2 秒。客户端错误冗长且重复，但无需担心，如“WARN”级别所示。
**示例：异常 1**
`10:05:25.306 [kafka-producer-network-thread | producer-1] WARN o.a.k.c.producer.internals.Sender - [Producer clientId=producer-1] Got error produce response with correlation id 864845 on topic-partition msk-test-topic-1-0, retrying (2147483646 attempts left). Error: NETWORK_EXCEPTION. Error Message: Disconnected from node 2`
**示例：异常 2**
`10:05:25.306 [kafka-producer-network-thread | producer-1] WARN o.a.k.c.producer.internals.Sender - [Producer clientId=producer-1] Received invalid metadata error in produce request on partition msk-test-topic-1-41 due to org.apache.kafka.common.errors.NotLeaderOrFollowerException: For requests intended only for the leader, this error indicates that the broker is not the current leader. For requests intended for any replica, this error indicates that the broker is not a replica of the topic partition.. Going to request metadata update now"`
Kafka 客户端通常会在 1 秒内（最多 3 秒）自动解决这些错误。在客户端指标中，这表示为 p99 的 produce/consume 延迟（通常在 100 中为高毫秒）。超过此时间通常表明客户端配置或服务器端控制器负载存在问题。请参阅故障排除部分。
可以通过检查其他代理上的 `BytesInPerSec` 和 `LeaderCount` 指标是否增加来验证失效转移是否成功，这证明流量和领导权按预期移动。您还将观察到 `UnderReplicatedPartitions` 指标增加，这在关闭代理而副本处于离线状态时是预期的。
**问题排查**
破坏客户端-服务器合约可能会扰乱上述流程。最常见的问题原因包括：
+ Kafka 客户端库配置错误或使用不正确。
+ 第三方客户端库的意外默认行为和错误。
+ 控制器过载导致分区领导者分配速度变慢。
+ 正在选举新的控制器，从而导致分区领导者分配速度变慢。
为了确保处理领导权失效转移的行为正确，我们建议：
+ 必须遵循服务器端[最佳实践](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html)，以确保控制器代理得到适当扩展，从而避免领导权分配缓慢。
+ 客户端库必须启用重试以确保客户端处理失效转移。
+ 客户端库必须配置 retry.backoff.ms（默认为 100），以避免风暴。 connection/request
+ 客户端库必须将 request.timeout.ms 和 delivery.timeout.ms 设置为符合应用程序 SLA 的值。对于某些故障类型，较高的值将导致失效转移速度变慢。
+ 客户端库必须确保 bootstrap.servers 至少包含 3 个随机代理，以避免对初始发现的可用性产生影响。
+ 一些客户端库比其他库的级别较低，并期望应用程序开发人员自己实现重试逻辑和异常处理。有关示例用法，请参阅客户端库的特定文档，并确保遵循正确的 reconnect/retry 逻辑。
+ 我们建议监控客户端产生的延迟、成功请求数和不可重试错误的错误数。
+ 我们观察到，尽管生产和消费请求不受影响，但较旧的第三方 golang 和 ruby 库在整个代理离线期间仍然很冗长。除了成功和错误的请求指标外，我们建议您始终监控业务级别指标，以确定日志中是否存在真正的影响和噪音。
+ 客户不应对 network/not\$1leader 的瞬态异常发出警报，因为它们是正常的、不产生影响的，并且是 kafka 协议的一部分。
+ 客户不应发出警报， UnderReplicatedPartitions 因为在单个离线经纪商期间，他们是正常的、无影响的，并且是预料之中的。
# Amazon MSK 中的安全性
云安全 AWS 是重中之重。作为 AWS 客户，您可以受益于专为满足大多数安全敏感型组织的要求而构建的数据中心和网络架构。
安全是双方 AWS 的共同责任。[责任共担模式](https://aws.amazon.com/compliance/shared-responsibility-model/)将其描述为云*的*安全性和云*中*的安全性：
+ **云安全** — AWS 负责保护在 AWS 云中运行 AWS 服务的基础架构。 AWS 还为您提供可以安全使用的服务。作为[AWS 合规计划合规计划合规计划合](https://aws.amazon.com/compliance/programs/)的一部分，第三方审计师定期测试和验证我们安全的有效性。要了解适用于 Amazon Managed Streaming for Apache Kafka 的合规性计划，请参阅[按合规性计划提供的范围内 Amazon Web Services](https://aws.amazon.com/compliance/services-in-scope/)。
+ **云端安全**-您的责任由您使用的 AWS 服务决定。您还需要对其它因素负责，包括您的数据的敏感性、您公司的要求以及适用的法律法规。
该文档可帮助您了解如何在使用 Amazon MSK 时应用责任共担模式。以下主题说明如何配置 Amazon MSK 以实现您的安全性与合规性目标。您还会了解如何使用其他 Amazon Web Services 帮助您监控和保护 Amazon MSK 资源。
**Topics**
+ [
# Amazon Managed Streaming for Apache Kafka 中的数据保护
](data-protection.md)
+ [
# 亚马逊 MSK 的身份验证和授权 APIs
](security-iam.md)
+ [
# Apache Kafka 的身份验证和授权 APIs
](kafka_apis_iam.md)
+ [
# 更改 Amazon MSK 集群的安全组
](change-security-group.md)
+ [
# 控制对亚马逊 MSK ZooKeeper 集群中 Apache 节点的访问权限
](zookeeper-security.md)
+ [
# Amazon Managed Streaming for Apache Kafka 的合规性验证
](MSK-compliance.md)
+ [
# Amazon Managed Streaming for Apache Kafka 中的恢复能力
](disaster-recovery-resiliency.md)
+ [
# Amazon Managed Streaming for Apache Kafka 中的基础设施安全性
](infrastructure-security.md)
# Amazon Managed Streaming for Apache Kafka 中的数据保护
分担责任模式 AWS [分担责任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)适用于适用于 Apache Kafka 的 Apache Streaming for Apache Streaming 中的数据保护。如本模型所述 AWS ，负责保护运行所有内容的全球基础架构 AWS 云。您负责维护对托管在此基础结构上的内容的控制。您还负责您所使用的 AWS 服务 的安全配置和管理任务。有关数据隐私的更多信息，请参阅[数据隐私常见问题](https://aws.amazon.com/compliance/data-privacy-faq/)。有关欧洲数据保护的信息，请参阅 *AWS Security Blog* 上的 [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) 博客文章。
出于数据保护目的，我们建议您保护 AWS 账户 凭证并使用 AWS IAM Identity Center 或 AWS Identity and Access Management (IAM) 设置个人用户。这样，每个用户只获得履行其工作职责所需的权限。还建议您通过以下方式保护数据：
+ 对每个账户使用多重身份验证（MFA）。
+ 用于 SSL/TLS 与 AWS 资源通信。我们要求使用 TLS 1.2，建议使用 TLS 1.3。
+ 使用设置 API 和用户活动日志 AWS CloudTrail。有关使用 CloudTrail 跟踪捕获 AWS 活动的信息，请参阅《*AWS CloudTrail 用户指南》*中的[使用跟 CloudTrail 踪](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html)。
+ 使用 AWS 加密解决方案以及其中的所有默认安全控件 AWS 服务。
+ 使用高级托管安全服务（例如 Amazon Macie），它有助于发现和保护存储在 Amazon S3 中的敏感数据。
+ 如果您在 AWS 通过命令行界面或 API 进行访问时需要经过 FIPS 140-3 验证的加密模块，请使用 FIPS 端点。有关可用的 FIPS 端点的更多信息，请参阅《美国联邦信息处理标准（FIPS）第 140-3 版》[https://aws.amazon.com/compliance/fips/](https://aws.amazon.com/compliance/fips/)。
强烈建议您切勿将机密信息或敏感信息（如您客户的电子邮件地址）放入标签或自由格式文本字段（如**名称**字段）。这包括您 AWS 服务 使用控制台、API 或与 Amazon MSK 或其他机构 AWS CLI合作时。 AWS SDKs在用于名称的标签或自由格式文本字段中输入的任何数据都可能会用于计费或诊断日志。如果您向外部服务器提供 URL，强烈建议您不要在网址中包含凭证信息来验证对该服务器的请求。
**Topics**
+ [
# Amazon MSK 加密
](msk-encryption.md)
+ [
# Amazon MSK 加密入门
](msk-working-with-encryption.md)
+ [
# 将 Amazon MSK APIs 与接口 VPC 终端节点配合使用
](privatelink-vpc-endpoints.md)
# Amazon MSK 加密
Amazon MSK 提供了数据加密选项，可使用这些选项来满足严格的数据管理要求。Amazon MSK 用于加密的证书必须每 13 个月续订一次。Amazon MSK 会自动为所有集群续订这些证书。Amazon MSK 开始进行证书更新操作时，快速代理集群仍处于 `ACTIVE` 状态。对于标准代理集群，Amazon MSK 会集群在启动证书更新操作时将集群状态设置为 `MAINTENANCE`。待更新完成后，MSK 会将集群状态重新设置为 `ACTIVE`。当集群处于证书更新操作时，您可以继续生成和使用数据，但无法对数据执行任何更新操作。
## Amazon MSK 静态加密
Amazon MSK 与 [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)（KMS）集成以提供透明的服务器端加密。Amazon MSK 始终加密您的静态数据。当创建 MSK 集群时，您可以指定您希望 Amazon MSK 用于加密静态数据的 AWS KMS key 。如果您不指定 KMS 密钥，Amazon MSK 会为您创建一个 [AWS 托管式密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) 并代表您使用它。有关 KMS 密钥的更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的 [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys)。
## Amazon MSK 传输中加密
Amazon MSK 会使用 TLS 1.2。默认情况下，它会加密在 MSK 集群的代理之间传输的数据。可以在创建集群时覆盖此默认值。
对于客户端和代理之间的通信，您必须指定下列三项设置之一：
+ 仅允许 TLS 加密数据。这是默认设置。
+ 同时允许明文数据和 TLS 加密数据。
+ 仅允许明文数据。
亚马逊 MSK 经纪人使用公共 AWS Certificate Manager 证书。因此，任何信任 Amazon Trust Services 的信任库也会信任 Amazon MSK 代理的证书。
虽然我们强烈建议启用传输中加密，但它可能会增加额外的 CPU 开销和几毫秒的延迟。但是，大多数使用案例对这些差异并不敏感，影响的程度取决于集群、客户端和使用情况配置文件的配置。
# Amazon MSK 加密入门
创建 MSK 集群时，您可以使用 JSON 格式指定加密设置。示例如下：
```
{
"EncryptionAtRest": {
"DataVolumeKMSKeyId": "arn:aws:kms:us-east-1:123456789012:key/abcdabcd-1234-abcd-1234-abcd123e8e8e"
},
"EncryptionInTransit": {
"InCluster": true,
"ClientBroker": "TLS"
}
}
```
对于 `DataVolumeKMSKeyId`，您可以为账户 (`alias/aws/kafka`) 中的 MSK 指定[客户托管密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)或 AWS 托管式密钥 。如果您未指定`EncryptionAtRest`，Amazon MSK 仍会加密您的静态数据。 AWS 托管式密钥要确定您的集群使用的密钥，请发送 `GET` 请求或调用 `DescribeCluster` API 操作。
对于 `EncryptionInTransit`，`InCluster` 的默认值为 true，但是如果您不想在代理之间传递数据时让 Amazon MSK 加密数据，则可以将此项设置为 false。
要为客户端和代理之间传输的数据指定加密模式，请将 `ClientBroker` 设置为以下三个值之一：`TLS`、`TLS_PLAINTEXT` 或 `PLAINTEXT`。
**Topics**
+ [
# 创建 Amazon MSK 集群时指定加密设置
](msk-working-with-encryption-cluster-create.md)
+ [
# 测试 Amazon MSK TLS 加密
](msk-working-with-encryption-test-tls.md)
# 创建 Amazon MSK 集群时指定加密设置
此过程介绍了如何在创建 Amazon MSK 集群时指定加密设置。
**创建集群时指定加密设置**
1. 将上一示例的内容保存在文件中，并为该文件指定所需的任何名称。例如，将其命名为 `encryption-settings.json`。
1. 运行 `create-cluster` 命令并使用 `encryption-info` 选项指向您保存配置 JSON 的文件。示例如下：替换为*\$1YOUR MSK VERSION\$1*与 Apache Kafka 客户端版本相匹配的版本。有关如何查找 MSK 集群版本的信息，请参阅[确定 MSK 集群版本](create-topic.md#find-msk-cluster-version)。请注意，使用与 MSK 集群版本不同的 Apache Kafka 客户端版本，可能会导致 Apache Kafka 数据损坏、丢失和停机。
```
aws kafka create-cluster --cluster-name "ExampleClusterName" --broker-node-group-info file://brokernodegroupinfo.json --encryption-info file://encryptioninfo.json --kafka-version "{YOUR MSK VERSION}" --number-of-broker-nodes 3
```
以下是运行此命令后的成功响应示例。
```
{
"ClusterArn": "arn:aws:kafka:us-east-1:123456789012:cluster/SecondTLSTest/abcdabcd-1234-abcd-1234-abcd123e8e8e",
"ClusterName": "ExampleClusterName",
"State": "CREATING"
}
```
# 测试 Amazon MSK TLS 加密
此过程介绍了如何在 Amazon MSK 上测试 TLS 加密。
**测试 TLS 加密**
1. 按照[步骤 3：创建客户端计算机](create-client-machine.md)中的指导创建客户端计算机。
1. 在客户端计算机上安装 Apache Kafka。
1. 在本示例中，我们使用 JVM 信任库与 MSK 集群通信。为此，请首先在客户端计算机上创建一个名为 `/tmp` 的文件夹。然后，转到 Apache Kafka 安装的 `bin` 文件夹，并运行以下命令。（您的 JVM 路径可能不相同。）
```
cp /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.201.b09-0.amzn2.x86_64/jre/lib/security/cacerts /tmp/kafka.client.truststore.jks
```
1. 仍在客户端计算机上的 Apache Kafka 安装的 `bin` 文件夹中，创建一个名为 `client.properties` 的文本文件，该文件包含以下内容。
```
security.protocol=SSL
ssl.truststore.location=/tmp/kafka.client.truststore.jks
```
1. 在 AWS CLI 安装了的计算机上运行以下命令，*clusterARN*替换为集群的 ARN。
```
aws kafka get-bootstrap-brokers --cluster-arn clusterARN
```
成功结果如下所示。保存此结果，因为您需要在下一步中使用它。
```
{
"BootstrapBrokerStringTls": "a-1.example.g7oein.c2.kafka.us-east-1.amazonaws.com:0123,a-3.example.g7oein.c2.kafka.us-east-1.amazonaws.com:0123,a-2.example.g7oein.c2.kafka.us-east-1.amazonaws.com:0123"
}
```
1. 运行以下命令，*BootstrapBrokerStringTls*替换为您在上一步中获得的代理端点之一。
```
/bin/kafka-console-producer.sh --broker-list BootstrapBrokerStringTls --producer.config client.properties --topic TLSTestTopic
```
1. 打开新的命令窗口并连接到同一台客户端计算机。然后，运行以下命令以创建控制台使用器。
```
/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringTls --consumer.config client.properties --topic TLSTestTopic
```
1. 在生成器窗口中，输入文本消息后点击回车键，并在使用器窗口中查找相同消息。Amazon MSK 对传输中的此消息进行了加密。
有关配置 Apache Kafka 客户端以使用加密数据的更多信息，请参阅[配置 Kafka 客户端](https://kafka.apache.org/documentation/#security_configclients)。
# 将 Amazon MSK APIs 与接口 VPC 终端节点配合使用
您可以使用由 AWS PrivateLink提供支持的接口 VPC 终端节点来防止您的 Amazon VPC 和 Amazon MSK 之间的流量 APIs 离开亚马逊网络。接口 VPC 终端节点不需要互联网网关、NAT 设备、VPN 连接或 AWS Direct Connect 连接。 [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html)是一种使用弹性网络接口实现 AWS 服务之间私有通信的 AWS 技术，在 Amazon VPC IPs 中使用私有网络。有关更多信息，请参阅[亚马逊 Virtual Private Cloud](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) 和[接口 VPC 终端节点 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint)。
您的应用程序可以使用与 Amazon MSK Provisioned 和 MSK Connect 连接 APIs 。 AWS PrivateLink首先，为 Amazon MSK API 创建一个接口 VPC 端点，以便来自和前往 Amazon VPC 资源的流量开始流经接口 VPC 端点。启用 FIPS 的接口 VPC 端点适用于美国区域。有关更多信息，请参阅[创建接口端点](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint)。
使用此功能，Apache Kafka 客户端可动态获取连接字符串以连接预置 MSK 或 MSK Connect 资源，而无需遍历互联网来检索连接字符串。
创建接口 VPC 端点时，请选择以下服务名称端点之一：
**对于预置 MSK：**
+ 新连接不再支持以下服务名称终端节点：
+ com.amazonaws.region.kafka
+ com.amazonaws.region.kafka-fips（启用 FIPS）
+ 支持两者的双栈端点服务 IPv4 以及 IPv6 流量：
+ wws.api.region.kafka-api
+ aws.api.region。 kafka-api-fips （支持 FIPS）
要设置双堆栈终端节点，必须遵循[双栈和 FIP](https://docs.aws.amazon.com/sdkref/latest/guide/feature-endpoints.html) S 端点指南。
其中区域指您的区域名称。选择此服务名称可与 MSK 预配置 APIs兼容。有关更多信息，请参阅 *https://docs.aws.amazon.com/msk/1.0/* apireference/ 中的[操作](https://docs.aws.amazon.com/msk/1.0/apireference/operations.html)。
**对于 MSK Connect：**
+ com.amazonaws.region.kafkaconnect
其中区域指您的区域名称。选择此服务名称即可与 MSK Connec APIs t 兼容。有关更多信息，请参阅《Amazon MSK Connect API 参考》**中的[操作](https://docs.aws.amazon.com/MSKC/latest/mskc/API_Operations.html)。
有关更多信息，包括创建接口 VPC 终端节点的 step-by-step说明，请参阅*AWS PrivateLink 指南*中的[创建接口终端节点](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint)。
## 控制对亚马逊 MSK 预配置或 MSK Connect 的 VPC 终端节点的访问权限 APIs
借助 VPC 端点策略，您可以控制访问，方式是：将策略附加到 VPC 端点或使用附加到 IAM 用户、组或角色的策略中的额外字段，从而限制只能通过特定 VPC 端点进行访问。使用相应的示例策略，定义对预置 MSK 或 MSK Connect 服务的访问权限。
如果您在创建端点时未附加策略，Amazon VPC 会为您附加一个默认策略，该策略允许对服务的完全访问。终端节点策略不会覆盖或替换 IAM 基于身份的策略或服务特定的策略。这是一个单独的策略，用于控制从端点中对指定服务进行的访问。
有关更多信息，请参阅《AWS PrivateLink 指南》**中的[使用 VPC 端点控制对服务的访问](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)。
------
#### [ MSK Provisioned — VPC policy example ]
**只读访问权限**
此示例策略可以附加到某个 VPC 端点。（有关更多信息，请参阅控制对 Amazon VPC 资源的访问）。它限制仅能通过其附加的 VPC 端点列出或描述操作。
```
{
"Statement": [
{
"Sid": "MSKReadOnly",
"Principal": "*",
"Action": [
"kafka:List*",
"kafka:Describe*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
**预置 MSK — VPC 端点策略示例**
限制对特定 MSK 集群的访问
此示例策略可以附加到某个 VPC 端点。它限制通过其附加的 VPC 端点访问特定的 Kafka 集群。
```
{
"Statement": [
{
"Sid": "AccessToSpecificCluster",
"Principal": "*",
"Action": "kafka:*",
"Effect": "Allow",
"Resource": "arn:aws:kafka:us-east-1:123456789012:cluster/MyCluster"
}
]
}
```
------
#### [ MSK Connect — VPC endpoint policy example ]
**列出连接器并创建新的连接器**
下面是用于 MSK Connect 的端点策略示例。此策略允许指定角色列出连接器，并创建新的连接器。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "MSKConnectPermissions",
"Effect": "Allow",
"Action": [
"kafkaconnect:ListConnectors",
"kafkaconnect:CreateConnector"
],
"Resource": "*",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/MyMSKConnectExecutionRole"
]
}
}
]
}
```
**MSK Connect — VPC 端点策略示例**
仅允许指定 VPC 中特定 IP 地址的请求
以下示例显示的策略仅允许来自指定 VPC 中指定 IP 地址的请求成功。来自其它 IP 地址的请求将失败。
```
{
"Statement": [
{
"Action": "kafkaconnect:*",
"Effect": "Allow",
"Principal": "*",
"Resource": "*",
"Condition": {
"IpAddress": {
"aws:VpcSourceIp": "192.0.2.123"
},
"StringEquals": {
"aws:SourceVpc": "vpc-555555555555"
}
}
}
]
}
```
------
# 亚马逊 MSK 的身份验证和授权 APIs
AWS Identity and Access Management (IAM) AWS 服务 可帮助管理员安全地控制对 AWS 资源的访问权限。IAM 管理员控制谁可以*通过身份验证*（登录）和*获得授权*（具有权限）来使用 Amazon MSK 资源。您可以使用 IAM AWS 服务 ，无需支付额外费用。
**Topics**
+ [
# Amazon MSK 如何与 IAM 配合使用
](security_iam_service-with-iam.md)
+ [
# Amazon MSK 基于身份的策略示例
](security_iam_id-based-policy-examples.md)
+ [
# Amazon MSK 的服务相关角色
](using-service-linked-roles.md)
+ [
# AWS 亚马逊 MSK 的托管策略
](security-iam-awsmanpol.md)
+ [
# 排查 Amazon MSK 身份和访问问题
](security_iam_troubleshoot.md)
# Amazon MSK 如何与 IAM 配合使用
在使用 IAM 管理对 Amazon MSK 的访问权限之前，您应该了解哪些 IAM 功能可用于 Amazon MSK。要全面了解 Amazon MSK 和其他 AWS 服务如何与 IAM 配合使用，请参阅 IAM *用户指南*中的[与 IAM 配合使用的AWS 服务](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。
**Topics**
+ [
# Amazon MSK 基于身份的策略
](security_iam_service-with-iam-id-based-policies.md)
+ [
# Amazon MSK 基于资源的策略
](security_iam_service-with-iam-resource-based-policies.md)
+ [
# 基于 Amazon MSK 标签的授权
](security_iam_service-with-iam-tags.md)
+ [
# Amazon MSK IAM 角色
](security_iam_service-with-iam-roles.md)
# Amazon MSK 基于身份的策略
通过使用 IAM 基于身份的策略，您可以指定允许或拒绝的操作和资源以及允许或拒绝操作的条件。Amazon MSK 支持特定的操作、资源和条件键。要了解在 JSON 策略中使用的所有元素，请参阅《IAM 用户指南》** 中的 [IAM JSON 策略元素参考](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html)。
## Amazon MSK 基于身份的策略的操作
管理员可以使用 AWS JSON 策略来指定谁有权访问什么。也就是说，哪个**主体**可以对什么**资源**执行**操作**，以及在什么**条件**下执行。
JSON 策略的 `Action` 元素描述可用于在策略中允许或拒绝访问的操作。在策略中包含操作以授予执行关联操作的权限。
Amazon MSK 中的策略操作在操作前使用以下前缀：`kafka:`。例如，要授予某人使用 Amazon MSK `DescribeCluster` API 操作描述 MSK 集群的权限，您应将 `kafka:DescribeCluster` 操作纳入其策略。策略语句必须包含 `Action` 或 `NotAction` 元素。Amazon MSK 定义了自己的一组操作，以描述您可以使用该服务执行的任务。
请注意，MSK 主题的策略操作在操作前 APIs 使用`kafka-cluster`前缀，请参阅。[IAM 授权策略、操作和资源的语义](kafka-actions.md)
要在单个语句中指定多项操作，请使用逗号将它们隔开，如下所示：
```
"Action": ["kafka:action1", "kafka:action2"]
```
您也可以使用通配符 （\$1) 指定多个操作。例如，要指定以单词 `Describe` 开头的所有操作，包括以下操作：
```
"Action": "kafka:Describe*"
```
要查看 Amazon MSK 操作的列表，请参阅《IAM 用户指南》**中的 [Amazon Managed Streaming for Apache Kafka 的操作、资源和条件键](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmanagedstreamingforapachekafka.html)。
## Amazon MSK 基于身份的策略的资源
管理员可以使用 AWS JSON 策略来指定谁有权访问什么。也就是说，哪个**主体**可以对什么**资源**执行**操作**，以及在什么**条件**下执行。
`Resource` JSON 策略元素指定要向其应用操作的一个或多个对象。作为最佳实践，请使用其 [Amazon 资源名称（ARN）](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)指定资源。对于不支持资源级权限的操作，请使用通配符 (\$1) 指示语句应用于所有资源。
```
"Resource": "*"
```
Amazon MSK 实例资源具有以下 ARN：
```
arn:${Partition}:kafka:${Region}:${Account}:cluster/${ClusterName}/${UUID}
```
有关格式的更多信息 ARNs，请参阅 [Amazon 资源名称 (ARNs) 和 AWS 服务命名空间](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)。
例如，要在语句中指定 `CustomerMessages` 实例，请使用以下 ARN：
```
"Resource": "arn:aws:kafka:us-east-1:123456789012:cluster/CustomerMessages/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2"
```
要指定属于特定账户的所有实例，请使用通配符 (\$1)：
```
"Resource": "arn:aws:kafka:us-east-1:123456789012:cluster/*"
```
无法对特定资源执行某些 Amazon MSK 操作，例如用于创建资源的操作。在这些情况下，您必须使用通配符（\$1)。
```
"Resource": "*"
```
要在单个语句中指定多个资源，请 ARNs 用逗号分隔。
```
"Resource": ["resource1", "resource2"]
```
*要查看亚马逊 MSK 资源类型及其列表 ARNs，请参阅 IAM 用户指南中的[亚马逊托管流媒体为 Apache Kafka 定义的资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonmanagedstreamingforkafka.html#amazonmanagedstreamingforkafka-resources-for-iam-policies)。*要了解您可以在哪些操作中指定每个资源的 ARN，请参阅 [Amazon Managed Streaming for Apache Kafka 定义的操作](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonmanagedstreamingforkafka.html#amazonmanagedstreamingforkafka-actions-as-permissions)。
## Amazon MSK 基于身份的策略的条件密钥
管理员可以使用 AWS JSON 策略来指定谁有权访问什么。也就是说，哪个**主体**可以对什么**资源**执行**操作**，以及在什么**条件**下执行。
`Condition` 元素根据定义的条件指定语句何时执行。您可以创建使用[条件运算符](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)（例如，等于或小于）的条件表达式，以使策略中的条件与请求中的值相匹配。要查看所有 AWS 全局条件键，请参阅 *IAM 用户指南*中的[AWS 全局条件上下文密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)。
Amazon MSK 定义了自己的一组条件键，还支持使用一些全局条件键。要查看所有 AWS 全局条件键，请参阅 *IAM 用户指南*中的[AWS 全局条件上下文密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)。
要查看 Amazon MSK 条件键的列表，请参阅《IAM 用户指南》**中的 [Amazon Managed Streaming for Apache Kafka 的条件键](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonmanagedstreamingforkafka.html#amazonmanagedstreamingforkafka-policy-keys)。要了解您可以对哪些操作和资源使用条件键，请参阅 [Amazon Managed Streaming for Apache Kafka 定义的操作](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonmanagedstreamingforkafka.html#amazonmanagedstreamingforkafka-actions-as-permissions)。
## Amazon MSK 基于身份的策略的示例
要查看 Amazon MSK 基于身份的策略的示例，请参阅 [Amazon MSK 基于身份的策略示例](security_iam_id-based-policy-examples.md)。
# Amazon MSK 基于资源的策略
Amazon MSK 支持用于 Amazon MSK 集群的集群策略（也称为基于资源的策略）。您可以使用集群策略来定义哪些 IAM 主体拥有跨账户权限来设置与 Amazon MSK 集群的私有连接。当与 IAM 客户端身份验证一起使用时，您也可以使用集群策略为连接的客户端精细定义 Kafka 数据面板的权限。
集群策略支持的最大大小为 20 KB。
要查看如何配置集群策略的示例，请参阅[步骤 2：将集群策略附加到 MSK 集群](mvpc-cluster-owner-action-policy.md)。
# 基于 Amazon MSK 标签的授权
您可以将标签附加到 Amazon MSK 集群。要基于标签控制访问，您需要使用 `kafka:ResourceTag/key-name``aws:RequestTag/key-name` 或 `aws:TagKeys` 条件键在策略的[条件元素](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)中提供标签信息。有关标记 Amazon MSK 资源的信息，请参阅[为 Amazon MSK 集群添加标签](msk-tagging.md)。
只能借助于标签来控制集群的访问。要向主题和使用者组添加标签，需在策略中添加一条不带标签的单独语句。
要查看基于身份的策略（用于基于集群上的标签来限制对该集群的访问）的示例，请参阅[根据标签访问 Amazon MSK 集群](security_iam_id-based-policy-examples-view-widget-tags.md)。
您可以在基于身份的策略中使用条件，以便基于标签控制对 Amazon MSK 资源的访问权限。此示例演示了如何创建允许用户描述集群、获取其引导代理、列出其代理节点、更新和删除集群的策略。但是，仅当集群标签 `Owner` 的值为该用户的 `username` 时，此策略才会授予权限。以下策略中的第二个语句允许访问集群中的主题。该策略中的第一个语句未授权任何主题访问权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessClusterIfOwner",
"Effect": "Allow",
"Action": [
"kafka:Describe*",
"kafka:Get*",
"kafka:List*",
"kafka:Update*",
"kafka:Delete*"
],
"Resource": "arn:aws:kafka:us-east-1:123456789012:cluster/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Owner": "${aws:username}"
}
}
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:*Topic*",
"kafka-cluster:WriteData",
"kafka-cluster:ReadData"
],
"Resource": [
"arn:aws:kafka:us-east-1:123456789012:topic/*"
]
}
]
}
```
------
# Amazon MSK IAM 角色
[IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)是 Amazon Web Services 账户中具有特定权限的实体。
## 将临时凭证用于 Amazon MSK
可以使用临时凭证进行联合身份验证登录，分派 IAM 角色或分派跨账户角色。您可以通过调用[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)或之类的 AWS STS API 操作来获取临时安全证书[GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html)。
Amazon MSK 支持使用临时凭证。
## 服务关联角色
[服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)允许 Amazon Web Services 访问其他服务中的资源，以代表您完成操作。服务关联角色显示在 IAM 账户中，并归该服务所有。管理员可以查看但不能编辑服务相关角色的权限。
Amazon MSK 支持服务相关角色。有关创建或管理 Amazon MSK 服务相关角色的详细信息，请参阅[Amazon MSK 的服务相关角色](using-service-linked-roles.md)。
# Amazon MSK 基于身份的策略示例
默认情况下，IAM 用户和角色无权执行 Amazon MSK API 操作。管理员必须创建 IAM policy，以便为用户和角色授予权限以对所需的指定资源执行特定的 API 操作。然后，管理员必须将这些策略附加到需要这些权限的 IAM 用户或组。
要了解如何使用这些示例 JSON 策略文档创建 IAM 基于身份的策略，请参阅*《IAM 用户指南》*中的 [在 JSON 选项卡上创建策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor)。
**Topics**
+ [
# 策略最佳实践
](security_iam_service-with-iam-policy-best-practices.md)
+ [
# 允许用户查看他们自己的权限
](security_iam_id-based-policy-examples-view-own-permissions.md)
+ [
# 访问一个 Amazon MSK 集群
](security_iam_id-based-policy-examples-access-one-cluster.md)
+ [
# 根据标签访问 Amazon MSK 集群
](security_iam_id-based-policy-examples-view-widget-tags.md)
# 策略最佳实践
基于身份的策略确定某个人是否可以创建、访问或删除您账户中的 Amazon MSK 资源。这些操作可能会使 AWS 账户产生成本。创建或编辑基于身份的策略时，请遵循以下指南和建议：
+ **开始使用 AWS 托管策略并转向最低权限权限** — 要开始向用户和工作负载授予权限，请使用为许多常见用例授予权限的*AWS 托管策略*。它们在你的版本中可用 AWS 账户。我们建议您通过定义针对您的用例的 AWS 客户托管策略来进一步减少权限。有关更多信息，请参阅《IAM 用户指南》**中的 [AWS 托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)或[工作职能的AWS 托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html)。
+ **应用最低权限**：在使用 IAM 策略设置权限时，请仅授予执行任务所需的权限。为此，您可以定义在特定条件下可以对特定资源执行的操作，也称为*最低权限许可*。有关使用 IAM 应用权限的更多信息，请参阅《IAM 用户指南》**中的 [IAM 中的策略和权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)。
+ **使用 IAM 策略中的条件进一步限制访问权限**：您可以向策略添加条件来限制对操作和资源的访问。例如，您可以编写策略条件来指定必须使用 SSL 发送所有请求。如果服务操作是通过特定的方式使用的，则也可以使用条件来授予对服务操作的访问权限 AWS 服务，例如 CloudFormation。有关更多信息，请参阅《IAM 用户指南》**中的 [IAM JSON 策略元素：条件](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)。
+ **使用 IAM Access Analyzer 验证您的 IAM 策略，以确保权限的安全性和功能性**：IAM Access Analyzer 会验证新策略和现有策略，以确保策略符合 IAM 策略语言（JSON）和 IAM 最佳实践。IAM Access Analyzer 提供 100 多项策略检查和可操作的建议，以帮助您制定安全且功能性强的策略。有关更多信息，请参阅《IAM 用户指南》**中的[使用 IAM Access Analyzer 验证策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html)。
+ **需要多重身份验证 (MFA**)-如果 AWS 账户您的场景需要 IAM 用户或根用户，请启用 MFA 以提高安全性。若要在调用 API 操作时需要 MFA，请将 MFA 条件添加到您的策略中。有关更多信息，请参阅《IAM 用户指南》**中的[使用 MFA 保护 API 访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html)。
有关 IAM 中的最佳实操的更多信息，请参阅《IAM 用户指南》**中的 [IAM 中的安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
# 允许用户查看他们自己的权限
该示例说明了您如何创建策略，以允许 IAM 用户查看附加到其用户身份的内联和托管式策略。此策略包括在控制台上或使用 AWS CLI 或 AWS API 以编程方式完成此操作的权限。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}
```
# 访问一个 Amazon MSK 集群
在此示例中，您想要为 Amazon Web Services 账户中的 IAM 用户授予访问某个集群 `purchaseQueriesCluster` 的权限。此策略允许用户描述集群、获取其引导代理、列出其代理节点并更新它。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"UpdateCluster",
"Effect":"Allow",
"Action":[
"kafka:Describe*",
"kafka:Get*",
"kafka:List*",
"kafka:Update*"
],
"Resource":"arn:aws:kafka:us-east-1:012345678012:cluster/purchaseQueriesCluster/abcdefab-1234-abcd-5678-cdef0123ab01-2"
}
]
}
```
------
# 根据标签访问 Amazon MSK 集群
您可以在基于身份的策略中使用条件，以便基于标签控制对 Amazon MSK 资源的访问权限。此示例演示了如何创建允许用户描述集群、获取其引导代理、列出其代理节点、更新和删除集群的策略。但是，仅当集群标签 `Owner` 的值为该用户的用户名时，才能授予此权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessClusterIfOwner",
"Effect": "Allow",
"Action": [
"kafka:Describe*",
"kafka:Get*",
"kafka:List*",
"kafka:Update*",
"kafka:Delete*"
],
"Resource": "arn:aws:kafka:us-east-1:012345678012:cluster/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Owner": "${aws:username}"
}
}
}
]
}
```
------
您可以将该策略附加到您账户中的 IAM 用户。如果名为 `richard-roe` 的用户尝试更新 MSK 集群，必须将集群标记为 `Owner=richard-roe` 或 `owner=richard-roe`。否则，他将被拒绝访问。条件标签键 `Owner` 匹配 `Owner` 和 `owner`，因为条件键名称不区分大小写。有关更多信息，请参阅 *IAM 用户指南* 中的 [IAM JSON 策略元素：条件](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)。
# Amazon MSK 的服务相关角色
Amazon MSK 使用 AWS Identity and Access Management (IAM) [服务相关](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)角色。服务相关角色是一种独特类型的 IAM 角色，它与 Amazon MSK 直接关联。服务相关角色由 Amazon MSK 预定义，包括该服务代表您调用其他 AWS 服务所需的所有权限。
服务相关角色可让您更轻松地设置 Amazon MSK，因为您不必手动添加所需权限。Amazon MSK 可定义其服务相关角色的权限。除非另行定义，否则只有 Amazon MSK 才能代入其角色。定义的权限包括信任策略和权限策略，而且权限策略不能附加到任何其他 IAM 实体。
有关支持服务相关角色的其他服务的信息，请参阅[使用 IAM 的 Amazon Web Services](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)，并查找**服务相关角色**列中显示为**是**的服务。请选择**是**与查看该服务的服务关联角色文档的链接。
**Topics**
+ [服务相关角色权限](slr-permissions.md)
+ [创建服务相关角色](create-slr.md)
+ [编辑服务相关角色](edit-slr.md)
+ [服务相关角色的受支持区域](slr-regions.md)
# Amazon MSK 的服务相关角色权限
Amazon MSK 使用名为 **AWSServiceRoleForKafka** 的服务相关角色。Amazon MSK 使用此角色来访问您的资源并执行以下操作：
+ `*NetworkInterface` – 在客户账户中创建和管理网络接口，使客户 VPC 中的客户端可以访问集群代理。
+ `*VpcEndpoints`— 管理客户账户中的 VPC 终端节点，这些终端节点允许客户 VPC 中的客户使用集群代理 AWS PrivateLink。Amazon MSK 对 `DescribeVpcEndpoints`、`ModifyVpcEndpoint` 和 `DeleteVpcEndpoints` 使用权限。
+ `secretsmanager`— 使用管理客户凭证 AWS Secrets Manager。
+ `GetCertificateAuthorityCertificate` – 检索私有证书颁发机构的证书。
+ `*Ipv6Addresses`— 为客户账户中的网络接口分配和取消分配 IPv6 地址，以启用 MSK IPv6 群集的连接。
+ `ModifyNetworkInterfaceAttribute`— 修改客户帐户中的网络接口属性以配置 MSK 集群连接的 IPv6 设置。
此服务相关角色附加到以下托管策略：`KafkaServiceRolePolicy`。有关此策略的更新，请参阅[KafkaServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/KafkaServiceRolePolicy.html)。
AWSServiceRoleForKafka 服务相关角色信任以下服务代入该角色：
+ `kafka.amazonaws.com`
角色权限策略允许 Amazon MSK 对资源完成以下操作。
您必须配置权限，允许 IAM 实体（如用户、组或角色）创建、编辑或删除服务关联角色。有关更多信息，请参阅《IAM 用户指南》**中的[服务关联角色权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions)。
# 为 Amazon MSK 创建服务相关角色
您无需手动创建服务相关角色。当您在 AWS 管理控制台、或 AWS API 中创建 Amazon MSK 集群时 AWS CLI，Amazon MSK 会为您创建服务相关角色。
如果您删除该服务关联角色，然后需要再次创建，您可以使用相同流程在账户中重新创建此角色。当您创建 Amazon MSK 集群时，Amazon MSK 将再次为您创建服务相关角色。
# 编辑 Amazon MSK 的服务相关角色
Amazon MSK 不允许您编辑 AWSServiceRoleForKafka 服务相关角色。创建服务关联角色后，您将无法更改角色的名称，因为可能有多种实体引用该角色。但是可以使用 IAM 编辑角色描述。有关更多信息，请参阅《IAM 用户指南》**中的[编辑服务关联角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role)。
# Amazon MSK 服务相关角色支持的区域
Amazon MSK 支持在该服务可用的所有区域中使用服务相关角色。有关更多信息，请参阅[AWS 区域和端点](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
# AWS 亚马逊 MSK 的托管策略
AWS 托管策略是由创建和管理的独立策略 AWS。 AWS 托管策略旨在为许多常见用例提供权限，以便您可以开始为用户、组和角色分配权限。
请记住， AWS 托管策略可能不会为您的特定用例授予最低权限权限，因为它们可供所有 AWS 客户使用。我们建议通过定义特定于使用案例的[客户管理型策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies)来进一步减少权限。
您无法更改 AWS 托管策略中定义的权限。如果 AWS 更新 AWS 托管策略中定义的权限，则更新会影响该策略所关联的所有委托人身份（用户、组和角色）。 AWS 最有可能在启动新的 API 或现有服务可以使用新 AWS 服务 的 API 操作时更新 AWS 托管策略。
有关更多信息，请参阅《IAM 用户指南》**中的 [AWS 托管式策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
# AWS 托管策略：Amazon A MSKFull ccess
此策略授予管理权限，允许主体完全访问所有 Amazon MSK 操作。此策略中的权限分组如下：
+ Amazon MSK 权限允许所有 Amazon MSK 操作。
+ **`Amazon EC2` 权限** – 此策略中需要才能验证 API 请求中的已传递资源。这是为了确保 Amazon MSK 能够成功在集群中使用资源。此策略中的其他 Amazon EC2 权限允许 Amazon MSK 创建必要的 AWS 资源，使您能够连接到您的集群。
+ **`AWS KMS` 权限** – API 调用期间用于验证请求中的已传递资源。Amazon MSK 必须使用它们才能在 Amazon MSK 集群中使用传递的密钥。
+ **`CloudWatch Logs, Amazon S3, and Amazon Data Firehose` 权限** – Amazon MSK 需要才能确保可到达日志传输目标及这些目标对代理日志使用有效。
+ **`IAM` 权限** – Amazon MSK 需要才能在您的账户中创建服务相关角色，并允许您将服务执行角色传递给 Amazon MSK。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"kafka:*",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeSecurityGroups",
"ec2:DescribeRouteTables",
"ec2:DescribeVpcEndpoints",
"ec2:DescribeVpcAttribute",
"kms:DescribeKey",
"kms:CreateGrant",
"logs:CreateLogDelivery",
"logs:GetLogDelivery",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:ListLogDeliveries",
"logs:PutResourcePolicy",
"logs:DescribeResourcePolicies",
"logs:DescribeLogGroups",
"S3:GetBucketPolicy",
"firehose:TagDeliveryStream"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint"
],
"Resource": [
"arn:*:ec2:*:*:vpc/*",
"arn:*:ec2:*:*:subnet/*",
"arn:*:ec2:*:*:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint"
],
"Resource": [
"arn:*:ec2:*:*:vpc-endpoint/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/AWSMSKManaged": "true"
},
"StringLike": {
"aws:RequestTag/ClusterArn": "*"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:*:ec2:*:*:vpc-endpoint/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateVpcEndpoint"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DeleteVpcEndpoints"
],
"Resource": "arn:*:ec2:*:*:vpc-endpoint/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/AWSMSKManaged": "true"
},
"StringLike": {
"ec2:ResourceTag/ClusterArn": "*"
}
}
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "*",
"Condition": {
"StringEquals": {
"iam:PassedToService": "kafka.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kafka.amazonaws.com/AWSServiceRoleForKafka*",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kafka.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/kafka.amazonaws.com/AWSServiceRoleForKafka*"
},
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/delivery.logs.amazonaws.com/AWSServiceRoleForLogDelivery*",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "delivery.logs.amazonaws.com"
}
}
}
]
}
```
------
# AWS 托管策略：Amazon MSKRead OnlyAccess
此策略授予只读权限，允许用户查看 Amazon MSK 中的信息。附加此策略的主体不能进行任何更新或删除现有资源，也不能创建新的 Amazon MSK 资源。例如，拥有这些权限的主体可以查看与其账户关联的集群和配置列表，但不能更改任何集群的配置或设置。此策略中的权限分组如下：
+ **`Amazon MSK` 权限** – 允许您列出 Amazon MSK 资源、对它们进行描述并获取有关它们的信息。
+ **`Amazon EC2`权限** — 用于描述与集群关联的 Amazon VPC、 ENIs 子网、安全组。
+ **`AWS KMS` 权限** – 用于描述与集群关联的密钥。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"kafka:Describe*",
"kafka:List*",
"kafka:Get*",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"kms:DescribeKey"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
# AWS 托管策略： KafkaServiceRolePolicy
您无法附加 KafkaServiceRolePolicy 到您的 IAM 实体。将此策略附加到服务相关角色，该角色允许 Amazon MSK 执行诸如管理 MSK 集群上的 VPC 端点（连接器）、管理网络接口和使用 AWS Secrets Manager管理集群凭证等操作。有关更多信息，请参阅 [Amazon MSK 的服务相关角色](using-service-linked-roles.md)。
下表描述了自 Amazon MSK 开始跟踪变更以来对 KafkaServiceRolePolicy 托管策略的更新。
| 更改 | 描述 | 日期 |
| --- | --- | --- |
| IPv6 已将@@ [连接支持添加到 KafkaServiceRolePolicy](#security-iam-awsmanpol-KafkaServiceRolePolicy) — 更新现有政策 | Amazon MSK KafkaServiceRolePolicy 向添加了启用 MSK IPv6 集群连接的权限。这些权限允许 Amazon MSK 为网络接口分配和取消分配 IPv6 地址，以及修改客户账户中的网络接口属性。 | 2025 年 11 月 17 日 |
| [KafkaServiceRolePolicy](#security-iam-awsmanpol-KafkaServiceRolePolicy)：对现有策略的更新 | Amazon MSK 添加了支持多 VPC 私有连接的权限。 | 2023 年 3 月 8 日 |
| Amazon MSK 开启了跟踪更改 | Amazon MSK 已开始跟踪 KafkaServiceRolePolicy 托管政策的变更。 | 2023 年 3 月 8 日 |
# AWS 托管策略： AWSMSKReplicatorExecutionRole
`AWSMSKReplicatorExecutionRole` 策略向 Amazon MSK 复制器授予在 MSK 集群之间复制数据的权限。此策略中的权限如下分组：
+ **`cluster`** – 向 Amazon MSK 复制器授予使用 IAM 身份验证连接到集群的权限。还授予描述和更改集群的权限。
+ **`topic`** – 向 Amazon MSK 复制器授予描述、创建和更改主题以及更改主题动态配置的权限。
+ **`consumer group`** – 向 Amazon MSK 复制器授予描述和更改消费者组、从 MSK 集群读取和写入日期以及删除复制器创建的内部主题的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ClusterPermissions",
"Effect": "Allow",
"Action": [
"kafka-cluster:Connect",
"kafka-cluster:DescribeCluster",
"kafka-cluster:AlterCluster",
"kafka-cluster:DescribeTopic",
"kafka-cluster:CreateTopic",
"kafka-cluster:AlterTopic",
"kafka-cluster:WriteData",
"kafka-cluster:ReadData",
"kafka-cluster:AlterGroup",
"kafka-cluster:DescribeGroup",
"kafka-cluster:DescribeTopicDynamicConfiguration",
"kafka-cluster:AlterTopicDynamicConfiguration",
"kafka-cluster:WriteDataIdempotently"
],
"Resource": [
"arn:aws:kafka:*:*:cluster/*"
]
},
{
"Sid": "TopicPermissions",
"Effect": "Allow",
"Action": [
"kafka-cluster:DescribeTopic",
"kafka-cluster:CreateTopic",
"kafka-cluster:AlterTopic",
"kafka-cluster:WriteData",
"kafka-cluster:ReadData",
"kafka-cluster:DescribeTopicDynamicConfiguration",
"kafka-cluster:AlterTopicDynamicConfiguration",
"kafka-cluster:AlterCluster"
],
"Resource": [
"arn:aws:kafka:*:*:topic/*/*"
]
},
{
"Sid": "GroupPermissions",
"Effect": "Allow",
"Action": [
"kafka-cluster:AlterGroup",
"kafka-cluster:DescribeGroup"
],
"Resource": [
"arn:aws:kafka:*:*:group/*/*"
]
}
]
}
```
------
# 亚马逊 MSK 更新了托 AWS 管政策
查看自该服务开始跟踪这些更改以来，Amazon MSK AWS 托管政策更新的详细信息。
| 更改 | 描述 | 日期 |
| --- | --- | --- |
| [WriteDataIdempotently 权限已添加到 AWSMSKReplicator ExecutionRole](security-iam-awsmanpol-AWSMSKReplicatorExecutionRole.md)-更新现有策略 | Amazon MSK 为 AWSMSKReplicatorExecutionRole 策略添加了支持 MSK 集群之间数据复制的 WriteDataIdempotently 权限。 | 2024 年 3 月 12 日 |
| [AWSMSKReplicatorExecutionRole](security-iam-awsmanpol-AWSMSKReplicatorExecutionRole.md)：新策略 | 亚马逊 MSK 增加了支持 Amazon MSK Replicator 的 AWSMSKReplicatorExecutionRole 政策。 | 2023 年 12 月 4 日 |
| [Amazon A MSKFull cces](security-iam-awsmanpol-AmazonMSKFullAccess.md) s — 更新现有政策 | Amazon MSK 添加了支持 Amazon MSK 复制器的权限。 | 2023 年 9 月 28 日 |
| [KafkaServiceRolePolicy](security-iam-awsmanpol-KafkaServiceRolePolicy.md)：对现有策略的更新 | Amazon MSK 添加了支持多 VPC 私有连接的权限。 | 2023 年 3 月 8 日 |
| [Amazon A MSKFull cces](security-iam-awsmanpol-AmazonMSKFullAccess.md) s — 更新现有政策 | Amazon MSK 添加了新的 Amazon EC2 权限，以便连接到集群。 | 2021 年 11 月 30 日 |
| [Amazon A MSKFull cces](security-iam-awsmanpol-AmazonMSKFullAccess.md) s — 更新现有政策 | Amazon MSK 添加了新权限，允许其描述 Amazon EC2 路由表。 | 2021 年 11 月 19 日 |
| Amazon MSK 开启了跟踪更改 | Amazon MSK 开始跟踪其 AWS 托管政策的变更。 | 2021 年 11 月 19 日 |
# 排查 Amazon MSK 身份和访问问题
使用以下信息可帮助您诊断和修复在使用 Amazon MSK 和 IAM 时可能遇到的常见问题。
**Topics**
+ [
## 我无权在 Amazon MSK 中执行操作
](#security_iam_troubleshoot-no-permissions)
## 我无权在 Amazon MSK 中执行操作
如果 AWS 管理控制台 告诉您您无权执行某项操作，则必须联系管理员寻求帮助。管理员是向您提供登录凭证的人。
当 `mateojackson` IAM 用户尝试使用控制台删除集群，但没有 `kafka:DeleteCluster` 权限时，会发生以下示例错误。
```
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: kafka:DeleteCluster on resource: purchaseQueriesCluster
```
在这种情况下，Mateo 请求他的管理员更新其策略，以允许他使用 `kafka:DeleteCluster` 操作访问 `purchaseQueriesCluster` 资源。
# Apache Kafka 的身份验证和授权 APIs
您可以使用 IAM 对客户端进行身份验证并允许或拒绝 Apache Kafka 操作。或者，您可以使用 TLS 或对客户端 SASL/SCRAM 进行身份验证，使用 Apache Kafka ACLs 来允许或拒绝操作。
有关如何控制谁可以在您的集群上执行 [Amazon MSK 操作](https://docs.aws.amazon.com/msk/1.0/apireference/operations.html)的信息，请参阅[亚马逊 MSK 的身份验证和授权 APIs](security-iam.md)。
**Topics**
+ [
# IAM 访问控制
](iam-access-control.md)
+ [
# Amazon MSK 的双向 TLS 客户端身份验证
](msk-authentication.md)
+ [
# 使用 S AWS ecrets Manager 进行登录凭据身份验证
](msk-password.md)
+ [
# 阿帕奇 Kafka ACLs
](msk-acls.md)
# IAM 访问控制
Amazon MSK 的 IAM 访问控制让您能够处理 MSK 集群的身份验证和授权。这样就不需要使用一种身份验证机制和另一种授权机制。例如，当客户端尝试写入您的集群时，Amazon MSK 使用 IAM 来检查该客户端是否是经过身份验证的身份，以及是否有权向您的集群生成数据。
IAM 访问控制适用于 Java 和非 Java 客户端，包括用 Python、 JavaScript Go 和.NET 编写的 Kafka 客户端。非 Java 客户端的 IAM 访问控制适用于 Kafka 版本 2.7.1 或更高版本的 MSK 集群。
为了能够进行 IAM 访问控制，Amazon MSK 对 Apache Kafka 源代码进行了少许修改。这些修改不会给您的 Apache Kafka 体验造成明显的影响。Amazon MSK 会记录访问事件，以方便您进行审计。
您可以 APIs 为使用 IAM 访问控制的 MSK 集群调用 Apache Kafka ACL。但是，Apache Kafka 对 IAM 身份的授权 ACLs 没有影响。您必须将 IAM 策略用于 IAM 身份的访问控制。
**重要注意事项**
对 MSK 集群使用 IAM 访问控制时，请记住以下重要注意事项：
IAM 访问控制不适用于 Apache ZooKeeper 节点。有关如何控制对这些节点的访问权限的信息，请参阅 [控制对亚马逊 MSK ZooKeeper 集群中 Apache 节点的访问权限](zookeeper-security.md)。
如果您的集群使用 IAM 访问控制，则 `allow.everyone.if.no.acl.found` Apache Kafka 设置无效。
您可以 APIs 为使用 IAM 访问控制的 MSK 集群调用 Apache Kafka ACL。但是，Apache Kafka 对 IAM 身份的授权 ACLs 没有影响。您必须将 IAM 策略用于 IAM 身份的访问控制。
# Amazon MSK 的 IAM 访问控制的工作原理
要对 Amazon MSK 使用 IAM 访问控制，请执行以下步骤，以下主题将详细介绍这些步骤：
+ [创建使用 IAM 访问控制的 Amazon MSK 集群](create-iam-access-control-cluster-in-console.md)
+ [配置客户端以进行 IAM 访问控制](configure-clients-for-iam-access-control.md)
+ [为 IAM 角色创建授权策略](create-iam-access-control-policies.md)
+ [获取用于 IAM 访问控制的引导代理](get-bootstrap-brokers-for-iam.md)
# 创建使用 IAM 访问控制的 Amazon MSK 集群
本节介绍如何使用 AWS 管理控制台、API 或创建使用 IAM 访问控制的 Amazon MSK 集群。 AWS CLI 有关如何为现有集群开启 IAM 访问控制的信息，请参阅[更新 Amazon MSK 集群的安全设置](msk-update-security.md)。
**使用创建 AWS 管理控制台 使用 IAM 访问控制的集群**
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 选择**创建集群**。
1. 选择**使用自定义设置创建集群**。
1. 在**身份验证**部分中，选择 **IAM 访问控制**。
1. 完成创建集群的其余工作流程。
**使用 API 或创建 AWS CLI 使用 IAM 访问控制的集群**
+ 要创建启用了 IAM 访问控制的集群，请使用 [CreateCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters.html#CreateCluster)API 或 [create-cluster CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/create-cluster.html) 命令，并传递以下 JSON 作为`ClientAuthentication`参数：。`"ClientAuthentication": { "Sasl": { "Iam": { "Enabled": true } }`
# 配置客户端以进行 IAM 访问控制
要让客户端能够与使用 IAM 访问控制的 MSK 集群通信，您可以使用以下任何一种机制：
+ 使用 SASL\$1OAUTHBEARER机制进行非 Java 客户端配置
+ 使用 SASL\$1OAUTHBEARER机制或 AWS\$1MSK\$1IAM 机制配置 Java 客户端
## 使用该 SASL\$1OAUTHBEARER机制配置 IAM
1. 使用以下 Python Kafka 客户端示例，编辑 client.properties 配置文件。其他语言的配置更改与之类似。
```
from kafka import KafkaProducer
from kafka.errors import KafkaError
from kafka.sasl.oauth import AbstractTokenProvider
import socket
import time
from aws_msk_iam_sasl_signer import MSKAuthTokenProvider
class MSKTokenProvider():
def token(self):
token, _ = MSKAuthTokenProvider.generate_auth_token('')
return token
tp = MSKTokenProvider()
producer = KafkaProducer(
bootstrap_servers='',
security_protocol='SASL_SSL',
sasl_mechanism='OAUTHBEARER',
sasl_oauth_token_provider=tp,
client_id=socket.gethostname(),
)
topic = ""
while True:
try:
inp=input(">")
producer.send(topic, inp.encode())
producer.flush()
print("Produced!")
except Exception:
print("Failed to send message:", e)
producer.close()
```
1. 下载所选配置语言的帮助程序库，然后按照该语言库主页的“*开始使用*”部分中的说明进行操作。
+ JavaScript: [https://github.com/aws/aws-msk-iam-sasl-signer-js \$1getting-star](https://github.com/aws/aws-msk-iam-sasl-signer-js#getting-started) ted
+ Python：[https://github.com/aws/aws-msk-iam-sasl-signer-python \$1get-](https://github.com/aws/aws-msk-iam-sasl-signer-python#get-started) 已启动
+ Go: [https://github.com/aws/aws-msk-iam-sasl-signer-](https://github.com/aws/aws-msk-iam-sasl-signer-go#getting-started) go \$1getting-started
+ .NET: [https://github.com/aws/aws-msk-iam-sasl-signer-net \$1getting-](https://github.com/aws/aws-msk-iam-sasl-signer-net#getting-started) 已启动
+ JAVA：可通过 ja [https://github.com/aws/aws-msk-iam-auth/releases](https://github.com/aws/aws-msk-iam-auth/releases)r 文件获得对 Java 的 SASL\$1OAUTHBEARER支持
## 使用 MSK 自定义 AWS\$1MSK\$1IAM 机制配置 IAM
1. 将以下内容添加到 `client.properties` 文件中。**替换为客户端上信任存储文件的完全限定路径。
**注意**
如果您不想使用特定证书，可以从 `client.properties` 文件中删除 `ssl.truststore.location=`。如果您不指定 `ssl.truststore.location` 的值，Java 进程将使用默认证书。
```
ssl.truststore.location=
security.protocol=SASL_SSL
sasl.mechanism=AWS_MSK_IAM
sasl.jaas.config=software.amazon.msk.auth.iam.IAMLoginModule required;
sasl.client.callback.handler.class=software.amazon.msk.auth.iam.IAMClientCallbackHandler
```
要使用您为 AWS 凭证创建的命名配置文件，请将其包含`awsProfileName="your profile name";`在您的客户端配置文件中。有关命名配置文件的信息，请参阅文档中的[命名配置](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) AWS CLI 文件。
1. 下载最新的稳定版 [aws-msk-iam-auth](https://github.com/aws/aws-msk-iam-auth/releases)JAR 文件，并将其放在类路径中。如果您使用 Maven，请添加以下依赖项，并根据需要调整版本号：
```
software.amazon.msk
aws-msk-iam-auth
1.0.0
```
Amazon MSK 客户端插件在 Apache 2.0 许可证下是开源的。
# 为 IAM 角色创建授权策略
将授权策略附加到与客户端对应的 IAM 角色。在授权策略中，您可以指定角色允许或拒绝哪些操作。如果您的客户端位于 Amazon EC2 实例上，请将授权策略与该 Amazon EC2 实例的 IAM 角色关联。或者，您也可以将客户端配置为使用命名配置文件，然后将授权策略与该命名配置文件的角色关联。[配置客户端以进行 IAM 访问控制](configure-clients-for-iam-access-control.md) 介绍如何将客户端配置为使用命名配置文件。
有关如何创建 IAM policy 的信息，请参阅[创建 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。
以下是名为的集群的授权策略示例 MyTestCluster。要了解 `Action` 和 `Resource` 元素的语义，请参阅 [IAM 授权策略、操作和资源的语义](kafka-actions.md)。
**重要**
您对 IAM 策略所做的更改会 AWS CLI 立即反映在 IAM APIs 中。但是，策略更改可能需要很长时间才能生效。在大多数情况下，策略更改会在不到一分钟的时间内生效。网络状况有时可能会增加延迟时间。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kafka-cluster:Connect",
"kafka-cluster:AlterCluster",
"kafka-cluster:DescribeCluster"
],
"Resource": [
"arn:aws:kafka:us-east-1:111122223333:cluster/MyTestCluster/abcd1234-0123-abcd-5678-1234abcd-1"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:*Topic*",
"kafka-cluster:WriteData",
"kafka-cluster:ReadData"
],
"Resource": [
"arn:aws:kafka:us-east-1:123456789012:topic/MyTestCluster/*"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:AlterGroup",
"kafka-cluster:DescribeGroup"
],
"Resource": [
"arn:aws:kafka:us-east-1:123456789012:group/MyTestCluster/*"
]
}
]
}
```
------
要了解如何创建包含与常见 Apache Kafka 用例（例如创建和使用数据）对应的操作元素的策略，请参阅[客户端授权策略的常见使用场景](iam-access-control-use-cases.md)。
[对于 Kafka 版本 2.8.0 及更高版本，该**WriteDataIdempotently**权限已被弃用 (KIP-679)。](https://cwiki.apache.org/confluence/display/KAFKA/KIP-679%3A+Producer+will+enable+the+strongest+delivery+guarantee+by+default)默认情况下，设置了 `enable.idempotence = true`。因此，对于 Kafka 版本 2.8.0 及更高版本，IAM 不提供与 Kafka 相同的功能。 ACLs仅提供 `WriteData` 对某个主题的访问权限，无法 `WriteDataIdempotently` 到该主题。这不会影响将 `WriteData` 提供给**所有**主题的情况。在这种情况下，允许 `WriteDataIdempotently`。这是由于 IAM 逻辑的实现和 Kafka ACLs 的实现方式存在差异。此外，以幂等方式写入一个主题也需要访问 `transactional-ids`。
要解决这个问题，建议使用类似于以下策略的策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kafka-cluster:Connect",
"kafka-cluster:AlterCluster",
"kafka-cluster:DescribeCluster",
"kafka-cluster:WriteDataIdempotently"
],
"Resource": [
"arn:aws:kafka:us-east-1:123456789012:cluster/MyTestCluster/abcd1234-0123-abcd-5678-1234abcd-1"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:*Topic*",
"kafka-cluster:WriteData",
"kafka-cluster:ReadData"
],
"Resource": [
"arn:aws:kafka:us-east-1:123456789012:topic/MyTestCluster/abcd1234-0123-abcd-5678-1234abcd-1/TestTopic",
"arn:aws:kafka:us-east-1:123456789012:transactional-id/MyTestCluster/abcd1234-0123-abcd-5678-1234abcd-1/*"
]
}
]
}
```
------
在这种情况下，`WriteData` 允许写入 `TestTopic`，而 `WriteDataIdempotently` 允许对集群进行幂等性写入。该策略还增加了对未来所需的 `transactional-id` 资源的访问权限。
由于 `WriteDataIdempotently` 是集群级权限，因此无法主题级别使用。如果 `WriteDataIdempotently` 仅限于主题级别，则此策略将不起作用。
# 获取用于 IAM 访问控制的引导代理
请参阅[获取 Amazon MSK 集群的引导代理](msk-get-bootstrap-brokers.md)。
# IAM 授权策略、操作和资源的语义
**注意**
对于运行 Apache Kafka 3.8 或更高版本的集群，IAM 访问控制支持用于终止 WriteTxnMarkers 交易的 API。对于运行 Kafka 版本低于 3.8 的集群，IAM 访问控制不支持内部集群操作，包括 WriteTxnMarkers。对于这些早期版本，要终止交易，请使用带有相应的 SCRAM 或 mTLS 身份验证， ACLs 而不是 IAM 身份验证。
本部分解释了可以在 IAM 授权策略中使用的操作和资源元素的语义。有关策略示例，请参阅 [为 IAM 角色创建授权策略](create-iam-access-control-policies.md)。
## 授权策略操作
下表列出了在使用 Amazon MSK 的 IAM 访问控制时可以在授权策略中包含的操作。当您在授权策略中包含表*操作*列中的操作时，还必须包含*所需操作*列中的相应操作。
| Action | 说明 | 所需的操作 | 所需的资源 | 适用于无服务器集群 |
| --- | --- | --- | --- | --- |
| kafka-cluster:Connect | 授予连接和验证集群的权限。 | 无 | cluster | 是 |
| kafka-cluster:DescribeCluster | 授予描述集群各个方面的权限，相当于 Apache Kafka 的 DESCRIBE CLUSTER ACL。 | `kafka-cluster:Connect` | cluster | 是 |
| kafka-cluster:AlterCluster | 授予更改集群各个方面的权限，相当于 Apache Kafka 的 ALTER CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeCluster` | cluster | 否 |
| kafka-cluster:DescribeClusterDynamicConfiguration | 授予描述集群动态配置的权限，相当于 Apache Kafka 的 DESCRIBE\$1CONFIGS CLUSTER ACL。 | `kafka-cluster:Connect` | cluster | 否 |
| kafka-cluster:AlterClusterDynamicConfiguration | 授予更改集群动态配置的权限，相当于 Apache Kafka 的 ALTER\$1CONFIGS CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeClusterDynamicConfiguration` | cluster | 否 |
| kafka-cluster:WriteDataIdempotently | 授予在集群上以幂等方式写入数据的权限，相当于 Apache Kafka 的 IDEMPOTENT\$1WRITE CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:WriteData` | cluster | 是 |
| kafka-cluster:CreateTopic | 授予在集群上创建主题的权限，相当于 Apache Kafka 的创建 CLUSTER/TOPIC ACL。 | `kafka-cluster:Connect` | topic | 是 |
| kafka-cluster:DescribeTopic | 授予描述集群上主题的权限，相当于 Apache Kafka 的 DESCRIBE TOPIC ACL。 | `kafka-cluster:Connect` | topic | 是 |
| kafka-cluster:AlterTopic | 授予更改集群上主题的权限，相当于 Apache Kafka 的 ALTER TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | topic | 是 |
| kafka-cluster:DeleteTopic | 授予删除集群上主题的权限，相当于 Apache Kafka 的 DELETE TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | topic | 是 |
| kafka-cluster:DescribeTopicDynamicConfiguration | 授予描述集群上主题动态配置的权限，相当于 Apache Kafka 的 DESCRIBE\$1CONFIGS TOPIC ACL。 | `kafka-cluster:Connect` | topic | 是 |
| kafka-cluster:AlterTopicDynamicConfiguration | 授予更改集群上主题动态配置的权限，相当于 Apache Kafka 的 ALTER\$1CONFIGS TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopicDynamicConfiguration` | topic | 是 |
| kafka-cluster:ReadData | 授予从集群上主题中读取数据的权限，相当于 Apache Kafka 的 READ TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:AlterGroup` | topic | 是 |
| kafka-cluster:WriteData | 授予向集群上的主题写入数据的权限，相当于 Apache Kafka 的 WRITE TOPIC ACL | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | topic | 是 |
| kafka-cluster:DescribeGroup | 授予描述集群上群组的权限，相当于 Apache Kafka 的 DESCRIBE GROUP ACL。 | `kafka-cluster:Connect` | 组 | 是 |
| kafka-cluster:AlterGroup | 授予加入集群上群组的权限，相当于 Apache Kafka 的 READ GROUP ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeGroup` | 组 | 是 |
| kafka-cluster:DeleteGroup | 授予删除集群上群组的权限，相当于 Apache Kafka 的 DELETE GROUP ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeGroup` | 组 | 是 |
| kafka-cluster:DescribeTransactionalId | 授予描述集群 IDs 上交易的权限，相当于 Apache Kafka 的 DESCRIBE TRANSACTIONAL\$1ID ACL。 | `kafka-cluster:Connect` | transactional-id | 是 |
| kafka-cluster:AlterTransactionalId | 授予在集群 IDs 上更改事务的权限，相当于 Apache Kafka 的 WRITE TRANSACTIONAL\$1ID ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTransactionalId` `kafka-cluster:WriteData` | transactional-id | 是 |
在冒号之后的操作中，您可以任意次数地使用星号 (\$1) 通配符。示例如下。
+ `kafka-cluster:*Topic` 代表 `kafka-cluster:CreateTopic`、`kafka-cluster:DescribeTopic`、`kafka-cluster:AlterTopic` 和 `kafka-cluster:DeleteTopic`。它不包括 `kafka-cluster:DescribeTopicDynamicConfiguration` 或 `kafka-cluster:AlterTopicDynamicConfiguration`。
+ `kafka-cluster:*` 代表所有权限。
## 授权策略资源
下表显示了在使用 Amazon MSK 的 IAM 访问控制时可在授权策略中使用的四种资源。您可以使用 [DescribeCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)API 或 d [es](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI cribe-cluster 命令从 AWS 管理控制台 或中获取集群 Amazon 资源名称 (ARN)。然后，您可以使用集群 ARN 来构造主题、群组和交易 ID。 ARNs要在授权策略中指定资源，请使用该资源的 ARN。
| 资源 | ARN 格式 |
| --- | --- |
| Cluster | arn: aws: kafka::: cluster//regionaccount-idcluster-namecluster-uuid |
| Topic | arn: aws: kafka::: topic//regionaccount-idcluster-namecluster-uuidtopic-name |
| Group | arn: aws: kafka::: group//regionaccount-idcluster-namecluster-uuidgroup-name |
| 事务 ID | arn: aws: kafka::: transactional-id///regionaccount-idcluster-namecluster-uuidtransactional-id |
您可以在 ARN 中 `:cluster/`、`:topic/`、`:group/` 和 `:transactional-id/` 之后的任意位置，任意次数地使用星号 (\$1) 通配符。以下是如何使用星号 (\$1) 通配符引用多个资源的部分示例：
+ `arn:aws:kafka:us-east-1:0123456789012:topic/MyTestCluster/*`：任何名为的集群中的所有主题 MyTestCluster，无论集群的 UUID 如何。
+ `arn:aws:kafka:us-east-1:0123456789012:topic/MyTestCluster/abcd1234-0123-abcd-5678-1234abcd-1/*_test`：集群中名称以 “\$1test” 结尾的所有主题，其名称为，UUID 为 abcd1234-0123-abcd-56 MyTestCluster 78-1234abcd-1。
+ `arn:aws:kafka:us-east-1:0123456789012:transactional-id/MyTestCluster/*/5555abcd-1111-abcd-1234-abcd1234-1`：所有交易 ID 为 5555abcd-1111-abcd-1234-abcd-1234-1 的交易，适用于您的账户中命名的集群的所有化身。 MyTestCluster 这意味着，如果您创建了一个名为 MyTestCluster的集群，然后将其删除，然后创建另一个同名集群，则可以使用此资源 ARN 在两个集群上表示相同的交易 ID。但是，无法访问已删除的集群。
# 客户端授权策略的常见使用场景
下表中的第一列显示了一些常见用例。要授权客户端执行给定用例，请在客户端的授权策略中包含该用例所需的操作，并将 `Effect` 设置为 `Allow`。
有关 Amazon MSK 的 IAM 访问控制之所有操作的信息，请参阅 [IAM 授权策略、操作和资源的语义](kafka-actions.md)。
**注意**
默认情况下，操作将被拒绝。您必须明确允许要授权客户端执行的每个操作。
****
| 使用案例 | 所需的操作 |
| --- | --- |
| Admin | `kafka-cluster:*` |
| 创建话题 | `kafka-cluster:Connect` `kafka-cluster:CreateTopic` |
| 生成数据 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:WriteData` |
| 使用数据 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DescribeGroup` `kafka-cluster:AlterGroup` `kafka-cluster:ReadData` |
| 以幂等方式生成数据 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:WriteData` `kafka-cluster:WriteDataIdempotently` |
| 以事务方式生成数据 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:WriteData` `kafka-cluster:DescribeTransactionalId` `kafka-cluster:AlterTransactionalId` |
| 描述集群的配置 | `kafka-cluster:Connect` `kafka-cluster:DescribeClusterDynamicConfiguration` |
| 更新集群的配置 | `kafka-cluster:Connect` `kafka-cluster:DescribeClusterDynamicConfiguration` `kafka-cluster:AlterClusterDynamicConfiguration` |
| 描述主题的配置 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopicDynamicConfiguration` |
| 更新主题的配置 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopicDynamicConfiguration` `kafka-cluster:AlterTopicDynamicConfiguration` |
| 更改主题 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:AlterTopic` |
# Amazon MSK 的双向 TLS 客户端身份验证
可以为从应用程序到 Amazon MSK 代理的连接启用 TLS 客户端身份验证。要使用客户端身份验证，您需要有 AWS 私有 CA。 AWS 私有 CA 可以与您的集群位于 AWS 账户 同一个账户中，也可以位于不同的账户中。有关 AWS 私有 CA s 的信息，请参阅[创建和管理 AWS 私有 CA](https://docs.aws.amazon.com/acm-pca/latest/userguide/create-CA.html)。
Amazon MSK 不支持证书吊销列表 () CRLs。要控制对集群主题的访问权限或屏蔽已泄露的证书，请使用 Apache Kafka ACLs 和 AWS 安全组。有关使用 Apache Kafka 的信息 ACLs，请参阅。[阿帕奇 Kafka ACLs](msk-acls.md)
**Topics**
+ [
# 创建支持客户端身份验证的 Amazon MSK 集群
](msk-authentication-cluster.md)
+ [
# 将客户端设置为使用身份验证
](msk-authentication-client.md)
+ [
# 使用身份验证生成和使用消息
](msk-authentication-messages.md)
# 创建支持客户端身份验证的 Amazon MSK 集群
此过程向您展示如何使用启用客户端身份验证 AWS 私有 CA。
**注意**
在使用双向 TLS 控制访问时，我们强烈建议 AWS 私有 CA 对每个 MSK 集群使用独立模式。这样做可以确保由签名的 TLS 证书 PCAs 仅在单个 MSK 集群中进行身份验证。
1. 使用以下内容创建名为 `clientauthinfo.json` 的文件。*Private-CA-ARN*替换为您的 PCA 的 ARN。
```
{
"Tls": {
"CertificateAuthorityArnList": ["Private-CA-ARN"]
}
}
```
1. 创建一个名为 `brokernodegroupinfo.json` 的文件，如[使用创建预配置的 Amazon MSK 集群 AWS CLI](create-cluster-cli.md)中所述。
1. 客户端身份验证还要求您启用客户端和代理之间的传输中加密。使用以下内容创建名为 `encryptioninfo.json` 的文件。*KMS-Key-ARN*替换为您的 KMS 密钥的 ARN。可以将 `ClientBroker` 设置为 `TLS` 或 `TLS_PLAINTEXT`。
```
{
"EncryptionAtRest": {
"DataVolumeKMSKeyId": "KMS-Key-ARN"
},
"EncryptionInTransit": {
"InCluster": true,
"ClientBroker": "TLS"
}
}
```
有关加密的更多信息，请参阅[Amazon MSK 加密](msk-encryption.md)。
1. 在 AWS CLI 安装了身份验证和传输中加密的计算机上，运行以下命令来创建集群。保存响应中提供的集群 ARN。
```
aws kafka create-cluster --cluster-name "AuthenticationTest" --broker-node-group-info file://brokernodegroupinfo.json --encryption-info file://encryptioninfo.json --client-authentication file://clientauthinfo.json --kafka-version "{YOUR KAFKA VERSION}" --number-of-broker-nodes 3
```
# 将客户端设置为使用身份验证
此过程描述了如何设置 Amazon EC2 实例以用作客户端来使用身份验证。
此过程介绍了如何通过创建客户端计算机、创建主题和配置所需的安全设置，使用身份验证来生成和使用消息。
1. 创建用作客户端计算机的 Amazon EC2 实例。为简单起见，请在用于集群的同一 VPC 中创建此实例。有关如何创建此类客户端计算机的示例，请参阅[步骤 3：创建客户端计算机](create-client-machine.md)。
1. 创建主题。有关示例，请参阅[步骤 4：在 Amazon MSK 集群中创建主题](create-topic.md)下的说明。
1. 在已 AWS CLI 安装的计算机上，运行以下命令以获取集群的引导代理。*Cluster-ARN*替换为集群的 ARN。
```
aws kafka get-bootstrap-brokers --cluster-arn Cluster-ARN
```
保存与响应中的 `BootstrapBrokerStringTls` 关联的字符串。
1. 在客户端计算机上，运行以下命令以使用 JVM 信任存储来创建客户端信任存储。如果您的 JVM 路径不同，请相应地调整命令。
```
cp /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.201.b09-0.amzn2.x86_64/jre/lib/security/cacerts kafka.client.truststore.jks
```
1. 在客户端计算机上，运行以下命令为客户端创建私有密钥。用您选择*Your-Key-Pass*的字符串替换*Distinguished-Name**Example-Alias**Your-Store-Pass*、、和。
```
keytool -genkey -keystore kafka.client.keystore.jks -validity 300 -storepass Your-Store-Pass -keypass Your-Key-Pass -dname "CN=Distinguished-Name" -alias Example-Alias -storetype pkcs12 -keyalg rsa
```
1. 在客户端计算机上，运行以下命令以使用您在上一步中创建的私有密钥创建证书请求。
```
keytool -keystore kafka.client.keystore.jks -certreq -file client-cert-sign-request -alias Example-Alias -storepass Your-Store-Pass -keypass Your-Key-Pass
```
1. 打开 `client-cert-sign-request` 文件，并确保该文件的开头为 `-----BEGIN CERTIFICATE REQUEST-----` 且结尾为 `-----END CERTIFICATE REQUEST-----`。如果该文件的开头为 `-----BEGIN NEW CERTIFICATE REQUEST-----`，请从文件的开头和结尾处删除单词 `NEW`（及其后面的单个空格）。
1. 在已 AWS CLI 安装证书的计算机上，运行以下命令对证书请求进行签名。*Private-CA-ARN*替换为您的 PCA 的 ARN。如果需要，您可以更改有效性值。在这里，我们以 300 为例。
```
aws acm-pca issue-certificate --certificate-authority-arn Private-CA-ARN --csr fileb://client-cert-sign-request --signing-algorithm "SHA256WITHRSA" --validity Value=300,Type="DAYS"
```
保存响应中提供的证书 ARN。
**注意**
要检索您的客户端证书，请使用 `acm-pca get-certificate` 命令并指定您的证书 ARN。有关更多信息，请参阅《AWS CLI Command Reference》**中的 [get-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/acm-pca/get-certificate.html)。
1. 运行以下命令获取为您 AWS 私有 CA 签名的证书。*Certificate-ARN*替换为您从对上一个命令的响应中获得的 ARN。
```
aws acm-pca get-certificate --certificate-authority-arn Private-CA-ARN --certificate-arn Certificate-ARN
```
1. 从运行上一条命令所获得的 JSON 结果中，复制与 `Certificate` 和 `CertificateChain` 关联的字符串。将这两个字符串粘贴到名为的新文件中 signed-certificate-from-acm。先粘贴与 `Certificate` 关联的字符串，然后粘贴与 `CertificateChain` 关联的字符串。将 `\n` 字符替换为新行。以下是将证书和证书链粘贴到其中之后的文件结构。
```
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
```
1. 在客户端计算机上运行以下命令将此证书添加到您的密钥库中，以便能在与 MSK 代理交流时出示此证书。
```
keytool -keystore kafka.client.keystore.jks -import -file signed-certificate-from-acm -alias Example-Alias -storepass Your-Store-Pass -keypass Your-Key-Pass
```
1. 使用以下内容创建名为 `client.properties` 的文件。将信任存储和密钥库位置调整为您将 `kafka.client.truststore.jks` 保存到的路径。用你的 Kafka 客户端版本代替*\$1YOUR KAFKA VERSION\$1*占位符。
```
security.protocol=SSL
ssl.truststore.location=/tmp/kafka_2.12-{YOUR KAFKA VERSION}/kafka.client.truststore.jks
ssl.keystore.location=/tmp/kafka_2.12-{YOUR KAFKA VERSION}/kafka.client.keystore.jks
ssl.keystore.password=Your-Store-Pass
ssl.key.password=Your-Key-Pass
```
# 使用身份验证生成和使用消息
此过程介绍了如何使用身份验证生成和使用消息。
1. 运行以下命令以创建主题。名为 `client.properties` 的文件是您在上一过程中创建的文件。
```
/bin/kafka-topics.sh --create --bootstrap-server BootstrapBroker-String --replication-factor 3 --partitions 1 --topic ExampleTopic --command-config client.properties
```
1. 运行以下命令以启动控制台生成器。名为 `client.properties` 的文件是您在上一过程中创建的文件。
```
/bin/kafka-console-producer.sh --bootstrap-server BootstrapBroker-String --topic ExampleTopic --producer.config client.properties
```
1. 在客户端计算机上的新命令窗口中，运行以下命令以启动控制台使用器。
```
/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBroker-String --topic ExampleTopic --consumer.config client.properties
```
1. 在生成器窗口中键入消息，并观察消息显示在使用器窗口中。
# 使用 S AWS ecrets Manager 进行登录凭据身份验证
您可以使用使用 S AWS ecrets Manager 存储和保护的登录凭证来控制对您的 Amazon MSK 集群的访问权限。将用户凭证存储在 Secrets Manager 中可以减少集群身份验证的开销，例如审计、更新和轮换凭证。Secrets Manager 还让您能够跨集群共享用户凭证。
将密钥与 MSK 集群关联后，MSK 会定期同步该凭证数据。
**Topics**
+ [
# 登录凭证身份验证的工作原理
](msk-password-howitworks.md)
+ [
# 为 Amazon MSK 集群设置 SASL/SCRAM 身份验证
](msk-password-tutorial.md)
+ [
# 使用用户
](msk-password-users.md)
+ [
# 使用 SCRAM 密钥时的限制
](msk-password-limitations.md)
# 登录凭证身份验证的工作原理
Amazon MSK 的登录凭证身份验证使用的身份验证 SASL/SCRAM （简单身份验证和安全层/加盐质询响应机制）身份验证。要为集群设置登录凭证身份验证，您可以在 [AWS Secrets Manager](https://docs.aws.amazon.com//secretsmanager/?id=docs_gateway) 中创建密钥资源，并将登录凭证与该密钥关联。
SASL/SCRAM 在 [RFC 5802](https://tools.ietf.org/html/rfc5802) 中定义。SCRAM 使用安全哈希算法，不会在客户端和服务器之间传输明文登录凭证。
**注意**
当您为集群设置 SASL/SCRAM 身份验证时，Amazon MSK 会为客户端和代理之间的所有流量启用 TLS 加密。
# 为 Amazon MSK 集群设置 SASL/SCRAM 身份验证
要在 Secr AWS ets Manager 中设置密钥，请按照 Secrets Man [ager 用户指南中的[创建和检索密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)AWS 钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)教程进行操作。
在为 Amazon MSK 集群创建密钥时，请注意以下要求：
+ 对于密钥类型，请选择**其他密钥类型（例如 API 密钥）**。
+ 您的密钥名称必须以前缀 **AmazonMSK\$1** 开头。
+ 您必须使用现有的自定义 AWS KMS 密钥或为您的密 AWS KMS 钥创建新的自定义密钥。默认情况下，Secrets Manager 对密 AWS KMS 钥使用默认密钥。
**重要**
使用默认密钥创建的密 AWS KMS 钥不能用于 Amazon MSK 集群。
+ 您的登录凭证数据必须采用以下格式，才能使用**明文**选项输入键值对。
```
{
"username": "alice",
"password": "alice-secret"
}
```
+ 记录密钥的 ARN（Amazon 资源名称）值。
+
**重要**
您不能将 Secrets Manager 密钥与超出 [调整集群的大小：每个标准代理的分区数量](bestpractices.md#partitions-per-broker) 中所述限制的集群关联。
+ 如果您使用创建密钥，请为参数指定密钥 ID 或 ARN。 AWS CLI `kms-key-id`不要指定别名。
+ 要将密钥与您的集群关联，请使用 Amazon MSK 控制台或[ BatchAssociateScramSecret](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-scram-secrets.html#BatchAssociateScramSecret)操作。
**重要**
当您将密钥与集群关联时，Amazon MSK 会向该密钥附加资源策略，以允许您的集群访问和读取您定义的密钥值。您不应修改此资源策略。这样做可能会阻止您的集群访问密钥。如果对密钥资源策略和/或用于密钥加密的 KMS 密钥进行了任何更改，请确保将密钥重新关联至 MSK 集群。这可以确保集群能继续访问密钥。
`BatchAssociateScramSecret` 操作的以下 JSON 输入示例将密钥与集群关联：
```
{
"clusterArn" : "arn:aws:kafka:us-west-2:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4",
"secretArnList": [
"arn:aws:secretsmanager:us-west-2:0123456789019:secret:AmazonMSK_MyClusterSecret"
]
}
```
# 使用登录凭证连接到集群
在创建密钥并将其与集群关联后，您便可以将客户端连接到集群。以下过程演示如何将客户端连接到使用 SASL/SCRAM 身份验证的集群。此外还展示了如何通过示例主题生成和使用。
**Topics**
+ [
## 使用 SASL/SCRAM 身份验证将客户端连接到集群
](#w2aab9c13c29c17c13c11b9b7)
+ [
## 排除连接问题
](#msk-password-tutorial-connect-troubleshooting)
## 使用 SASL/SCRAM 身份验证将客户端连接到集群
1. 在已 AWS CLI 安装的计算机上运行以下命令。*clusterARN*替换为集群的 ARN。
```
aws kafka get-bootstrap-brokers --cluster-arn clusterARN
```
从该命令的 JSON 结果中，保存与名为 `BootstrapBrokerStringSaslScram` 的字符串关联的值。该值将在后面的步骤中使用。
1. 在您的客户端计算机上，创建一个 JAAS 配置文件，其中包含存储在密钥中的用户凭证。例如，对于用户 **alice**，使用以下内容创建一个名为 `users_jaas.conf` 的文件。
```
KafkaClient {
org.apache.kafka.common.security.scram.ScramLoginModule required
username="alice"
password="alice-secret";
};
```
1. 使用以下命令将 JAAS 配置文件导出为 `KAFKA_OPTS` 环境参数。
```
export KAFKA_OPTS=-Djava.security.auth.login.config=/users_jaas.conf
```
1. 在 `/tmp` 目录中创建一个名为 `kafka.client.truststore.jks` 的文件。
1. （可选）使用以下命令将 JDK 密钥存储文件从 JVM `cacerts` 文件夹复制到您在上一步中创建的 `kafka.client.truststore.jks` 文件。*JDKFolder*替换为实例上的 JDK 文件夹的名称。例如，您的 JDK 文件夹可能命名为 `java-1.8.0-openjdk-1.8.0.201.b09-0.amzn2.x86_64`。
```
cp /usr/lib/jvm/JDKFolder/lib/security/cacerts /tmp/kafka.client.truststore.jks
```
1. 在 Apache Kafka 安装的 `bin` 目录中，创建一个名为 `client_sasl.properties` 的客户端属性文件，其中包含以下内容。此文件可定义 SASL 机制和协议。
```
security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-512
```
1. 要创建示例主题，请运行以下命令。*BootstrapBrokerStringSaslScram*替换为您在本主题的步骤 1 中获得的引导代理字符串。
```
/bin/kafka-topics.sh --create --bootstrap-server BootstrapBrokerStringSaslScram --command-config /client_sasl.properties --replication-factor 3 --partitions 1 --topic ExampleTopicName
```
1. 要生成您创建的示例主题，请在客户端计算机上运行以下命令。*BootstrapBrokerStringSaslScram*替换为您在本主题的步骤 1 中检索到的引导代理字符串。
```
/bin/kafka-console-producer.sh --broker-list BootstrapBrokerStringSaslScram --topic ExampleTopicName --producer.config client_sasl.properties
```
1. 要使用您创建的主题，在您的客户端计算机上运行以下命令。*BootstrapBrokerStringSaslScram*替换为您在本主题的步骤 1 中获得的引导代理字符串。
```
/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --from-beginning --consumer.config client_sasl.properties
```
## 排除连接问题
运行 Kafka 客户端命令时，可能会遇到 Java 堆内存错误，尤其是在使用大型主题或数据集时。出现这些错误的原因是，Kafka 工具作为 Java 应用程序运行，其默认内存设置可能不足以供工作负载使用。
要解决 `Out of Memory Java Heap` 错误，可通过修改 `KAFKA_OPTS` 环境变量包含内存设置来增大 Java 堆大小。
以下示例将最大堆大小设置为 1GB (`-Xmx1G`)。此值可根据可用系统内存和要求进行调整。
```
export KAFKA_OPTS="-Djava.security.auth.login.config=/users_jaas.conf -Xmx1G"
```
要使用大型主题，可考虑使用基于时间或基于偏移量的参数（而不是 `--from-beginning`）来限制内存使用量：
```
/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --max-messages 1000 --consumer.config client_sasl.properties
```
# 使用用户
**创建用户：**您在密钥中以键值对的形式创建用户。在 Secrets Manager 控制台中使用**明文**选项时，应按以下格式指定登录凭证数据。
```
{
"username": "alice",
"password": "alice-secret"
}
```
**撤销用户访问权限：**要撤销用户访问集群的凭证，建议您先在集群上移除或强制执行 ACL，然后取消与该密钥的关联。这是因为：
+ 移除用户并不能关闭现有连接。
+ 对密钥的更改最多需要 10 分钟才能传播。
有关将 ACL 与 Amazon MSK 结合使用的更多信息，请参阅 [阿帕奇 Kafka ACLs](msk-acls.md)。
对于使用 ZooKeeper 模式的集群，我们建议您限制对 ZooKeeper 节点的访问以防止用户进行修改 ACLs。有关更多信息，请参阅 [控制对亚马逊 MSK ZooKeeper 集群中 Apache 节点的访问权限](zookeeper-security.md)。
# 使用 SCRAM 密钥时的限制
使用 SCRAM 密钥时请注意以下限制：
+ Amazon MSK 仅支持 SCRAM-SHA-512 身份验证。
+ 一个 Amazon MSK 集群最多可拥有 1000 个用户。
+ 你必须在你的密钥中 AWS KMS key 使用。您不能将使用默认 Secrets Manager 加密密钥的密钥与 Amazon MSK 一起使用。有关创建 KMS 密钥的信息，请参阅 [Creating symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)。
+ 您无法在 Secrets Manager 中使用非对称 KMS 密钥。
+ 使用该[ BatchAssociateScramSecret](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-scram-secrets.html#BatchAssociateScramSecret)操作，您一次最多可以将 10 个密钥与一个集群关联。
+ 与 Amazon MSK 集群关联的密钥的名称必须带有前缀 **AmazonMSK\$1**。
+ 与 Amazon MSK 集群关联的密钥必须与集群位于相同的 Amazon Web Services 账户和 AWS 区域中。
# 阿帕奇 Kafka ACLs
Apache Kafka 有一个可插拔的授权器，并附带了授权器实现。 out-of-boxAmazon MSK 在代理上的 `server.properties` 文件中启用此授权方。
Apache Kafka ACLs 的格式为 “主体 P 是 [允许/拒绝] 来自主机 H 对任何与 RP 匹配的资源 R 的操作 O”。 ResourcePattern 如果 RP 与特定资源 R 不匹配，则 R 没有关联 ACLs，因此除了超级用户之外，不允许任何其他人访问 R。要更改此 Apache Kafka 行为，请将该属性`allow.everyone.if.no.acl.found`设置为 true。默认情况下，Amazon MSK 会将其设置为 true。这意味着， ACLs 在 Amazon MSK 集群中，如果您没有明确设置资源，则所有委托人都可以访问此资源。如果您在资源 ACLs 上启用，则只有授权的委托人才能访问该资源。如果要限制对主题的访问并使用 TLS 双向身份验证对客户端进行授权，请 ACLs 使用 Apache Kafka 授权器 CLI 进行添加。有关添加、删除和列出的更多信息 ACLs，请参阅 [Kafka 授权命令行界面](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Authorization+Command+Line+Interface)。
由于 Amazon MSK 将代理配置为超级用户，因此代理可访问所有主题。这有助于代理从主分区复制消息，无论是否为集群配置定义了 `allow.everyone.if.no.acl.found` 属性。
**添加或删除对主题的读写访问权**
1. 将您的代理添加到 ACL 表中，以允许他们读取所有已 ACLs 存在的主题。要授予代理对主题的读取访问权限，请在可与 MSK 集群通信的客户端计算机上运行以下命令。
*Distinguished-Name*替换为集群中任何引导程序代理的 DNS，然后将此可分辨名称中第一个句点之前的字符串替换为星号 () `*`。例如，如果集群的某个引导代理有 DNS`b-6.mytestcluster.67281x.c4.kafka.us-east-1.amazonaws.com`，则在以下命令*Distinguished-Name*中替换为。`*.mytestcluster.67281x.c4.kafka.us-east-1.amazonaws.com`有关如何获取引导代理的信息，请参阅[获取 Amazon MSK 集群的引导代理](msk-get-bootstrap-brokers.md)。
```
/bin/kafka-acls.sh --bootstrap-server BootstrapServerString --add --allow-principal "User:CN=Distinguished-Name" --operation Read --group=* --topic Topic-Name
```
1. 要授予客户端应用对主题的读访问权，请在客户端计算机上运行以下命令。如果您使用双向 TLS 身份验证，请使用与创建私钥时相同的*Distinguished-Name*身份验证。
```
/bin/kafka-acls.sh --bootstrap-server BootstrapServerString --add --allow-principal "User:CN=Distinguished-Name" --operation Read --group=* --topic Topic-Name
```
要删除读访问权，您可以运行相同的命令，并将 `--add` 替换为 `--remove`。
1. 要授予对主题的写访问权，请在客户端计算机上运行以下命令。如果您使用双向 TLS 身份验证，请使用与创建私钥时相同的*Distinguished-Name*身份验证。
```
/bin/kafka-acls.sh --bootstrap-server BootstrapServerString --add --allow-principal "User:CN=Distinguished-Name" --operation Write --topic Topic-Name
```
要删除写访问权，您可以运行相同的命令，并将 `--add` 替换为 `--remove`。
# 更改 Amazon MSK 集群的安全组
本页介绍如何更改现有 MSK 集群的安全组。您可能需要更改集群的安全组，以便为特定用户组提供访问权限或限制对集群的访问权限。有关安全组的信息，请参阅《Amazon VPC 用户指南》中的[您的 VPC 的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。
1. 使用中的 [ListNodes](https://docs.amazonaws.cn/en_us/msk/1.0/apireference/clusters-clusterarn-nodes.html#ListNodes)API 或 [list-nodes](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/list-nodes.html) 命令获取集群中代理的列表。 AWS CLI 此操作的结果包括与代理关联 IDs 的弹性网络接口 (ENIs)。
1. 登录 AWS 管理控制台 并打开 Amazon EC2 控制台，网址为[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 使用屏幕右上角附近的下拉列表，选择部署集群的区域。
1. 在左侧窗格的**网络与安全**下，选择**网络接口**。
1. 选择您在第一步中获得的第一个 ENI。选择屏幕顶部的**操作**菜单，然后选择**更改安全组**。将新的安全组分配给此 ENI。对您在第一步中获得 ENIs 的每个内容重复此步骤。
**注意**
您使用 Amazon EC2 控制台对集群安全组所做的更改，不会反映在 MSK 控制台的**网络设置**下。
1. 配置新安全组的规则，确保您的客户端可以访问代理。有关设置安全组规则的信息，请参阅《Amazon VPC 用户指南》中的[添加、删除和更新规则](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html?shortFooter=true#AddRemoveRules)。
**重要**
如果您更改与集群代理关联的安全组，然后向该集群添加新的代理，Amazon MSK 会将新代理与创建集群时与该集群关联的原始安全组关联。但是，要使集群正常运行，其所有代理都必须与同一个安全组关联。因此，如果您在更改安全组后添加新代理，则必须再次执行前面的步骤并更新新代理 ENIs 的代理。
# 控制对亚马逊 MSK ZooKeeper 集群中 Apache 节点的访问权限
出于安全考虑，您可以限制对属于您的 Amazon MSK ZooKeeper 集群的 Apache 节点的访问权限。要限制对节点的访问，您可以为节点分配单独的安全组。然后，您可以决定有权访问该安全组的人员。
**重要**
本节不适用于在 KRaft 模式下运行的集群。请参阅[KRaft 模式](metadata-management.md#kraft-intro)。
**Topics**
+ [
# 将 Apache ZooKeeper 节点放在单独的安全组中
](zookeeper-security-group.md)
+ [
# 在 Apache 中使用 TLS 安全性 ZooKeeper
](zookeeper-security-tls.md)
# 将 Apache ZooKeeper 节点放在单独的安全组中
要限制对 Apache ZooKeeper 节点的访问，您可以为其分配单独的安全组。您可以通过设置安全组规则来选择谁有权访问此新安全组。
1. 获取您的集群的 Apache ZooKeeper 连接字符串。要了解如何操作，请参阅[ZooKeeper 模式](metadata-management.md#msk-get-connection-string)。连接字符串包含您的 Apache ZooKeeper 节点的 DNS 名称。
1. 使用 `host` 或 `ping` 等工具将您在上一步中获得的 DNS 名称转换为 IP 地址。稍后您需要在此过程中使用这些 IP 地址，因此请保存这些地址。
1. 登录 AWS 管理控制台 并打开 Amazon EC2 控制台，网址为[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 在左侧窗格的 **Network & Security (网络与安全性)** 下，选择 **Network Interfaces (网络接口)**。
1. 在网络接口表上方的搜索字段中，键入集群名称，然后键入 return。这会将表中显示的网络接口数限制为与您的集群关联的接口。
1. 选中与列表中的第一个网络接口对应的行开头处的复选框。
1. 在页面底部的详细信息窗格中，查找**主私 IPv4 有 IP**。如果此 IP 地址与您在本过程第一步中获得的 IP 地址相匹配，则表示该网络接口已分配给集群中的一个 Apache ZooKeeper 节点。否则，取消选中此网络接口旁边的复选框，然后选择列表中的下一个网络接口。选择网络接口的顺序无关紧要。在接下来的步骤中，您将对分配给 Apache ZooKeeper 节点的所有网络接口逐一执行相同的操作。
1. 当您选择与 Apache ZooKeeper 节点对应的网络接口时，请选择页面顶部的**操作**菜单，然后选择**更改安全组**。将新安全组分配给此网络接口。有关创建安全组的信息，请参阅 Amazon VPC 文档中的[创建安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html?shortFooter=true#CreatingSecurityGroups)。
1. 重复上一步为与集群的 Apache ZooKeeper 节点关联的所有网络接口分配相同的新安全组。
1. 现在，您可以选择有权访问此新安全组的人员。有关设置安全组规则的信息，请参阅 Amazon VPC 文档中的[添加、删除和更新规则](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html?shortFooter=true#AddRemoveRules)。
# 在 Apache 中使用 TLS 安全性 ZooKeeper
您可以使用 TLS 安全性在客户端和 Apache ZooKeeper 节点之间传输时进行加密。要在 Apache ZooKeeper 节点上实现 TLS 安全，请执行以下操作：
+ 集群必须使用 Apache Kafka 版本 2.5.1 或更高版本才能在 Apache 中使用 TLS 安全性。 ZooKeeper
+ 在创建或配置集群时启用 TLS 安全。使用 Apache Kafka 版本 2.5.1 或更高版本创建并启用 TLS 的集群会自动对 Apache 终端节点使用 TLS 安全性。 ZooKeeper 有关设置 TLS 安全的信息，请参阅[Amazon MSK 加密入门](msk-working-with-encryption.md)。
+ 使用[DescribeCluster ](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)操作检索 TLS Apache ZooKeeper 端点。
+ 创建 Apache ZooKeeper 配置文件，以便与`kafka-configs.sh`和[https://kafka.apache.org/documentation/#security_authz_cli](https://kafka.apache.org/documentation/#security_authz_cli)工具或 ZooKeeper 外壳一起使用。对于每个工具，您都使用`--zk-tls-config-file`参数来指定 Apache ZooKeeper 配置。
以下示例显示了一个典型的 Apache ZooKeeper 配置文件：
```
zookeeper.ssl.client.enable=true
zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
zookeeper.ssl.keystore.location=kafka.jks
zookeeper.ssl.keystore.password=test1234
zookeeper.ssl.truststore.location=truststore.jks
zookeeper.ssl.truststore.password=test1234
```
+ 对于其他命令（例如`kafka-topics`），必须使用`KAFKA_OPTS`环境变量来配置 Apache ZooKeeper 参数。以下示例说明如何配置`KAFKA_OPTS`环境变量以将 Apache ZooKeeper 参数传递给其他命令：
```
export KAFKA_OPTS="
-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
-Dzookeeper.client.secure=true
-Dzookeeper.ssl.trustStore.location=/home/ec2-user/kafka.client.truststore.jks
-Dzookeeper.ssl.trustStore.password=changeit"
```
配置 `KAFKA_OPTS` 环境变量后，您便可正常使用 CLI 命令。以下示例使用环境变量中的 Apache ZooKeeper 配置创建 Apache Kafka 主题：`KAFKA_OPTS`
```
/bin/kafka-topics.sh --create --zookeeper ZooKeeperTLSConnectString --replication-factor 3 --partitions 1 --topic AWSKafkaTutorialTopic
```
**注意**
您在 Apache ZooKeeper 配置文件中使用的参数名称与您在`KAFKA_OPTS`环境变量中使用的参数名称不一致。注意在配置文件和 `KAFKA_OPTS` 环境变量中与参数一起使用的名称。
有关使用 TLS 访问您的 Apache ZooKeeper 节点的更多信息，请参阅 [KIP-515：启用 ZK 客户端使用新的 TLS 支持的身份验证](https://cwiki.apache.org/confluence/display/KAFKA/KIP-515%3A+Enable+ZK+client+to+use+the+new+TLS+supported+authentication)。
# Amazon Managed Streaming for Apache Kafka 的合规性验证
作为 AWS 合规性计划的一部分，第三方审计员将评估 Amazon Managed Streaming for Apache Kafka 的安全性与合规性。其中包括 PCI 和 HIPAA BAA。
有关特定合规计划范围内的 AWS 服务列表，请参阅[按合规计划提供的范围内的亚马逊服务 Amazon Web Ser](https://aws.amazon.com/compliance/services-in-scope/) 。有关一般信息，请参阅[AWS 合规计划AWS](https://aws.amazon.com/compliance/programs/)。
您可以使用下载第三方审计报告 AWS Artifact。有关更多信息，请参阅中的 “[下载报告” 中的 “ AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)。
您在使用 Amazon MSK 时的合规责任取决于您的数据的敏感性、贵公司的合规目标以及适用的法律和法规。 AWS 提供了以下资源来帮助实现合规性：
+ [安全性与合规性快速入门指南](https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) - 这些部署指南讨论了架构注意事项，并提供了在 AWS上部署基于安全性和合规性的基准环境的步骤。
+ [HIPAA 安全与合规架构白皮书 — 本白皮书](https://docs.aws.amazon.com/whitepapers/latest/architecting-hipaa-security-and-compliance-on-aws/architecting-hipaa-security-and-compliance-on-aws.html)描述了公司如何使用来 AWS 创建符合 HIPAA 标准的应用程序。
+ [AWS 合规资源AWS](https://aws.amazon.com/compliance/resources/) — 此工作簿和指南集可能适用于您所在的行业和所在地区。
+ [使用*AWS Config 开发人员指南*中的规则评估资源](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) — 该 AWS Config 服务评估您的资源配置在多大程度上符合内部实践、行业准则和法规。
+ [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html)— 此 AWS 服务可全面了解您的安全状态 AWS ，帮助您检查是否符合安全行业标准和最佳实践。
# Amazon Managed Streaming for Apache Kafka 中的恢复能力
AWS 全球基础设施是围绕 AWS 区域和可用区构建的。 AWS 区域提供多个物理隔离和隔离的可用区，这些可用区通过低延迟、高吞吐量和高度冗余的网络相连。利用可用区，您可以设计和操作在可用区之间无中断地自动实现失效转移的应用程序和数据库。与传统的单个或多个数据中心基础设施相比，可用区具有更高的可用性、容错能力和可扩展性。
有关 AWS 区域和可用区的更多信息，请参阅[AWS 全球基础设施](https://aws.amazon.com/about-aws/global-infrastructure/)。
# Amazon Managed Streaming for Apache Kafka 中的基础设施安全性
作为一项托管服务，适用于 Apache Kafka 的亚马逊托管流媒体受到 AWS 《[亚马逊网络服务：安全流程概述》白皮书中描述的全球网络安全程序的](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf)保护。
您可以使用 AWS 已发布的 API 调用通过网络访问 Amazon MSK。客户端必须支持传输层安全性协议（TLS）1.0 或更高版本。建议使用 TLS 1.2 或更高版本。客户端还必须支持具有完全向前保密（PFS）的密码套件，例如 Ephemeral Diffie-Hellman（DHE）或 Elliptic Curve Ephemeral Diffie-Hellman（ECDHE）。大多数现代系统（如 Java 7 及更高版本）都支持这些模式。
此外，必须使用访问密钥 ID 和与 IAM 主体关联的秘密访问密钥来对请求进行签名。或者，您可以使用 [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html)（AWS STS）生成临时安全凭证来对请求进行签名。
# Amazon MSK 日志记录
您可以将 Apache Kafka 代理日志传送到以下一种或多种目标类型：亚马逊日 CloudWatch 志、亚马逊 S3、Amazon Data Firehose。您也可以使用记录亚马逊 MSK API 调用。 AWS CloudTrail
**注意**
MSK 标准和快递经纪商均提供经纪人日志。
## 代理日志
利用代理日志，您可以对 Apache Kafka 应用程序进行问题排查，并分析它们与 MSK 集群的通信。您可以将新的或现有 MSK 集群配置为将信息级别的代理日志传送到以下一种或多种目标资源： CloudWatch 日志组、S3 存储桶、Firehose 传输流。然后，您可以通过 Firehose 将传输流中的日志数据传送到 OpenSearch 服务。
在配置集群以向其传送代理日志之前，必须创建目标资源。如果尚不存在这些目标资源，Amazon MSK 也不会为您创建。有关这三种类型的目标资源以及如何创建这些资源的信息，请参阅以下文档：
+ [Amazon CloudWatch 日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)
+ [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html)
+ [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html)
### 所需的权限
要为 Amazon MSK 代理日志配置目标，您用于 Amazon MSK 操作的 IAM 身份必须具有 [AWS 托管策略：Amazon A MSKFull ccess](security-iam-awsmanpol-AmazonMSKFullAccess.md) 策略中所述的权限。
要将代理日志流式传输到 S3 存储桶，您还需要 `s3:PutBucketPolicy` 权限。有关 S3 存储桶策略的信息，请参阅《Amazon S3 用户指南》中的[如何添加 S3 存储桶策略？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-bucket-policy.html)。有关 IAM 策略的一般信息，请参阅《IAM 用户指南》中的[访问管理](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html)。
### 与 SSE-KMS 存储桶结合使用时必需的 KMS 密钥政策
如果您使用带有客户托管密钥的 AWS KMS托管密钥 (SSE-KMS) 为 S3 存储桶启用了服务器端加密，请将以下内容添加到您的 KMS 密钥的密钥策略中，以便 Amazon MSK 可以将代理文件写入存储桶。
```
{
"Sid": "Allow Amazon MSK to use the key.",
"Effect": "Allow",
"Principal": {
"Service": [
"delivery.logs.amazonaws.com"
]
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*"
}
```
### 使用配置代理日志 AWS 管理控制台
如果您要创建新集群，请在**监控**部分中查找**代理日志传送**标题。您可以指定希望 Amazon MSK 向其传送代理日志的目标。
对于现有集群，请从集群列表中选择集群，然后选择**属性**选项卡。向下滚动到**日志传送**部分，然后选择其**编辑**按钮。您可以指定希望 Amazon MSK 向其传送代理日志的目标。
### 使用配置代理日志 AWS CLI
使用 `create-cluster` 或 `update-monitoring` 命令时，您可以选择指定 `logging-info` 参数并将类似如下的 JSON 结构传递给该参数。在此 JSON 中，所有三种目标类型都是可选的。
**注意**
要设置日志传输，必须在 Firehose 流上将 `LogDeliveryEnabled` 标签设置为 `true`。为 CloudWatch 日志 AWS 创建的服务相关角色使用此标签来授予所有 Firehose 传输流的权限。如果移除此标签，服务相关角色将无法向 Firehose 流传送日志。要查看显示服务相关角色所包含权限的 IAM 策略示例，请参阅 [A *mazon CloudWatch 用户指南*中用于资源权限的 IAM 角色](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-infrastructure-V2-Firehose.html)。
```
{
"BrokerLogs": {
"S3": {
"Bucket": "amzn-s3-demo-bucket",
"Prefix": "ExamplePrefix",
"Enabled": true
},
"Firehose": {
"DeliveryStream": "ExampleDeliveryStreamName",
"Enabled": true
},
"CloudWatchLogs": {
"Enabled": true,
"LogGroup": "ExampleLogGroupName"
}
}
}
```
### 使用 API 配置代理日志
您可以在 JSON 中指定传递给[CreateCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters.html#CreateCluster)或[UpdateMonitoring](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-monitoring.html#UpdateMonitoring)操作的可选`loggingInfo`结构。
**注意**
默认情况下，启用代理日志记录后，Amazon MSK 会将 `INFO` 级别日志记录到指定目标。[但是，对于标准代理，Apache Kafka 2.4.X 及更高版本的用户可以将代理日志级别动态设置为任何 log4j 日志级别。](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html)有关动态设置代理日志级别的信息，请参阅 [KIP-412: Extend Admin API to support dynamic application log levels](https://cwiki.apache.org/confluence/display/KAFKA/KIP-412%3A+Extend+Admin+API+to+support+dynamic+application+log+levels)。如果您将日志级别动态设置为 `DEBUG` 或 `TRACE`，我们建议使用 Amazon S3 或 Firehose 作为日志目标。如果您使用 CloudWatch 日志作为日志目标，并且动态启用`DEBUG`或`TRACE`级别日志记录，Amazon MSK 可能会持续提供日志样本。这可能会对代理性能带来显著影响，因此只有在 `INFO` 日志级别不够详细，无法确定问题的根本原因时才应使用。
# 使用记录 API 调用 AWS CloudTrail
**注意**
AWS CloudTrail 只有在您使用[IAM 访问控制](iam-access-control.md)时，日志才可用于 Amazon MSK。
Amazon MSK 与 AWS CloudTrail一项服务集成，该服务提供用户、角色或 AWS 服务在 Amazon MSK 中采取的操作的记录。 CloudTrail 将发出的 API 调用捕获为事件。捕获的调用包含来自 Amazon MSK 控制台的调用以及对 Amazon MSK API 操作的代码调用。它还会捕获 Apache Kafka 操作，例如创建和更改主题与组。
如果您创建了跟踪，则可以允许将 CloudTrail 事件持续传输到 Amazon S3 存储桶，包括 Amazon MSK 的事件。如果您未配置跟踪，您仍然可以在 CloudTrail 控制台的 “事件**历史记录” 中查看最新的事件**。使用收集的信息 CloudTrail，您可以确定向 Amazon MSK 或 Apache Kafka 操作发出的请求、发出请求的 IP 地址、谁发出了请求、何时发出请求以及其他详细信息。
要了解更多信息 CloudTrail，包括如何配置和启用它，请参阅《[AWS CloudTrail 用户指南》](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## 亚马逊 MSK 信息位于 CloudTrail
CloudTrail 在您创建账户时，您的亚马逊 Web Services 账户已启用。当 MSK 集群中出现支持的事件活动时，该活动会与其他 AWS 服务 CloudTrail 事件一起记录在**事件历史**记录中。您可以在 Amazon Web Services 账户中查看、搜索和下载最新事件。有关更多信息，请参阅[使用 CloudTrail 事件历史记录查看事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)。
要持续记录 Amazon Web Services 账户中的事件（包括 Amazon MSK 的事件），请创建跟踪。*跟踪*允许 CloudTrail 将日志文件传输到 Amazon S3 存储桶。预设情况下，在控制台中创建跟踪时，此跟踪应用于所有 区域。此跟踪记录在 AWS 分区中记录所有区域中的事件，并将日志文件传送至您指定的 Amazon S3 存储桶。此外，您可以配置其他 Amazon 服务，以进一步分析和处理 CloudTrail 日志中收集的事件数据。有关更多信息，请参阅下列内容：
+ [创建跟踪概述](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 支持的服务和集成](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [配置 Amazon SNS 通知 CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [接收来自多个区域的 CloudTrail 日志文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html)和[接收来自多个账户的 CloudTrail 日志文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
Amazon MSK 将所有 [Amazon MSK 操作](https://docs.aws.amazon.com/MSK/2.0/APIReference/operations.html)作为事件 CloudTrail 记录在日志文件中。此外，它还会记录以下 Apache Kafka 操作。
+ kafka 集群：DescribeClusterDynamicConfiguration
+ kafka 集群：AlterClusterDynamicConfiguration
+ kafka 集群：CreateTopic
+ kafka 集群：DescribeTopicDynamicConfiguration
+ kafka 集群：AlterTopic
+ kafka 集群：AlterTopicDynamicConfiguration
+ kafka 集群：DeleteTopic
每个事件或日志条目都包含有关生成请求的人员信息。身份信息有助于您确定以下内容：
+ 请求是使用根用户还是 AWS Identity and Access Management (IAM) 用户凭证发出。
+ 请求是使用角色还是联合用户的临时安全凭证发出的。
+ 请求是否由其他 AWS 服务发出。
有关更多信息，请参阅 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
## 示例：Amazon MSK 日志文件条目
跟踪是一种配置，允许将事件作为日志文件传输到您指定的 Amazon S3 存储桶。 CloudTrail 日志文件包含一个或多个日志条目。事件代表来自任何来源的单个请求，包括有关请求的操作、操作的日期和时间、请求参数等的信息。 CloudTrail 日志文件不是公共 API 调用和 Apache Kafka 操作的有序堆栈跟踪，因此它们不会按任何特定的顺序出现。
以下示例显示了演示`DescribeCluster`和 `DeleteCluster` Amazon MSK 操作的 CloudTrail 日志条目。
```
{
"Records": [
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDEF0123456789ABCDE",
"arn": "arn:aws:iam::012345678901:user/Joe",
"accountId": "012345678901",
"accessKeyId": "AIDACKCEVSQ6C2EXAMPLE",
"userName": "Joe"
},
"eventTime": "2018-12-12T02:29:24Z",
"eventSource": "kafka.amazonaws.com",
"eventName": "DescribeCluster",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.14.67 Python/3.6.0 Windows/10 botocore/1.9.20",
"requestParameters": {
"clusterArn": "arn%3Aaws%3Akafka%3Aus-east-1%3A012345678901%3Acluster%2Fexamplecluster%2F01234567-abcd-0123-abcd-abcd0123efa-2"
},
"responseElements": null,
"requestID": "bd83f636-fdb5-abcd-0123-157e2fbf2bde",
"eventID": "60052aba-0123-4511-bcde-3e18dbd42aa4",
"readOnly": true,
"eventType": "AwsApiCall",
"recipientAccountId": "012345678901"
},
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDEF0123456789ABCDE",
"arn": "arn:aws:iam::012345678901:user/Joe",
"accountId": "012345678901",
"accessKeyId": "AIDACKCEVSQ6C2EXAMPLE",
"userName": "Joe"
},
"eventTime": "2018-12-12T02:29:40Z",
"eventSource": "kafka.amazonaws.com",
"eventName": "DeleteCluster",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.14.67 Python/3.6.0 Windows/10 botocore/1.9.20",
"requestParameters": {
"clusterArn": "arn%3Aaws%3Akafka%3Aus-east-1%3A012345678901%3Acluster%2Fexamplecluster%2F01234567-abcd-0123-abcd-abcd0123efa-2"
},
"responseElements": {
"clusterArn": "arn:aws:kafka:us-east-1:012345678901:cluster/examplecluster/01234567-abcd-0123-abcd-abcd0123efa-2",
"state": "DELETING"
},
"requestID": "c6bfb3f7-abcd-0123-afa5-293519897703",
"eventID": "8a7f1fcf-0123-abcd-9bdb-1ebf0663a75c",
"readOnly": false,
"eventType": "AwsApiCall",
"recipientAccountId": "012345678901"
}
]
}
```
以下示例显示了演示该`kafka-cluster:CreateTopic`操作的 CloudTrail 日志条目。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDEFGH1IJKLMN2P34Q5",
"arn": "arn:aws:iam::111122223333:user/Admin",
"accountId": "111122223333",
"accessKeyId": "CDEFAB1C2UUUUU3AB4TT",
"userName": "Admin"
},
"eventTime": "2021-03-01T12:51:19Z",
"eventSource": "kafka-cluster.amazonaws.com",
"eventName": "CreateTopic",
"awsRegion": "us-east-1",
"sourceIPAddress": "198.51.100.0/24",
"userAgent": "aws-msk-iam-auth/unknown-version/aws-internal/3 aws-sdk-java/1.11.970 Linux/4.14.214-160.339.amzn2.x86_64 OpenJDK_64-Bit_Server_VM/25.272-b10 java/1.8.0_272 scala/2.12.8 vendor/Red_Hat,_Inc.",
"requestParameters": {
"kafkaAPI": "CreateTopics",
"resourceARN": "arn:aws:kafka:us-east-1:111122223333:topic/IamAuthCluster/3ebafd8e-dae9-440d-85db-4ef52679674d-1/Topic9"
},
"responseElements": null,
"requestID": "e7c5e49f-6aac-4c9a-a1d1-c2c46599f5e4",
"eventID": "be1f93fd-4f14-4634-ab02-b5a79cb833d2",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"eventCategory": "Management",
"recipientAccountId": "111122223333"
}
```
# 元数据管理
亚马逊 MSK 支持 Apache ZooKeeper 或 KRaft 元数据管理模式。
在 Amazon MSK 上的 Apache Kafka 3.7.x 版本中，你可以创建 KRaft 使用模式而不是模式的集群。 ZooKeeper KRaft基于 Kafka 的集群依赖 Kafka 中的控制器来管理元数据。
**Topics**
+ [
## ZooKeeper 模式
](#msk-get-connection-string)
+ [
## KRaft 模式
](#kraft-intro)
## ZooKeeper 模式
[Apache ZooKeeper](https://zookeeper.apache.org/) 是 “一项集中式服务，用于维护配置信息、命名、提供分布式同步和提供群组服务。分布式应用程序以某种形式使用所有这些类型的服务”，包括 Apache Kafka。
如果您的集群正在使用 ZooKeeper 模式，则可以使用以下步骤获取 Apache ZooKeeper 连接字符串。但是，我们建议您使用 `BootstrapServerString` 连接到您的集群并执行管理员操作，因为 `--zookeeper` 标志已在 Kafka 2.5 中被弃用，并已从 Kafka 3.0 中移除。
### 使用获取 Apache ZooKeeper 连接字符串 AWS 管理控制台
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 该表显示了此账户下当前区域的所有集群。选择集群名称以查看其说明。
1. 在**集群摘要**页面上，选择**查看客户端信息**。这显示了引导程序代理以及 Apache ZooKeeper 连接字符串。
### 使用获取 Apache ZooKeeper 连接字符串 AWS CLI
1. 如果您不知道集群的 Amazon 资源名称 (ARN)，您可以通过列出您账户中的所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
1. 要获取 Apache ZooKeeper 连接字符串以及有关集群的其他信息，请运行以下命令，*ClusterArn*替换为集群的 ARN。
```
aws kafka describe-cluster --cluster-arn ClusterArn
```
该 `describe-cluster` 命令的输出如以下 JSON 示例所示。
```
{
"ClusterInfo": {
"BrokerNodeGroupInfo": {
"BrokerAZDistribution": "DEFAULT",
"ClientSubnets": [
"subnet-0123456789abcdef0",
"subnet-2468013579abcdef1",
"subnet-1357902468abcdef2"
],
"InstanceType": "kafka.m5.large",
"StorageInfo": {
"EbsStorageInfo": {
"VolumeSize": 1000
}
}
},
"ClusterArn": "arn:aws:kafka:us-east-1:111122223333:cluster/testcluster/12345678-abcd-4567-2345-abcdef123456-2",
"ClusterName": "testcluster",
"CreationTime": "2018-12-02T17:38:36.75Z",
"CurrentBrokerSoftwareInfo": {
"KafkaVersion": "2.2.1"
},
"CurrentVersion": "K13V1IB3VIYZZH",
"EncryptionInfo": {
"EncryptionAtRest": {
"DataVolumeKMSKeyId": "arn:aws:kms:us-east-1:555555555555:key/12345678-abcd-2345-ef01-abcdef123456"
}
},
"EnhancedMonitoring": "DEFAULT",
"NumberOfBrokerNodes": 3,
"State": "ACTIVE",
"ZookeeperConnectString": "10.0.1.101:2018,10.0.2.101:2018,10.0.3.101:2018"
}
}
```
上一 JSON 示例在 `describe-cluster` 命令输出中显示 `ZookeeperConnectString` 键。复制与此键对应的值，并保存它以用于在集群上创建主题。
**重要**
您的 Amazon MSK 集群必须处于`ACTIVE`状态才能获取 Apache ZooKeeper 连接字符串。当集群仍处于 `CREATING` 状态时，`describe-cluster` 命令的输出不包含 `ZookeeperConnectString`。如果发生这种情况，请等待几分钟，然后在集群进入 `ACTIVE` 状态后再次运行 `describe-cluster`。
### 使用 API 获取 Apache ZooKeeper 连接字符串
要使用 API 获取 Apache ZooKeeper 连接字符串，请参阅[DescribeCluster](https://docs.aws.amazon.com//msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)。
## KRaft 模式
亚马逊 MSK 在 Kafka 版本 3.7.x 中引入了对 KRaft （Apache Kafka Raft）的支持。Apache Kafka 社区旨在 KRaft 取代 Apache 在 [Apache](#msk-get-connection-string) Kafka 集群中 ZooKeeper进行元数据管理。在 KRaft 模式下，集群元数据在一组 Kafka 控制器中传播，这些控制器是 Kafka 集群的一部分，而不是跨节点传播。 ZooKeeper KRaft控制器包含在内，您无需支付任何额外费用，也不需要您进行额外的设置或管理。有关更多信息，请参阅 [KIP-500](https://cwiki.apache.org/confluence/display/KAFKA/KIP-500%3A+Replace+ZooKeeper+with+a+Self-Managed+Metadata+Quorum) KRaft。
以下是有关 MSK KRaft 模式的一些注意事项：
+ KRaft 模式仅适用于新集群。创建集群后，无法切换元数据模式。
+ 在 MSK 控制台上，您可以通过选择 Kafka 版本 3.7.x 并选中集群创建窗口中的 KRaft 复选框来创建基于 Kraft 的集群。
+ 要使用 MSK API [https://docs.aws.amazon.com/msk/1.0/apireference/clusters.html#CreateCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters.html#CreateCluster)或[https://docs.aws.amazon.com/MSK/2.0/APIReference/v2-clusters.html#CreateClusterV2](https://docs.aws.amazon.com/MSK/2.0/APIReference/v2-clusters.html#CreateClusterV2)操作在 KRaft 模式下创建集群，应使用`3.7.x.kraft`作为版本。`3.7.x`用作在 ZooKeeper 模式下创建集群的版本。
+ ZooKeeper 基于 KRaft 和基于群集的每个代理的分区数相同。但是，通过在集群中配置更多代理， KRaft 允许您在每个集群[中托管更多](https://docs.aws.amazon.com/msk/latest/developerguide/limits.html)分区。
+ 在 Amazon MSK 上使用 KRaft 模式无需更改 API。但是，如果您的客户端今天仍在使用 `--zookeeper` 连接字符串，则应更新您的客户端，以使用 `--bootstrap-server` 连接字符串连接到您的集群。`--zookeeper` 标志在 Apache Kafka 2.5 版中已弃用，并从 Kafka 3.0 版开始移除。因此，我们建议您对与集群的所有连接使用最新的 Apache Kafka 客户端版本和 `--bootstrap-server` 连接字符串。
+ ZooKeeper 模式继续适用于所有已发布的版本，其中 Apache Kafka 也支持 zookeeper。有关 Apache Kafka 版本终止支持和未来更新的详细信息，请参阅[支持的 Apache Kafka 版本](supported-kafka-versions.md)。
+ 你应该检查你使用的任何工具是否能够在 APIs 没有 ZooKeeper 连接的情况下使用 Kafka Admin。有关将集群连接到 Cruise Control 的更新步骤，请参阅 [在 Amazon LinkedIn MSK 上使用 Apache Kafka 的巡航控制系统](cruise-control.md)。Cruise Control 还提供了[不带巡航控制系统的运行](https://github.com/linkedin/cruise-control/wiki/Run-without-ZooKeeper)说明 ZooKeeper。
+ 您无需直接访问集群的 KRaft 控制器即可执行任何管理操作。但是，如果使用开放监控来收集指标，您还需要控制器的 DNS 端点来收集有关集群的一些非控制器相关指标。您可以从 MSK 控制台或使用 [ListNodes](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-nodes.html#ListNodes)API 操作获取这些 DNS 终端节点。有关[使用 Prometheus 监控预置 MSK 集群](open-monitoring.md)为 KRaft基于群集设置开放监控的更新步骤，请参阅。
+ 对于 KRaft 模式集群而不是 ZooKeeper 模式集群，您无需监控其他[CloudWatch 指标](https://docs.aws.amazon.com/msk/latest/developerguide/metrics-details.html)。MSK 管理您的集群中使用的 KRaft 控制器。
+ 您可以使用`--bootstrap-server`连接字符串在 KRaft 模式下 ACLs 使用集群继续进行管理。不应使用`--zookeeper`连接字符串进行管理 ACLs。请参阅[阿帕奇 Kafka ACLs](msk-acls.md)。
+ 在 KRaft 模式下，集群的元数据存储在 Kafka 中的 KRaft 控制器上，而不是外部 ZooKeeper 节点上。因此，您无需像控制节点那[样单独控制对控制器 ZooKeeper 节点的](https://docs.aws.amazon.com/msk/latest/developerguide/zookeeper-security.html)访问。
# 主题操作
您可以使用 Amazon MSK APIs 管理您的 MSK 预配置集群中的主题，而无需设置和维护 Kafka 管理员客户端。有了这些 APIs，您可以定义或读取主题属性，例如复制因子和分区计数，以及保留和清理策略等配置设置。您可以使用熟悉的界面（包括 CL AWS I、 AWS SDKs和）以编程方式管理 Kafka 主题。 AWS CloudFormation APIs 它们还集成到 Amazon MSK 控制台中，将所有主题操作集中到一个地方。现在，您只需点击几下即可使用引导式默认设置创建或更新主题，同时全面了解主题配置、分区级信息和指标。
**重要**
这些主题 API 响应反映的数据大约每分钟更新一次。要了解更改后的最新主题状态，请在查询前等待大约一分钟。
## 使用主题的要求 APIs
+ 您的集群必须是 MSK 预配置的集群。 APIs 这些不适用于 MSK 无服务器集群。
+ 您的集群必须运行 Apache Kafka 版本 3.6.0 或更高版本。有关支持的版本的更多信息，请参阅[支持的 Apache Kafka 版本](supported-kafka-versions.md)。
+ 您的集群必须处于`ACTIVE`状态。有关集群状态的更多信息，请参阅[了解预置 MSK 集群状态](msk-cluster-states.md)。
+ 您必须拥有相应的 IAM 权限。有关更多信息，请参阅 [用于主题操作的 IAM 权限 APIs](#topic-operations-permissions)。
## 用于主题操作的 IAM 权限 APIs
要调用它们 APIs，您必须拥有相应的 IAM 权限。下表列出了每个 API 所需的权限。
**主题操作所需的权限 APIs**
| API | 所需权限 | 资源 |
| --- | --- | --- |
| ListTopics | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | 集群 ARN，主题 ARN |
| DescribeTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DescribeTopicDynamicConfiguration` | 集群 ARN，主题 ARN |
| DescribeTopicPartitions | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DescribeTopicDynamicConfiguration` | 集群 ARN，主题 ARN |
| CreateTopic | `kafka-cluster:Connect` `kafka-cluster:CreateTopic` | 集群 ARN，主题 ARN |
| DeleteTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DeleteTopic` | 集群 ARN，主题 ARN |
| UpdateTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:AlterTopic` `kafka-cluster:AlterTopicDynamicConfiguration` | 集群 ARN，主题 ARN |
**注意**
对于`kafka-cluster:Connect`，请在您的 IAM 策略中指定集群 ARN。对于所有其他操作，请在您的 IAM 策略中指定主题 ARN。
**注意**
对于`ListTopics`，您可以使用通配符 (\$1) 来匹配集群上的所有主题。例如：`arn:aws:kafka:us-east-1:123456789012:topic/my-cluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/*`。
有关适用于 Amazon MSK 的 IAM 访问控制的更多信息，请参阅[IAM 访问控制](iam-access-control.md)。
**Topics**
+ [
## 使用主题的要求 APIs
](#topic-operations-requirements)
+ [
## 用于主题操作的 IAM 权限 APIs
](#topic-operations-permissions)
+ [
# 在 Amazon MSK 集群中列出主题
](msk-list-topics.md)
+ [
# 获取有关某个主题的详细信息
](msk-describe-topic.md)
+ [
# 查看主题的分区信息
](msk-describe-topic-partitions.md)
+ [
# 在 Amazon MSK 集群中创建主题
](msk-create-topic.md)
+ [
# 更新 Amazon MSK 集群中的主题
](msk-update-topic.md)
+ [
# 删除 Amazon MSK 集群中的主题
](msk-delete-topic.md)
# 在 Amazon MSK 集群中列出主题
您可以列出 MSK Provisioned 集群中的所有主题，以查看基本元数据，例如分区计数和复制因子。这对于监控集群的主题、执行库存检查或确定需要进一步调查的主题非常有用。
**注意**
`ListTopics`API 提供基本的主题元数据。要获取有关特定主题的详细信息，包括其当前状态和配置，请使用 `DescribeTopic` API。有关更多信息，请参阅 [获取有关某个主题的详细信息](msk-describe-topic.md)。
**注意**
此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。
**Topics**
+ [
# 使用列出主题 AWS 管理控制台
](list-topics-console.md)
+ [
# 使用列出主题 AWS CLI
](list-topics-cli.md)
+ [
# 使用 API 列出主题
](list-topics-api.md)
# 使用列出主题 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择要列出其主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 该表显示了集群中的所有主题，包括主题名称、分区数、重复因子和 out-of-sync副本数。
# 使用列出主题 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN)。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
```
aws kafka list-topics --cluster-arn ClusterArn
```
该 命令的输出如以下 JSON 示例所示。
```
{
"topics": [
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic",
"topicName": "MyTopic",
"partitionCount": 3,
"replicationFactor": 3,
"outOfSyncReplicaCount": 0
},
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/AnotherTopic",
"topicName": "AnotherTopic",
"partitionCount": 6,
"replicationFactor": 3,
"outOfSyncReplicaCount": 1
}
]
}
```
## 对结果进行分页
如果您的集群有许多主题，则可以使用分页功能以较小的批量检索结果。使用`--max-results`参数指定要返回的最大主题数，并使用`--next-token`参数检索下一页的结果。
```
aws kafka list-topics --cluster-arn ClusterArn --max-results 10
```
如果有更多结果可用，则响应中会包含一个`nextToken`值。使用此令牌检索下一页的结果。
```
aws kafka list-topics --cluster-arn ClusterArn --max-results 10 --next-token NextToken
```
## 按名称筛选主题
您可以通过使用`--topic-name-filter`参数指定前缀来筛选主题列表。这将仅返回名称以指定前缀开头的主题。
```
aws kafka list-topics --cluster-arn ClusterArn --topic-name-filter "prod-"
```
此命令仅返回名称以开头的主题`prod-`，例如`prod-orders`或`prod-inventory`。
# 使用 API 列出主题
要使用 API 列出主题，请参阅[ListTopics](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics.html#ListTopics)。
# 获取有关某个主题的详细信息
您可以检索有关 MSK Provisioned 集群中特定主题的详细信息，包括其当前状态、分区数、重复因子和配置。这对于故障排除、验证主题设置或在操作期间监控主题状态非常有用。
**注意**
此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。
**Topics**
+ [
# 使用描述主题 AWS 管理控制台
](describe-topic-console.md)
+ [
# 使用描述主题 AWS CLI
](describe-topic-cli.md)
+ [
# 使用 API 描述主题
](describe-topic-api.md)
# 使用描述主题 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择包含您要描述的主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 在主题列表中，选择要查看的主题的名称。
1. 主题详细信息页面显示有关该主题的信息，包括其状态、分区数、重复因子和配置设置。
# 使用描述主题 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*您要描述的主题的名称。
```
aws kafka describe-topic --cluster-arn ClusterArn --topic-name TopicName
```
该 命令的输出如以下 JSON 示例所示。
```
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic",
"topicName": "MyTopic",
"partitionCount": 3,
"replicationFactor": 3,
"configs": "Y29tcHJlc3Npb24udHlwZT1wcm9kdWNlcgpyZXRlbnRpb24ubXM9NjA0ODAwMDAw",
"status": "ACTIVE"
}
```
## 了解主题状态
该`status`字段表示主题的当前状态。下表描述了可能的状态值。
**主题状态值**
| Status | 说明 |
| --- | --- |
| CREATING | 主题正在创建中。 |
| ACTIVE | 该主题处于活动状态，可供使用。 |
| UPDATING | 主题配置正在更新中。 |
| DELETING | 该主题正在删除中。 |
## 了解主题配置
该`configs`字段包含主题的 Kafka 配置属性，这些属性以 Base64 格式编码。要以可读格式查看配置，您需要解码 Base64 字符串。
以下示例显示了如何在 Linux 或 macOS 上使用`base64`命令对配置进行解码。
```
echo "Y29tcHJlc3Npb24udHlwZT1wcm9kdWNlcgpyZXRlbnRpb24ubXM9NjA0ODAwMDAw" | base64 --decode
```
解码后的输出以键值格式显示主题配置属性。
```
compression.type=producer
retention.ms=604800000
```
有关主题级配置属性的更多信息，请参阅。[主题级别的 Amazon MSK 配置](msk-configuration-properties.md#msk-topic-confinguration)
# 使用 API 描述主题
要使用 API 描述主题，请参阅[DescribeTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#DescribeTopic)。
# 查看主题的分区信息
您可以检索有关 MSK Provisioned 集群中特定主题分区的详细信息。此信息包括分区号、领导代理、副本代理和同步副本 (ISR)。这对于监控分区分布、识别复制不足的分区或解决复制问题非常有用。
**注意**
此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。
**Topics**
+ [
# 使用查看分区信息 AWS 管理控制台
](describe-topic-partitions-console.md)
+ [
# 使用查看分区信息 AWS CLI
](describe-topic-partitions-cli.md)
+ [
# 使用 API 查看分区信息
](describe-topic-partitions-api.md)
# 使用查看分区信息 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择包含该主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 在主题列表中，选择要查看其分区信息的主题的名称。
1. 在主题详细信息页面上，将显示分区信息，显示每个分区的分区号、领导代理、副本和同步副本。
# 使用查看分区信息 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*主题名称。
```
aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName
```
该 命令的输出如以下 JSON 示例所示。
```
{
"partitions": [
{
"partition": 0,
"leader": 1,
"replicas": [1, 2, 3],
"isr": [1, 2, 3]
},
{
"partition": 1,
"leader": 2,
"replicas": [2, 3, 1],
"isr": [2, 3, 1]
},
{
"partition": 2,
"leader": 3,
"replicas": [3, 1, 2],
"isr": [3, 1]
}
]
}
```
## 了解分区信息
响应包含每个分区的以下信息：
+ **分区**-分区号。分区从 0 开始编号。
+ **le** ader — 此分区的领导者的代理 ID。领导者处理该分区的所有读取和写入请求。
+ **replicas** — 包含此分 IDs 区副本的代理列表。这包括同步和 out-of-sync副本。
+ **isr** — 同步副本 IDs 的代理列表。这些副本会完全赶上领导者，如果需要，可以接管领导者的职务。
在上面的示例中，分区 2 有一个 out-of-sync副本。该`replicas`列表包括经纪商 2，但`isr`列表中没有。这表明 broker 2 没有完全赶上该分区的领导者。
## 对结果进行分页
如果您的主题有多个分区，则可以使用分页功能以较小的批量检索结果。使用`--max-results`参数指定要返回的最大分区数，并使用`--next-token`参数检索下一页的结果。
```
aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName --max-results 10
```
如果有更多结果可用，则响应中会包含一个`nextToken`值。使用此令牌检索下一页的结果。
```
aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName --max-results 10 --next-token NextToken
```
## 常见使用案例
查看分区信息对以下几种情况很有用：
+ **识别复制不足的分区**-比较`replicas`和`isr`列表以确定某些副本不同步的分区。这可能表示性能问题或代理问题。
+ **监控分区分布**-检查分区领导者在代理之间是否均匀分布，以确保负载平衡。
+ 对@@ **复制问题进行故障排除**-通过查看 ISR 列表来确定哪些代理在跟上复制速度时遇到问题。
+ **规划分区重新平衡**-在执行重新平衡操作之前，请使用此信息了解当前分区布局。
# 使用 API 查看分区信息
要使用 API 查看分区信息，请参阅[DescribeTopicPartitions](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname-partitions.html#DescribeTopicPartitions)。
# 在 Amazon MSK 集群中创建主题
您可以直接使用此 API 在您的 MSK 预配置集群中创建主题，而无需设置任何自定义 Kafka。 AdminClient创建主题时，您可以指定主题名称、分区数、重复因子以及可选的主题配置。
**Topics**
+ [
# 使用创建主题 AWS 管理控制台
](create-topic-console.md)
+ [
# 使用创建主题 AWS CLI
](create-topic-cli.md)
+ [
# 使用 API 创建主题
](create-topic-api.md)
# 使用创建主题 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择要在其中创建主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 选择**创建主题**。
1. 输入主题名称、分区计数和重复因子。（可选）添加配置。您可以同时创建多个主题。
1. 选择**创建主题**。
# 使用创建主题 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN)。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
```
aws kafka create-topic --cluster-arn ClusterArn --topic-name MyTopic --partition-count 3 --replication-factor 3
```
该 命令的输出如以下 JSON 示例所示。
```
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic",
"topicName": "MyTopic",
"status": "CREATING"
}
```
# 使用 API 创建主题
要使用 API 创建主题，请参阅[CreateTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics.html#CreateTopic)。
# 更新 Amazon MSK 集群中的主题
更新现有主题的分区计数或主题级配置。此操作无需重新创建即可修改主题。
**注意**
您可以在单个 API 调用中更新分区计数或主题配置，但不能同时更新两者。要更新两者，请单独调用 API。
**Topics**
+ [
# 使用更新主题 AWS 管理控制台
](update-topic-console.md)
+ [
# 使用更新主题 AWS CLI
](update-topic-cli.md)
+ [
# 使用 API 更新主题
](update-topic-api.md)
# 使用更新主题 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择包含要更新的主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 选择要更新的主题，然后从 “**操作**” 中选择 **“编辑分区设置****” 或 “编辑配置”**。
1. 根据需要更新分区计数或配置。
1. 选择**保存**。
# 使用更新主题 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*要更新的主题名称。
```
aws kafka update-topic --cluster-arn ClusterArn --topic-name TopicName --partition-count 6
```
该 命令的输出如以下 JSON 示例所示。
```
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic",
"topicName": "MyTopic",
"status": "UPDATING"
}
```
# 使用 API 更新主题
要使用 API 更新主题，请参阅[UpdateTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#UpdateTopic)。
# 删除 Amazon MSK 集群中的主题
删除主题会永久删除其所有数据、元数据和分区信息。此操作无法撤消。
**Topics**
+ [
# 使用删除主题 AWS 管理控制台
](delete-topic-console.md)
+ [
# 使用删除主题 AWS CLI
](delete-topic-cli.md)
+ [
# 使用 API 删除主题
](delete-topic-api.md)
# 使用删除主题 AWS 管理控制台
1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。
1. 在集群列表中，选择包含要删除的主题的集群的名称。
1. 在集群详细信息页面上，选择**主题**选项卡。
1. 选择要删除的主题，然后从 “**操作**” 中选择 “**删除**”。
1. 确认删除，然后选择**删除**。
# 使用删除主题 AWS CLI
运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*要删除的主题的名称。
```
aws kafka delete-topic --cluster-arn ClusterArn --topic-name TopicName
```
该 命令的输出如以下 JSON 示例所示。
```
{
"topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic",
"topicName": "MyTopic",
"status": "DELETING"
}
```
# 使用 API 删除主题
要使用 API 删除主题，请参阅[DeleteTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#DeleteTopic)。
# Amazon MSK 资源
根据上下文可知，*资源*一词在 Amazon MSK 中有两种含义。在资源的 APIs 上下文中，是一个可以调用操作的结构。有关这些资源以及可在其上调用的操作的列表，请参阅《Amazon MSK API Reference》中的 [Resources](https://docs.aws.amazon.com/msk/1.0/apireference/resources.html)。在 [IAM 访问控制](iam-access-control.md) 上下文中，资源是可以允许或拒绝访问的实体，如 [授权策略资源](kafka-actions.md#msk-iam-resources) 小节所定义。
# Apache Kafka 版本
创建 Amazon MSK 集群时，您可以指定您想要使用哪个 Apache Kafka 版本。您还可以更新现有集群的 Apache Kafka 版本。本章中的主题可帮助您了解 Kafka 版本支持的时间表和最佳实践的建议。
**Topics**
+ [
# 支持的 Apache Kafka 版本
](supported-kafka-versions.md)
+ [
# Amazon MSK 版本支持
](version-support.md)
# 支持的 Apache Kafka 版本
Amazon Managed Streaming for Apache Kafka（Amazon MSK）支持以下 Apache Kafka 和 Amazon MSK 版本。Apache Kafka 社区为版本提供自发布之日起大约 12 个月的支持。有关更多详细信息，请参阅 [Apache Kafka EOL (end of life) policy](https://cwiki.apache.org/confluence/display/KAFKA/Time+Based+Release+Plan#TimeBasedReleasePlan-WhatIsOurEOLPolicy?)。
下表列出了 Amazon MSK 支持的 Apache Kafka 版本。
| Apache Kafka 版本 | MSK 发布日期 | 终止支持日期 |
| --- | --- | --- |
| [1.1.1](https://archive.apache.org/dist/kafka/1.1.1/RELEASE_NOTES.html) | -- | 2024-06-05 |
| [2.1.0](https://archive.apache.org/dist/kafka/2.1.0/RELEASE_NOTES.html) | -- | 2024-06-05 |
| [2.2.1](https://archive.apache.org/dist/kafka/2.2.1/RELEASE_NOTES.html) | 2019-07-31 | 2024-06-08 |
| [2.3.1](https://archive.apache.org/dist/kafka/2.3.1/RELEASE_NOTES.html) | 2019-12-19 | 2024-06-08 |
| [2.4.1](https://archive.apache.org/dist/kafka/2.4.1/RELEASE_NOTES.html) | 2020-04-02 | 2024-06-08 |
| [2.4.1.1](https://archive.apache.org/dist/kafka/2.4.1/RELEASE_NOTES.html) | 2020-09-09 | 2024-06-08 |
| [2.5.1](https://archive.apache.org/dist/kafka/2.5.1/RELEASE_NOTES.html) | 2020-09-30 | 2024-06-08 |
| [2.6.0](https://archive.apache.org/dist/kafka/2.6.0/RELEASE_NOTES.html) | 2020-10-21 | 2024-09-11 |
| [2.6.1](https://archive.apache.org/dist/kafka/2.6.1/RELEASE_NOTES.html) | 2021-01-19 | 2024-09-11 |
| [2.6.2](https://archive.apache.org/dist/kafka/2.6.2/RELEASE_NOTES.html) | 2021-04-29 | 2024-09-11 |
| [2.6.3](https://archive.apache.org/dist/kafka/2.6.3/RELEASE_NOTES.html) | 2021-12-21 | 2024-09-11 |
| [2.7.0](https://archive.apache.org/dist/kafka/2.7.0/RELEASE_NOTES.html) | 2020-12-29 | 2024-09-11 |
| [2.7.1](https://archive.apache.org/dist/kafka/2.7.1/RELEASE_NOTES.html) | 2021-05-25 | 2024-09-11 |
| [2.7.2](https://archive.apache.org/dist/kafka/2.7.2/RELEASE_NOTES.html) | 2021-12-21 | 2024-09-11 |
| [2.8.0](https://archive.apache.org/dist/kafka/2.8.0/RELEASE_NOTES.html) | 2021-05-19 | 2024-09-11 |
| [2.8.1](https://archive.apache.org/dist/kafka/2.8.1/RELEASE_NOTES.html) | 2022-10-28 | 2024-09-11 |
| [2.8.2](https://archive.apache.org/dist/kafka/2.8.2/RELEASE_NOTES.html) | 2022-10-28 | 2025-01-14 |
| [3.1.1](https://archive.apache.org/dist/kafka/3.1.1/RELEASE_NOTES.html) | 2022-06-22 | 2024-09-11 |
| [3.2.0](https://archive.apache.org/dist/kafka/3.2.0/RELEASE_NOTES.html) | 2022-06-22 | 2024-09-11 |
| [3.3.1](https://archive.apache.org/dist/kafka/3.3.1/RELEASE_NOTES.html) | 2022-10-26 | 2024-09-11 |
| [3.3.2](https://archive.apache.org/dist/kafka/3.3.2/RELEASE_NOTES.html) | 2023-03-02 | 2024-09-11 |
| [3.4.0](https://archive.apache.org/dist/kafka/3.4.0/RELEASE_NOTES.html) | 2023-05-04 | 2025-08-04 |
| [3.5.1](https://archive.apache.org/dist/kafka/3.5.1/RELEASE_NOTES.html) | 2023-09-26 | 2025-10-23 |
| [3.6.0](https://archive.apache.org/dist/kafka/3.6.0/RELEASE_NOTES.html) | 2023-11-16 | 2026-06-01 |
| [3.7.x](https://archive.apache.org/dist/kafka/3.7.0/RELEASE_NOTES.html) | 2024-05-29 | -- |
| [3.8.x](https://downloads.apache.org/kafka/3.8.0/RELEASE_NOTES.html) | 2025-02-20 | -- |
| [3.9.x（推荐](https://downloads.apache.org/kafka/3.9.0/RELEASE_NOTES.html)） | 2025-04-21 | -- |
| [4.0.x](https://downloads.apache.org/kafka/4.0.0/RELEASE_NOTES.html) | 2025-05-16 | -- |
| [4.1.x](https://downloads.apache.org/kafka/4.1.0/RELEASE_NOTES.html) | 2025-10-15 | -- |
有关 Amazon MSK 版本支持策略的更多信息，请参阅[Amazon MSK 版本支持策略](version-support.md#version-support-policy)。
## Amazon MSK 版本 4.1.x
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在支持 Apache Kafka 版本 4.1，该版本推出了预览版的队列功能、新的流再平衡协议抢先体验版以及合格领导副本（ELR）。除这些功能外，Apache Kafka 版本 4.1 还包括各种错误修复和改进。
Kafka 4.1 的一个主要亮点是推出了预览版的队列功能。您可以使用多个使用者来处理来自同一主题分区的消息，从而提高需要 point-to-point消息传送的工作负载的并行度和吞吐量。新的流再平衡协议建立在 Kafka 4.0 的使用者再平衡协议之上，并将代理协调功能扩展至 Kafka Streams，实现任务分配的优化和再平衡。此外，为增强可用性，现在默认已启用 ELR。
有关更多详细信息以及改进和错误修复的完整列表，请参阅 [Apache Kafka 的 4.1 版发行说明](https://downloads.apache.org/kafka/4.1.0/RELEASE_NOTES.html)。
要开始在 Amazon MSK 上使用 Apache Kafka 4.1，请在通过、或创建新集群时选择 4.1.x 版本。 AWS 管理控制台 AWS CLI AWS SDKs还可以通过就地滚动更新来升级现有的预置 MSK 集群。Amazon MSK 会编排代理重启，以便在升级期间保持可用性并保护数据。所有提供 Amazon MSK AWS 区域 的地方都支持 Kafka 版本 4.1。
## Amazon MSK 版本 4.0.x
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在支持 Apache Kafka 版本 4.0。此版本为预置 MSK 带来了最新的集群管理和性能升级。Kafka 4.0 推出的新使用者再平衡协议现已正式发布，有助于确保组实现更顺利、更快的再平衡。此外，Kafka 4.0 要求代理和工具使用 Java 17，从而提高安全性和性能，包括各种错误修复和改进，并弃用通过 Apache 进行元数据管理。 ZooKeeper
有关更多详细信息以及改进和错误修复的完整列表，请参阅 [Apache Kafka 的 4.0 版发行说明](https://downloads.apache.org/kafka/4.0.0/RELEASE_NOTES.html)。
## 亚马逊 MSK 版本 3.9.x（推荐）
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在支持 Apache Kafka 版本 3.9。此版本支持在主题级别禁用分层存储时保留分层数据，从而增强了分层存储功能。使用者应用程序可以从远程日志起始偏移量（Rx）读取历史数据，同时在本地和远程存储之间保持连续的日志偏移。
3.9 版是支持这两种系统 ZooKeeper 和 KRaft 元数据管理系统的最后一个版本。Amazon MSK 将为版本 3.9 提供至少两年的扩展支持，自该版本发布之日起计算。
有关更多详细信息以及改进和错误修复的完整列表，请参阅 [Apache Kafka 的 3.9.x 版发行说明](https://downloads.apache.org/kafka/3.9.0/RELEASE_NOTES.html)。
## 亚马逊 MSK 版本 3.8.x
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在支持 Apache Kafka 版本 3.8。现在，您可以使用 3.8 版使用 KRAFT 或元数据管理 ZooKeeper 模式创建新集群，也可以将现有的 ZooKeeper 基于集群升级为使用 3.8 版。Apache Kafka 3.8 包含一些可提高性能的错误修复和新功能。主要的新功能包括支持压缩级别配置。这样在使用 lz4、zstd 和 gzip 等压缩类型时，就可以通过更改默认压缩级别来进一步优化性能。
有关更多详细信息以及改进和错误修复的完整列表，请参阅 [Apache Kafka 的 3.8.x 版发行说明](https://downloads.apache.org/kafka/3.8.0/RELEASE_NOTES.html)。
## Apache Kafka 版本 3.7.x（支持生产就绪的分层存储）
MSK 上的 Apache Kafka 版本 3.7.x 包含对 Apache Kafka 版本 3.7.0 的支持。您可以创建集群或升级现有集群以使用新的 3.7.x 版本。通过这一版本命名更改，当 Apache Kafka 社区发布较新的补丁修复版本（例如 3.7.1）时，您不再需要采用它们。将来一旦有补丁版本可用，Amazon MSK 将自动更新 3.7.x 以支持该版本。这使您能够从补丁修复版本提供的安全性和错误修复中受益，而无需触发版本升级。Apache Kafka 发布的这些补丁修复版本不会破坏版本兼容性，您可以从新的补丁修复版本中受益，而不必担心客户端应用程序的读取或写入错误。请确保您的基础设施自动化工具（例如）已更新 CloudFormation，以应对版本命名的这一变化。
亚马逊 MSK 现在支持 Apache Kafka 版本 3.7.x 中的 KRaft 模式（Apache Kafka Raft）。与 ZooKeeper 节点一样，在 Amazon MSK 上， KRaft 控制器包含在内，您无需支付任何额外费用，也不需要您进行额外的设置或管理。现在，你可以在 Apache Kafka 版本 3. ZooKeeper 7.x 上以两种 KRaft 模式或模式创建集群。在 Kraft 模式下，您可以添加最多 60 个代理来在每个集群中托管更多分区，而无需请求增加限制，而基于 Zookeeper 的集群上的代理配额为 30 个。要了解有关 MSK KRaft 的更多信息，请参阅[KRaft 模式](metadata-management.md#kraft-intro)。
Apache Kafka 版本 3.7.x 还包含一些可提高性能的错误修复和新功能。主要改进包括针对客户端的领导者发现优化和日志段刷新优化选项。有关改进和错误修复的完整列表，请参阅 Apache Kafka [3.7.0](https://archive.apache.org/dist/kafka/3.7.0/RELEASE_NOTES.html) 发行说明。
## Apache Kafka 版本 3.6.0（支持生产就绪的分层存储）
有关 Apache Kafka 版本 3.6.0（支持生产就绪的分层存储）的信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/3.6.0/RELEASE_NOTES.html)。
为了稳定起见，在本版本中，Amazon MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。
## Amazon MSK 版本 3.5.1
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在对新集群和现有集群支持 Apache Kafka 版本 3.5.1。Apache Kafka 3.5.1 包含一些可提高性能的错误修复和新功能。主要功能包括为消费者引入新的机架感知分区分配。在本版本中，Amazon MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。有关改进和错误修复的完整列表，请参阅 Apache Kafka 3.5.1 发行说明。
有关 Apache Kafka 版本 3.5.1 的信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/3.5.1/RELEASE_NOTES.html)。
## Amazon MSK 版本 3.4.0
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在对新集群和现有集群支持 Apache Kafka 版本 3.4.0。Apache Kafka 3.4.0 包含一些可提高性能的错误修复和新功能。主要功能包括一个修复，可提高从最近的副本中提取的稳定性。在本版本中，Amazon MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。有关改进和错误修复的完整列表，请参阅 Apache Kafka 3.4.0 发行说明。
有关 Apache Kafka 版本 3.4.0 的信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/3.4.0/RELEASE_NOTES.html)。
## Amazon MSK 版本 3.3.2
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在对新集群和现有集群支持 Apache Kafka 版本 3.3.2。Apache Kafka 3.3.2 包含一些可提高性能的错误修复和新功能。主要功能包括一个修复，可提高从最近的副本中提取的稳定性。在本版本中，Amazon MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。有关改进和错误修复的完整列表，请参阅 Apache Kafka 3.3.2 发行说明。
有关 Apache Kafka 版本 3.3.2 的信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/3.3.2/RELEASE_NOTES.html)。
## Amazon MSK 版本 3.3.1
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在对新集群和现有集群支持 Apache Kafka 版本 3.3.1。Apache Kafka 3.3.1 包含一些可提高性能的错误修复和新功能。一些主要功能包括对指标和分区程序的增强。为了稳定起见，在本版本中，Amazon MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。有关改进和错误修复的完整列表，请参阅 Apache Kafka 3.3.1 发行说明。
有关 Apache Kafka 版本 3.3.1 的信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/3.3.1/RELEASE_NOTES.html)。
## Amazon MSK 版本 3.1.1
Amazon Managed Streaming for Apache Kafka（Amazon MSK）现在对新集群和现有集群支持 Apache Kafka 版本 3.1.1 和 3.2.0。Apache Kafka 3.1.1 和 Apache Kafka 3.2.0 包含一些可提高性能的错误修复和新功能。一些关键功能包括对指标的增强和主题的使用 IDs。为了稳定起见，在本版本中，MSK 将继续使用和管理 Zookeeper 以进行仲裁管理。有关改进和错误修复的完整列表，请参阅 Apache Kafka 3.1.1 和 3.2.0 的发行说明。
有关 Apache Kafka 版本 3.1.1 和 3.2.0 的信息，请参阅 Apache Kafka 下载网站上的 [3.2.0 发行说明](https://archive.apache.org/dist/kafka/3.2.0/RELEASE_NOTES.html)和 [3.1.1 发行说明](https://archive.apache.org/dist/kafka/3.1.1/RELEASE_NOTES.html)。
## Amazon MSK 分层存储版本 2.8.2.tiered
此版本是 Apache Kafka 版本 2.8.2 的仅限 Amazon MSK 版本，与开源 Apache Kafka 客户端兼容。
2.8.2 分层版本包含分层存储功能，该功能与 Apache Kafka 的 [KIP-405 中 APIs 引入的分层存储功能兼容。](https://cwiki.apache.org/confluence/display/KAFKA/KIP-405%3A+Kafka+Tiered+Storage)有关 Amazon MSK 分层存储功能的更多信息，请参阅[标准代理的分层存储](msk-tiered-storage.md)。
## Apache Kafka 版本 2.5.1
Apache Kafka 版本 2.5.1 包含多个错误修复和新功能，包括针对 Ap ZooKeeper ache 和管理客户端的传输加密。Amazon MSK 提供了 TLS ZooKeeper 终端节点，您可以通过[DescribeCluster ](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)操作查询这些终端节点。
该[ DescribeCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)操作的输出包括`ZookeeperConnectStringTls`节点，该节点列出了 TLS zookeeper 端点。
以下示例显示了 `DescribeCluster` 操作的响应 `ZookeeperConnectStringTls` 节点：
```
"ZookeeperConnectStringTls": "z-3.awskafkatutorialc.abcd123.c3.kafka.us-east-1.amazonaws.com:2182,z-2.awskafkatutorialc.abcd123.c3.kafka.us-east-1.amazonaws.com:2182,z-1.awskafkatutorialc.abcd123.c3.kafka.us-east-1.amazonaws.com:2182"
```
有关将 TLS 加密用于 Zookeeper 的信息，请参阅 [在 Apache 中使用 TLS 安全性 ZooKeeper](zookeeper-security-tls.md)。
有关 Apache Kafka 版本 2.5.1 的更多信息，请参阅 Apache Kafka 下载网站上的 [Release Notes](https://archive.apache.org/dist/kafka/2.5.1/RELEASE_NOTES.html)。
## Amazon MSK 错误修复版本 2.4.1.1
此版本是 Apache Kafka 版本 2.4.1 的仅限 Amazon MSK 的错误修复版本。此错误修复版本包含 [KAFKA-9752](https://issues.apache.org/jira/browse/KAFKA-9752) 的修复程序，这是一个极少出现的问题，会导致使用器组不断重新平衡并保持 `PreparingRebalance` 状态。此问题会影响运行 Apache Kafka 版本 2.3.1 和 2.4.1 的集群。此版本包含社区制作的修复程序，可用于 Apache Kafka 版本 2.5.0。
**注意**
运行版本 2.4.1.1 的 Amazon MSK 集群与兼容 Apache Kafka 版本 2.4.1 的任何 Apache Kafka 客户端兼容。
如果您更喜欢使用 Apache Kafka 2.4.1，建议您对新的 Amazon MSK 集群使用 MSK 错误修复版本 2.4.1.1。您可以将运行 Apache Kafka 版本 2.4.1 的现有集群更新为此版本，以加入此修复程序。有关升级现有集群的信息，请参阅[升级 Apache Kafka 版本](version-upgrades.md)。
要在不将集群升级到 2.4.1.1 版本的情况下解决此问题，请参阅[排查 Amazon MSK 集群的问题](troubleshooting.md)指南的[使用器组卡滞在 `PreparingRebalance` 状态](troubleshooting.md#consumer-group-rebalance)部分。
## Apache Kafka 版本 2.4.1（改用 2.4.1.1 版）
**注意**
您无法再使用 Apache Kafka 版本 2.4.1 创建新的 MSK 集群。相反，您可以将 [Amazon MSK 错误修复版本 2.4.1.1](#2.4.1.1) 与兼容 Apache Kafka 版本 2.4.1 的客户端结合使用。而且，如果已经拥有使用 Apache Kafka 版本 2.4.1 的 MSK 集群，建议您将其更新为使用 Apache Kafka 版本 2.4.1.1。
KIP-392 是 Apache Kafka 2.4.1 版中包含的重要 Kafka 改进建议之一。此项改进允许使用器从最近的副本提取。要使用此功能，请将使用器属性中的 `client.rack` 设置为使用器可用区的 ID。可用区 ID 的其中一个例子是 `use1-az1`。Amazon MSK 设置`broker.rack` IDs 了经纪商的可用区域。您还必须将 `replica.selector.class` 配置属性设置为 `org.apache.kafka.common.replica.RackAwareReplicaSelector`，这是 Apache Kafka 提供的 rack 感知的一种实现方式。
当您使用此版本的 Apache Kafka 时，`PER_TOPIC_PER_BROKER` 监控级别中的指标仅在其值首次变为非零后才会显示。有关此问题的更多信息，请参阅[`PER_TOPIC_PER_BROKER` 级别监控](metrics-details.md#broker-topic-metrics)。
有关如何查找可用区的信息 IDs，请参阅 AWS Resource Access Manager 用户指南[中的资源可用 IDs ](https://docs.aws.amazon.com/ram/latest/userguide/working-with-az-ids.html)区。
有关设置配置属性的信息，请参阅[预置 Amazon MSK 配置](msk-configuration.md)。
有关 KIP-392 的更多信息，请参阅 Confluence 页面中的[允许使用器从最近的副本提取](https://cwiki.apache.org/confluence/display/KAFKA/KIP-392:+Allow+consumers+to+fetch+from+closest+replica)。
有关 Apache Kafka 版本 2.4.1 的更多信息，请参阅 Apache Kafka 下载网站上的[版本说明](https://archive.apache.org/dist/kafka/2.4.1/RELEASE_NOTES.html)。
# Amazon MSK 版本支持
此主题介绍 [Amazon MSK 版本支持策略](#version-support-policy) 和 [升级 Apache Kafka 版本](version-upgrades.md) 的过程。如果要升级 Kafka 版本，请遵循[版本升级的最佳实践](version-upgrades-best-practices.md)中概述的最佳实践。
**Topics**
+ [
## Amazon MSK 版本支持策略
](#version-support-policy)
+ [
# 升级 Apache Kafka 版本
](version-upgrades.md)
+ [
# 版本升级的最佳实践
](version-upgrades-best-practices.md)
## Amazon MSK 版本支持策略
本节介绍了 Amazon MSK 支持的 Kafka 版本的支持策略。
+ 所有 Kafka 版本均受支持，直至达到其终止支持日期。有关终止支持日期的详细信息，请参阅[支持的 Apache Kafka 版本](supported-kafka-versions.md)。在终止支持日期之前，将您的 MSK 集群升级到推荐的 Kafka 版本或更高版本。有关升级 Apache Kafka 版本的详细信息，请参阅[升级 Apache Kafka 版本](version-upgrades.md)。在终止支持日期之后使用 Kafka 版本的集群会自动升级到推荐的 Kafka 版本。自动升级可以在支持结束日期后的任何时间进行。在升级之前，您不会收到任何通知。
+ MSK 将逐步停止对使用已发布终止支持日期的 Kafka 版本的新创建集群的支持。
# 升级 Apache Kafka 版本
您可以将现有的 MSK 集群升级为较新版本的 Apache Kafka。在升级集群的 Kafka 版本之前，请确认客户端软件版本支持新 Kafka 版本中的功能。
有关如何在升级期间使集群高度可用的信息，请参阅[构建高度可用的集群](bestpractices.md#ensure-high-availability)。
**使用 Apache Kafka 版本升级 AWS 管理控制台**
1. 在 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 打开 Amazon MSK 控制台。
1. 在导航栏上，选择您在其中创建 MSK 集群的区域。
1. 选择要升级的 MSK 集群。
1. 在**属性**选项卡上，在 **Apache Kafka 版本**部分中选择**升级**。
1. 在 **Apache Kafka 版本**部分，执行以下操作：
1. 在*选择 Apache Kafka 版本*下拉列表中，选择要升级至的目标版本。例如，选择 **3.9.x**。
1. （可选）选择**查看版本兼容性**，验证集群的当前版本与可用升级版本之间是否兼容。然后，选择**选择**以继续。
**注意**
Amazon MSK 支持大多数 Apache Kafka 版本进行就地升级。但是，从 ZooKeeper基于 Kafka 的版本升级到 KRaft基于 Kafka 的版本时，必须创建一个新集群。然后，将数据复制到新的集群，并将客户端切换至新集群。
1. （可选）选中**更新集群配置**复选框，应用与新版本兼容的配置更新。这就启用了新版本的功能和改进。
如果需要保持现有的自定义配置，可跳过这一步。
**注意**
服务器端升级不会自动更新客户端的应用程序。
为保持集群稳定性，不支持版本降级。
1. 选择**升级**以开始升级过程。
**使用 Apache Kafka 版本升级 AWS CLI**
1. 运行以下命令，并将 *ClusterArn* 替换为创建集群时所获取的 Amazon 资源名称（ARN）。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
```
aws kafka get-compatible-kafka-versions --cluster-arn ClusterArn
```
此命令的输出包括您可以将集群升级到的 Apache Kafka 版本的列表。其内容类似于以下示例。
```
{
"CompatibleKafkaVersions": [
{
"SourceVersion": "2.2.1",
"TargetVersions": [
"2.3.1",
"2.4.1",
"2.4.1.1",
"2.5.1"
]
}
]
}
```
1. 运行以下命令，并将 *ClusterArn* 替换为创建集群时所获取的 Amazon 资源名称（ARN）。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。
将 *Current-Cluster-Version* 替换为集群的当前版本。因为*TargetVersion*你可以从上一个命令的输出中指定任何目标版本。
**重要**
集群版本不是简单的整数。要查找集群的当前版本，请使用[DescribeCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster)操作或 desc [ribe-](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI cluster 命令。示例版本是 `KTVPDKIKX0DER`。
```
aws kafka update-cluster-kafka-version --cluster-arn ClusterArn --current-version Current-Cluster-Version --target-kafka-version TargetVersion
```
上一个命令的输出如以下 JSON 所示。
```
{
"ClusterArn": "arn:aws:kafka:us-east-1:012345678012:cluster/exampleClusterName/abcdefab-1234-abcd-5678-cdef0123ab01-2",
"ClusterOperationArn": "arn:aws:kafka:us-east-1:012345678012:cluster-operation/exampleClusterName/abcdefab-1234-abcd-5678-cdef0123ab01-2/0123abcd-abcd-4f7f-1234-9876543210ef"
}
```
1. 要获得`update-cluster-kafka-version`操作结果，请运行以下命令，*ClusterOperationArn*替换为在命令输出中获得的 ARN。`update-cluster-kafka-version`
```
aws kafka describe-cluster-operation --cluster-operation-arn ClusterOperationArn
```
该 `describe-cluster-operation` 命令的输出如以下 JSON 示例所示。
```
{
"ClusterOperationInfo": {
"ClientRequestId": "62cd41d2-1206-4ebf-85a8-dbb2ba0fe259",
"ClusterArn": "arn:aws:kafka:us-east-1:012345678012:cluster/exampleClusterName/abcdefab-1234-abcd-5678-cdef0123ab01-2",
"CreationTime": "2021-03-11T20:34:59.648000+00:00",
"OperationArn": "arn:aws:kafka:us-east-1:012345678012:cluster-operation/exampleClusterName/abcdefab-1234-abcd-5678-cdef0123ab01-2/0123abcd-abcd-4f7f-1234-9876543210ef",
"OperationState": "UPDATE_IN_PROGRESS",
"OperationSteps": [
{
"StepInfo": {
"StepStatus": "IN_PROGRESS"
},
"StepName": "INITIALIZE_UPDATE"
},
{
"StepInfo": {
"StepStatus": "PENDING"
},
"StepName": "UPDATE_APACHE_KAFKA_BINARIES"
},
{
"StepInfo": {
"StepStatus": "PENDING"
},
"StepName": "FINALIZE_UPDATE"
}
],
"OperationType": "UPDATE_CLUSTER_KAFKA_VERSION",
"SourceClusterInfo": {
"KafkaVersion": "2.4.1"
},
"TargetClusterInfo": {
"KafkaVersion": "2.6.1"
}
}
}
```
如果 `OperationState` 的值为 `UPDATE_IN_PROGRESS`，请等待一段时间，然后再次运行 `describe-cluster-operation` 命令。操作完成后，`OperationState` 的值变为 `UPDATE_COMPLETE`。由于 Amazon MSK 完成操作所需的时间各不相同，您可能需要反复检查直到操作完成。
**使用 API 升级 Apache Kafka 版本**
1. 调用该[GetCompatibleKafkaVersions](https://docs.aws.amazon.com//msk/1.0/apireference/compatible-kafka-versions.html#GetCompatibleKafkaVersions)操作以获取您可以将集群升级到的 Apache Kafka 版本列表。
1. 调用该[UpdateClusterKafkaVersion](https://docs.aws.amazon.com//msk/1.0/apireference/clusters-clusterarn-version.html#UpdateClusterKafkaVersion)操作将集群升级到兼容的 Apache Kafka 版本之一。
# 版本升级的最佳实践
为了在 Kafka 版本升级过程中执行的滚动更新期间确保客户端连续性，请检查客户端和 Apache Kafka 主题的配置，如下所示：
+ 对于双可用区集群，将主题复制因子（RF）的最小值设置为 `2`，对于三可用区集群，将最小值设置为 `3`。RF 值 `2` 可能会导致修补期间出现离线分区。
+ 将最小同步副本数（minISR）的上限设置为比复制因子（RF）小 1，即 `miniISR = (RF) - 1`。这可以确保分区副本集可以容忍一个副本离线或未完全复制。
+ 将客户端配置为使用多个代理连接字符串。如果支持客户端的特定代理 I/O 开始被修补，则在客户端的连接字符串中包含多个代理可以进行故障转移。有关如何获取具有多个代理的连接字符串的信息，请参阅 [Getting the bootstrap brokers for an Amazon MSK cluster](https://docs.aws.amazon.com//msk/latest/developerguide/msk-get-bootstrap-brokers.html)。
+ 我们建议您将连接客户端升级到推荐的版本或更高版本，以便从新版本提供的功能中受益。客户端升级不受 MSK 集群的 Kafka 版本的生命周期终止（EOL）日期限制，也无需在 EOL 日期之前完成。Apache Kafka 提供了[双向客户端兼容性策略](https://kafka.apache.org/protocol#protocol_compatibility)，允许较旧客户端与较新集群配合使用，反之亦然。
+ 使用版本 3.x.x 的 Kafka 客户端可能具有以下默认值：`acks=all` 和 `enable.idempotence=true`。`acks=all` 与之前的默认值 `acks=1` 不同，它通过确保所有同步副本都确认生成请求来提供额外持久性。同样，`enable.idempotence` 的默认值以前为 `false`。将 `enable.idempotence=true` 更改为默认值可降低重复消息的可能性。这些更改被视为最佳实践设置，可能会带来少量额外延迟，但这在正常性能参数范围内。
+ 创建新的 MSK 集群时，请使用推荐的 Kafka 版本。使用推荐的 Kafka 版本可让您受益于最新的 Kafka 和 MSK 功能。
# 排查 Amazon MSK 集群的问题
以下信息可帮助您排查 Amazon MSK 集群可能存在的问题。您也可以将问题发布到 [AWS re:Post](https://repost.aws/)。有关排查 Amazon MSK 复制器问题的信息，请参阅 [排查 MSK 复制器问题](msk-replicator-troubleshooting.md)。
**Topics**
+ [
## 由于复制过载，卷更换导致磁盘饱和
](#replication-overload-disk-saturation)
+ [
## 使用器组卡滞在 `PreparingRebalance` 状态
](#consumer-group-rebalance)
+ [
## 向 Amazon CloudWatch 日志传送代理日志时出错
](#cw-broker-logs-error)
+ [
## 无默认安全组
](#troubleshooting-shared-vpc)
+ [
## 集群显示卡在 CREATING 状态
](#troubleshooting-cluster-stuck)
+ [
## 集群状态从 CREATING 变为 FAILED
](#troubleshooting-cluster-failed)
+ [
## 集群状态为 ACTIVE，但生成器无法发送数据，或者使用器无法接收数据
](#troubleshooting-nodata)
+ [
## AWS CLI 无法识别 Amazon MSK
](#troubleshooting-nocli)
+ [
## 分区脱机或副本不同步
](#troubleshooting-offlinepartition-outofsyncreplicas)
+ [
## 磁盘空间不足
](#troubleshooting-lowdiskspace)
+ [
## 内存不足
](#troubleshooting-lowmemory)
+ [
## 制片人获得 NotLeaderForPartitionException
](#troubleshooting-NotLeaderForPartitionException)
+ [
## 复制中的分区（URP）大于零
](#troubleshooting-urp)
+ [
## 集群中有名为 \$1\$1amazon\$1msk\$1canary 和 \$1\$1amazon\$1msk\$1canary\$1state 的主题
](#amazon_msk_canary)
+ [
## 分区复制失败
](#partition_replication_fails)
+ [
## 无法访问已开启公共访问权限的集群
](#public-access-issues)
+ [
## 无法通过 IPv6 引导访问集群
](#dualstack-issues)
+ [
## 无法从内部访问集群 AWS：网络问题
](#networking-trouble)
+ [
## 身份验证失败：连接次数过多
](#troubleshoot-too-many-connects)
+ [
## 身份验证失败：会话时间太短
](#troubleshoot-session-too-short)
+ [
## MSK Serverless：集群创建失败
](#troubleshoot-serverless-create-cluster-failure)
+ [
## 无法 KafkaVersionsList 在 MSK 配置中更新
](#troubleshoot-kafkaversionslist-cfn-update-failure)
## 由于复制过载，卷更换导致磁盘饱和
在计划外卷硬件故障期间，Amazon MSK 可能会用新实例替换该卷。Kafka 通过从集群中的其他代理复制分区来重新填充新卷。一旦分区完成复制并赶上，它们就有资格获得领导权和同步副本（ISR）成员资格。
**问题**
在从卷更换恢复的代理中，一些不同大小的分区可能会先于其他分区恢复在线。这可能会出现问题，因为这些分区可能正在为来自同一代理的流量提供服务，而该代理仍在追赶（复制）其他分区。此复制流量有时会使底层卷吞吐量限制饱和，默认情况下为每秒 250 MiB。当出现这种饱和时，任何已经赶上的分区都会受到影响，导致集群中与这些赶上的分区共享 ISR 的任何代理（不仅仅是由于远程确认 `acks=all` 导致的领导者分区）出现延迟。此问题在具有大量大小不同的分区的较大集群中更为常见。
**建议**
+ 要改善复制 I/O 状态，请确保[最佳实践线程设置](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html#optimize-broker-threads)到位。
+ 要降低底层容量饱和的可能性，请启用具有更高吞吐量的预置存储。对于高吞吐量复制案例，建议将最小吞吐量值设置 MiB/s 为 500，但实际所需的值会因吞吐量和用例而异。 [为 Amazon MSK 集群中的标准代理预置存储吞吐量](msk-provision-throughput.md)。
+ 为了最大限度地减少复制压力，请将 `num.replica.fetchers` 降低为默认值 `2`。
## 使用器组卡滞在 `PreparingRebalance` 状态
如果一个或多个使用器组卡滞在一个永久的再平衡状态，则原因可能是 Apache Kafka 问题 [KAFKA-9752](https://issues.apache.org/jira/browse/KAFKA-9752)，这会影响 Apache Kafka 版本 2.3.1 和 2.4.1。
要解决此问题，建议您将集群升级到 [Amazon MSK 错误修复版本 2.4.1.1](supported-kafka-versions.md#2.4.1.1)，其中包含针对此问题的修复程序。有关将现有集群更新到 Amazon MSK 错误修复版本 2.4.1.1 的信息，请参阅[升级 Apache Kafka 版本](version-upgrades.md)。
在不将集群升级到 Amazon MSK 错误修复版本 2.4.1.1 的情况下解决此问题的方法是，设置要使用 [静态成员协议](#consumer-group-rebalance-static) 的 Kafka 客户端，或者 [识别并重启](#consumer-group-rebalance-reboot) 卡住的使用器组的协调代理节点。
### 实现静态成员协议
要在客户端中实现静态成员协议，请执行以下操作：
1. 将 [Kafka 使用器](https://kafka.apache.org/26/javadoc/index.html?org/apache/kafka/clients/consumer/KafkaConsumer.html)配置的 `group.instance.id` 属性设置为可识别组中使用器的静态字符串。
1. 确保配置的其他实例已更新为使用静态字符串。
1. 将更改部署到您的 Kafka 使用器。
如果将客户端配置中的会话超时设置为允许使用器在不过早触发使用器组重新平衡的情况下恢复的持续时间，则使用静态成员协议会更有效。例如，如果您的使用器应用程序可以容忍 5 分钟不可用，则会话超时的合理值为 4 分钟，而不是默认的 10 秒。
**注意**
使用静态成员协议只会降低遇到此问题的可能性。即使使用静态成员协议，您仍可能遇到此问题。
### 重启协调代理节点
要重启协调代理节点，请执行以下操作：
1. 使用 `kafka-consumer-groups.sh` 命令识别组协调器。
1. 使用 [ RebootBroker](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-reboot-broker.html#RebootBroker)API 操作重新启动卡住的消费者组的群组协调器。
## 向 Amazon CloudWatch 日志传送代理日志时出错
当您尝试将集群设置为向 Amazon Logs 发送代理 CloudWatch 日志时，可能会遇到两个例外情况之一。
如果遇到 `InvalidInput.LengthOfCloudWatchResourcePolicyLimitExceeded` 异常，请重试，但使用以 `/aws/vendedlogs/` 开头的日志组。有关更多信息，请参阅[启用从某些 Amazon Web Services 进行日志记录](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)。
如果您遇到异`InvalidInput.NumberOfCloudWatchResourcePoliciesLimitExceeded`常，请选择您账户中的现有 Ama CloudWatch zon Logs 政策，并在其中附加以下 JSON。
```
{"Sid":"AWSLogDeliveryWrite","Effect":"Allow","Principal":{"Service":"delivery.logs.amazonaws.com"},"Action":["logs:CreateLogStream","logs:PutLogEvents"],"Resource":["*"]}
```
如果您尝试将上述 JSON 附加到现有策略中，但收到错误提示您已达到所选策略的最大长度，请尝试将 JSON 附加到您的另一个 Amazon L CloudWatch ogs 策略中。将 JSON 附加到现有策略后，请再次尝试将代理日志传输设置为 Amazon Logs。 CloudWatch
## 无默认安全组
如果您尝试创建集群，并收到错误指示没有默认安全组，则可能是因为您使用的是共享 VPC。请向管理员申请向您授予描述此 VPC 上的安全组的权限，然后重试。有关允许此操作的策略示例，请参阅 [Amazon EC2：允许以编程方式在控制台中管理与特定 VPC 关联的 EC2 安全组](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_ec2_securitygroups-vpc.html)。
## 集群显示卡在 CREATING 状态
有时，集群创建可能需要长达 30 分钟。请等待 30 分钟，然后再次检查集群的状态。
## 集群状态从 CREATING 变为 FAILED
请尝试再次创建集群。
## 集群状态为 ACTIVE，但生成器无法发送数据，或者使用器无法接收数据
+ 如果集群创建成功（集群状态为 `ACTIVE`），但您无法发送或接收数据，请确保生成器和使用器应用程序有权访问集群。有关更多信息，请参阅[步骤 3：创建客户端计算机](create-client-machine.md)中的指南。
+ 如果您的生产器和使用器有权访问集群，但仍出现生成和使用数据问题，原因可能是 [KAFKA-7697](https://issues.apache.org/jira/browse/KAFKA-7697)，这会影响 Apache Kafka 2.1.0 版本，并可能导致一个或多个代理发生死锁。请考虑迁移到 Apache Kafka 2.2.1，该版本不受此错误影响。有关如何迁移的信息，请参阅[将 Kafka 工作负载迁移至 Amazon MSK 集群](migration.md)。
## AWS CLI 无法识别 Amazon MSK
如果您已 AWS CLI 安装但它无法识别 Amazon MSK 命令，请 AWS CLI 将您的命令升级到最新版本。有关如何升级的详细说明 AWS CLI，请参阅[安装 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。有关如何使用运行 Amazon MSK 命令的信息，请参阅[Amazon MSK 的关键功能和概念](operations.md)。 AWS CLI
## 分区脱机或副本不同步
这些可能是磁盘空间不足的症状。请参阅[磁盘空间不足](#troubleshooting-lowdiskspace)。
## 磁盘空间不足
请参阅以下有关管理磁盘空间的最佳实践：[监控磁盘空间](bestpractices.md#bestpractices-monitor-disk-space)和[调整数据保留参数](bestpractices.md#bestpractices-retention-period)。
## 内存不足
如果您发现 `MemoryUsed` 指标太高或 `MemoryFree` 太低，这并不意味着存在问题。Apache Kafka 的设计初衷是充分利用内存，并以最佳方式管理内存。
## 制片人获得 NotLeaderForPartitionException
这往往是临时错误。将生成器的 `retries` 配置参数设置为高于其当前值的值。
## 复制中的分区（URP）大于零
`UnderReplicatedPartitions` 指标是要监控的重要指标。在正常运行的 MSK 集群中，此指标的值为 0。如果它大于零，这可能是由以下某个原因所致。
+ 如果 `UnderReplicatedPartitions` 是峰值，问题可能在于该集群的大小配置不合适，无法处理传入和传出流量。请参阅[标准代理的最佳实践](bestpractices.md)。
+ 如果`UnderReplicatedPartitions`持续大于 0，包括在低流量时段，则问题可能是您设置了不向经纪人授予主题访问权限的限制 ACLs 。要复制分区，必须向代理授予 READ 和 DESCRIBE 主题的权限。默认情况下，将随 READ 授权一起授予 DESCRIBE 权限。有关设置的信息 ACLs，请参阅[授权和](https://kafka.apache.org/documentation/#security_authz) Apache Kafka 文档 ACLs中。
## 集群中有名为 \$1\$1amazon\$1msk\$1canary 和 \$1\$1amazon\$1msk\$1canary\$1state 的主题
您可能会看到，MSK 集群有一个名为 `__amazon_msk_canary` 的主题，而另一个主题的名称为 `__amazon_msk_canary_state`。这些是 Amazon MSK 创建并用于集群运行状况和诊断指标的内部主题。这些主题无法删除，不过大小可以忽略不计。
## 分区复制失败
确保您尚未在 CLUSTER\$1ACTI ACLs ONS 上进行设置。
## 无法访问已开启公共访问权限的集群
如果您的集群已开启公共访问权限，但您仍然无法通过互联网访问它，请按照以下步骤操作：
1. 确保集群安全组的入站规则允许您的 IP 地址和集群端口。有关集群端口号的列表，请参阅[端口信息](port-info.md)。还要确保安全组的出站规则允许出站通信。有关安全组及其入站和出站规则的更多信息，请参阅《Amazon VPC 用户指南》中的[您的 VPC 的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。
1. 确保集群 VPC 网络 ACL 的入站规则中允许您的 IP 地址和集群端口。与安全组不同，网络 ACLs 是无状态的。这意味着您必须配置入站和出站规则。在出站规则中，允许所有流量（端口范围：0-65535）发送到您的 IP 地址。有关更多信息，请参阅《Amazon VPC 用户指南》中的[添加和删除规则](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html#Rules)。
1. 确保您使用的是公共访问引导代理字符串来访问集群。开启了公共访问权限的 MSK 集群有两个不同的引导代理字符串，一个用于公共访问，另一个用于从 AWS内部访问。有关更多信息，请参阅 [使用获取引导程序代理 AWS 管理控制台](get-bootstrap-console.md)。
## 无法通过 IPv6 引导访问集群
如果您在使用提供的 IPv6 引导字符串连接到集群时遇到问题，请按照以下步骤操作：
1. 确保您的客户端同时分配了 IPv4 和 IPv6 地址。您的客户端应用程序必须在同时启用 IPv4 和 IPv6 寻址并正确配置的子网中运行。检查您的 VPC 是否同时具有 IPv4 CIDR 块和关联的 IPv6 CIDR 块，确认您的子网同时启用了 IPv4 和 IPv6 地址，并验证您的 EC2 实例或客户端环境是否同时 IPv4 分配了地址和地址。 IPv6 有关更多信息，请参阅 Amazon VPC 用户指南中的[您的 VPCs 和子网的 IP 地址](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html)。
1. 确保安全组的入站和出站规则中存在相关 IPv6 端口。添加入站规则以允许来自您的 IPv6 地址的集群端口上的流量，并配置出站规则以允许 IPv6 流量。有关具体的端口号，请参阅 MSK 文档中的[端口信息](https://docs.aws.amazon.com/msk/latest/developerguide/port-info.html)。如果在双堆栈模式下运行 IPv4 ，请记住更新两者的 IPv6 规则。有关安全组及其入站和出站规则的更多信息，请参阅《Amazon VPC 用户指南》中的[您的 VPC 的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html)。
1. 确保 JVM 属性配置正确以获得 IPv6 支持。在您的客户端应用程序中，设置`java.net.preferIPv6Addresses`为`true`和`java.net.preferIPv4Stack`为`false`。这些设置可以配置为系统属性或 JVM 参数。进行这些更改后，请重新启动应用程序以使其生效。
## 无法从内部访问集群 AWS：网络问题
如果您的 Apache Kafka 应用程序无法与 MSK 集群成功通信，可以先执行以下连接测试。
1. 使用[获取 Amazon MSK 集群的引导代理](msk-get-bootstrap-brokers.md)中介绍的方法之一获取引导代理的地址。
1. 在以下命令中，*bootstrap-broker*替换为您在上一步中获得的经纪人地址之一。如果集群设置为使用 TLS 身份验证，则替换*port-number*为 9094。如果集群不使用 TLS 身份验证，请*port-number*替换为 9092。从客户端计算机运行命令。
```
telnet bootstrap-broker port-number
```
其中 port-number 为：
+ 如果将集群设置为使用 TLS 身份验证，则为 9094。
+ 如果集群不使用 TLS 身份验证则为 9092。
+ 如果启用了公共访问，则需要其他端口号。
从客户端计算机运行命令。
1. 对所有引导代理重复运行上面的命令。
如果客户端计算机能够访问代理，则表示没有连接问题。在这种情况下，可以运行以下命令来检查 Apache Kafka 客户端是否设置正确。要获取*bootstrap-brokers*，请使用中描述的任何方法[获取 Amazon MSK 集群的引导代理](msk-get-bootstrap-brokers.md)。*topic*替换为主题的名称。
```
/bin/kafka-console-producer.sh --broker-list bootstrap-brokers --producer.config client.properties --topic topic
```
如果上一个命令成功，则表示客户端设置正确。如果仍然无法从应用程序创建和使用，请在应用程序级别调试问题。
如果客户端计算机无法访问代理，请参阅以下几个小节，获得关于客户端计算机设置的指导。
### 同一 VPC 中的 Amazon EC2 客户端和 MSK 集群
如果客户端计算机与 MSK 集群位于同一 VPC 中，请确保集群安全组具有接受来自客户端计算机安全组的流量的入站规则。有关设置这些规则的信息，请参阅[安全组规则](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)。有关如何从与集群位于同一 VPC 中的 Amazon EC2 实例访问集群的示例，请参阅[开始使用 Amazon MSK](getting-started.md)。
### Amazon EC2 客户端和 MSK 集群不同 VPCs
如果客户机和群集处于两个不同的位置 VPCs，请确保满足以下条件：
+ 两者互 VPCs 相监视。
+ 对等连接处于活动状态。
+ 两者的路由表设置 VPCs 正确。
有关 VPC 对等连接的信息，请参阅[使用 VPC 对等连接](https://docs.aws.amazon.com/vpc/latest/peering/working-with-vpc-peering.html)。
### 本地客户端
如果本地客户端设置为使用连接到 MSK 集群 Site-to-Site VPN，请确保满足以下条件：
+ VPN 连接状态为 `UP`。有关如何检查 VPN 连接状态的信息，请参阅[如何检查 VPN 隧道的当前状态？](https://aws.amazon.com/premiumsupport/knowledge-center/check-vpn-tunnel-status/)。
+ 集群 VPC 的路由表包含目标格式为 `Virtual private gateway(vgw-xxxxxxxx)` 的本地 CIDR 的路由。
+ MSK 集群的安全组允许端口 2181、端口 9092（如果您的集群接受明文流量）和端口 9094（如果您的集群接受 TLS 加密的流量）上的流量传输。
有关更多 Site-to-Site VPN 故障排除指南，请参阅 [Client VPN 故障排除](https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/troubleshooting.html)。
### Direct Connect
如果客户端使用 Direct Connect，请参阅[故障排除 Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Troubleshooting.html)。
如果上述问题排查指导未能解决此问题，请确保没有防火墙阻止网络流量。若要进一步调试，请使用 `tcpdump` 和 `Wireshark` 等工具来分析流量，并确保流量到达 MSK 集群。
## 身份验证失败：连接次数过多
`Failed authentication ... Too many connects` 错误表明代理正在保护自己，因为一个或多个 IAM 客户端正试图以激进的速度连接到它。为帮助代理接受更高的新 IAM 连接速率，您可以增加 [https://kafka.apache.org/documentation/#producerconfigs_reconnect.backoff.ms](https://kafka.apache.org/documentation/#producerconfigs_reconnect.backoff.ms) 配置参数。
要详细了解每个代理的新连接的速率限制，请参阅 [Amazon MSK 限额](limits.md)页面。
## 身份验证失败：会话时间太短
当客户端尝试使用即将过期的 IAM 凭证连接到集群时，就会发生 `Failed authentication ... Session too short` 错误。请务必检查 IAM 凭证的刷新方式。最有可能的原因是，替换凭证的时间太接近会话到期时间，这会导致服务器端出现问题和身份验证失败。
## MSK Serverless：集群创建失败
如果您尝试创建 MSK Serverless 集群，但工作流程失败，则您可能无权创建 VPC 端点。通过允许 `ec2:CreateVpcEndpoint` 操作，验证您的管理员是否已授予您创建 VPC 端点的权限。
有关执行所有 Amazon MSK 操作所需的完整权限列表，请参阅 [AWS 托管策略：Amazon A MSKFull ccess](security-iam-awsmanpol-AmazonMSKFullAccess.md)。
## 无法 KafkaVersionsList 在 MSK 配置中更新
更新[AWS::MSK::Configuration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-msk-configuration.html)资源中的[KafkaVersionsList](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-msk-configuration.html#cfn-msk-configuration-kafkaversionslist)属性时，更新失败并显示以下错误。
```
Resource of type 'AWS::MSK::Configuration' with identifier '' already exists.
```
更新`KafkaVersionsList`属性时，在删除旧配置之前，使用更新的属性 AWS CloudFormation 重新创建新配置。 CloudFormation 堆栈更新失败，因为新配置使用的名称与现有配置相同。这样的更新需要[替换资源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)。要成功更新 `KafkaVersionsList`，还必须在同一操作中更新[名称](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-msk-configuration.html#cfn-msk-configuration-name)属性。
此外，如果您的配置附加到使用 AWS 管理控制台 或创建的任何群集 AWS CLI，请将以下内容添加到您的配置资源中，以防止[资源删除尝试失败](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html#troubleshooting-errors-resource-removed-not-deleted)。
```
UpdateReplacePolicy: Retain
```
更新成功后，请转至 Amazon MSK 控制台并删除旧配置。有关 MSK 配置的信息，请参阅 [预置 Amazon MSK 配置](msk-configuration.md)。