本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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 Provisioned 提供兩種代理程式類型 - Standard 和 Express。標準型代理程式提供設定叢集的最大靈活性，快速型代理程式則為執行高效能串流應用程式提供更高的彈性、輸送量、恢復能力和易用性。
如需每個產品的詳細資訊，請參閱下列主題。下表也會反白顯示 Standard 和 Express 代理程式之間的主要功能比較。
| 功能 | 標準代理程式 | 快速代理程式 |
| --- | --- | --- |
| [儲存管理](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) | 加密、私有/公開存取、身分驗證和授權 - IAM、SASL/SCRAM、mTLS、純文字、Kafka ACLs | 加密、私有/公開存取、身分驗證和授權 - IAM、SASL/SCRAM、mTLS、純文字、Kafka ACLs |
| [監控](monitoring.md) | CloudWatch、開放監控 | CloudWatch、開放監控 |
**注意**
您無法使用 MSK API 切換代理程式類型，將 MSK 佈建叢集從標準代理程式類型變更為快速代理程式類型。您必須使用所需的代理程式類型 （標準或快速） 建立新的叢集。
**Topics**
+ [Amazon MSK 標準代理程式](msk-broker-types-standard.md)
+ [Amazon MSK Express 代理程式](msk-broker-types-express.md)
# Amazon MSK 標準代理程式
MSK Provisioned 的標準代理程式提供最大的彈性來設定叢集的效能。您可以選擇各種叢集組態，以實現應用程式所需的可用性、耐用性、輸送量和延遲特性。您也可以佈建儲存容量，並視需要增加儲存容量。Amazon MSK 會處理標準代理程式和連接儲存資源的硬體維護，並自動修復可能發生的硬體問題。您可以在本文件中找到與標準代理程式相關的各種主題的詳細資訊，包括[儲存管理](msk-storage-management.md)、[組態](msk-configuration-standard.md)[和維護](patching-impact.md#patching-standard-brokers)的主題。
# Amazon MSK Express 代理程式
MSK Provisioned 的快速代理程式可讓 Apache Kafka 更輕鬆地管理、更符合成本效益地大規模執行，以及具有您預期低延遲的彈性。中介裝置包含pay-as-you-go儲存，可自動擴展，不需要調整大小、佈建或主動監控。根據選取的執行個體大小，每個代理程式節點可以提供每個代理程式高達 3 倍的輸送量、擴展到 20 倍的速度，以及比標準 Apache Kafka 代理程式更快 90% 的復原速度。快速代理程式預先設定了 Amazon MSK 的最佳實務預設值，並強制執行用戶端輸送量配額，將用戶端與 Kafka 背景操作之間的資源爭用降至最低。
以下是使用 Express 代理程式時需要考慮的一些關鍵因素和功能。
+ **無儲存管理**：快速代理程式不需要[佈建或管理任何儲存資源](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)的章節。
+ **更高的輸送量**：快速代理程式為每個代理程式提供比標準代理程式多 3 倍的輸送量。例如，與同等標準代理程式上的 153.8 MBps 相比，每個 m7g.16xlarge 大小的 Express 代理程式可以安全地寫入高達 500 MBps 的資料 （兩個數字都假設對背景操作進行足夠的頻寬分配，例如複寫和重新平衡）。
+ **設定為高彈性**：快速代理程式會自動提供各種最佳實務，以改善叢集的彈性。其中包括關鍵 Apache Kafka 組態的護欄、輸送量配額，以及背景操作和意外修復的容量保留。這些功能可讓您更安全、更輕鬆地執行大規模 Apache Kafka 應用程式。如需[Amazon MSK Express 代理程式配額](limits.md#msk-express-quota)詳細資訊，請參閱 [快速代理程式組態](msk-configuration-express.md) 和 上的章節。
+ **無維護時段**：Express 代理程式沒有維護時段。Amazon MSK 會持續自動更新您的叢集硬體。如需詳細資訊，請參閱[適用於 Express 代理程式的修補](https://docs.aws.amazon.com/msk/latest/developerguide/patching-impact.html#patching-express-brokers)。
## Express 代理程式的其他資訊
+ 快速代理程式使用 Apache Kafka APIs，但尚未完全支援 KStreams API。
+ 快速代理程式僅適用於 3AZs組態。
+ 快速代理程式僅適用於特定執行個體大小。如需更新清單，請參閱 [Amazon MSK 定價](https://aws.amazon.com/msk/pricing/)。
+ 下列 Apache Kafka 版本支援快速代理程式：3.6、3.8 和 3.9。
+ 可以使用 Apache Kafka 3.9 版以上的 KRaft 模式建立快速代理程式。
**請參閱這些部落格**
如需 MSK Express 代理程式的詳細資訊，以及查看使用中 Express 代理程式的實際範例，請閱讀下列部落格：
[推出適用於 Amazon MSK 的 Express 代理程式，為您的 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/)
此部落格示範 Express 代理程式如何：
提供更快的輸送量、快速擴展，以及改善故障的復原時間
消除儲存管理複雜性
# Amazon MSK 代理程式大小
當您建立 Amazon MSK 佈建叢集時，您可以指定要擁有的代理程式大小。根據[代理程式類型](broker-instance-types.md)，Amazon MSK 支援下列代理程式大小。
**標準代理程式大小**
+ 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 代理程式使用 AWS Graviton 處理器 (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 執行個體大小，請參閱 [Amazon EC2 一般用途執行個體](https://aws.amazon.com/ec2/instance-types/)。
+ T3 中介裝置有能力使用 CPU 信用來暫時爆增性能。如果您正在測試中小型串流工作負載，或如果您有低輸送量串流工作負載，會遇到暫時性尖峰的輸送量，請使用 T3 中介裝置進行低成本開發。我們建議您執行概念驗證測試，以判斷 T3 中介裝置是否足以進行生產或重要的工作負載。若要進一步了解 T3 代理程式大小，請參閱 [Amazon EC2 T3 執行個體](https://aws.amazon.com/ec2/instance-types/t3/)。
如需如何選擇代理程式大小的詳細資訊，請參閱[標準和快速代理程式的最佳實務](bestpractices-intro.md)。
# 標準代理程式的儲存管理
Amazon MSK 提供的功能可協助您在 MSK 叢集上進行儲存管理。
**注意**
使用 [Express 代理程式](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 Standard 代理程式儲存](msk-update-storage.md)
+ [管理 Amazon MSK 叢集中標準代理程式的儲存輸送量](msk-provision-throughput-management.md)
# 標準代理程式的分層儲存
分層儲存是 Amazon MSK 的低成本儲存層級，可擴展到幾乎無限制的儲存空間，讓建置串流資料應用程式具有成本效益。
您可以建立設定了分層儲存的 Amazon MSK 叢集，平衡效能和成本。Amazon MSK 會將串流資料儲存在效能最佳化的主要儲存層中，直到資料達到 Apache Kafka 主題保留期限為止。然後，Amazon MSK 會自動將資料移入新的低成本儲存層。
當您的應用程式開始從分層儲存讀取資料時，您可以預期前幾個位元組的讀取延遲會增加。當您開始從低成本儲存層依序讀取剩餘資料時，您可以預期與主要儲存層近似的延遲。您不需要針對低成本分層儲存佈建任何儲存，也不需要管理基礎設施。您可儲存任意數量的資料，只需按實際使用量付費。此功能與 [KIP-405: Kafka Tiered Storage](https://cwiki.apache.org/confluence/display/KAFKA/KIP-405%3A+Kafka+Tiered+Storage) 中介紹的 API 相容。
如需有關調整 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 API，以舊資料的精確生產順序重新處理舊資料。
+ 由於次要儲存上的資料不需要跨代理程式磁碟進行複寫，因此分區重新平衡的速度會更快。
+ 代理程式與分層儲存之間的資料會在 VPC 內移動，不會透過網際網路傳輸。
+ 用戶端機器可以使用相同的程序連線至已啟用分層儲存的新叢集，就像連線到未啟用分層儲存的叢集一樣。請參閱[建立用戶端機器](https://docs.aws.amazon.com/msk/latest/developerguide/create-client-machine.html)。
## Amazon MSK 叢集的分層儲存需求
+ 您必須使用 Apache Kafka 用戶端 3.0.0 或更高版本，才能建立已啟用分層儲存的新主題。若要將現有主題轉換到分層儲存，您可以重新設定使用 3.0.0 以下版本 (支援的 Apache Kafka 最低版本為 2.8.2.tiered) Kafka 用戶端的用戶端機器，以啟用分層儲存。請參閱 [步驟 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 (US) 區域。
+ 分層儲存僅適用於佈建類型叢集。
+ 分層儲存不支援代理程式大小 t3.small。
+ 低成本儲存的最短保留期間為 3 天。主要儲存沒有最短保留期間。
+ 分層儲存不支援在代理程式上使用多日誌目錄 (JBOD 相關功能)。
+ 分層儲存不支援壓縮主題。確定已開啟分層儲存的所有主題都已將其 cleanup.policy 設定為僅限「DELETE」。
+ 分層儲存叢集不支援在建立主題之後變更主題的 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.retention.ms 設定為 2 天。以下是一個區段到期時的事件序列。
**時間 T0 - 啟用分層儲存之前。**
在您啟用此主題的分層儲存之前，有兩個日誌區段。其中一個區段在現有主題分區 0 中處於作用中狀態。
![\[時間 T0 - 啟用分層儲存之前。\]](http://docs.aws.amazon.com/zh_tw/msk/latest/developerguide/images/tiered-storage-segments-1.png)
**時間 T1 (< 2 天) - 已啟用分層儲存。將區段 0 複製到分層儲存。**
啟用本主題的分層儲存後，Apache Kafka 會在關閉日誌區段 0 時立即將其複製到分層儲存。區段會根據 segment.bytes 或 segment.ms 設定關閉，而不是根據保留設定。Apache Kafka 也會在主要儲存體中保留副本。作用中區段 1 不符合複製到分層儲存的資格，因為它仍然作用中且尚未關閉。在此時間軸中，Amazon MSK 尚未針對區段 0 和區段 1 中的任何訊息套用任何保留設定。(local.retention.bytes/ms，https：//retention.ms/bytes)
![\[時間 T1 (< 2 天) - 已啟用分層儲存。將區段 0 複製到分層儲存。\]](http://docs.aws.amazon.com/zh_tw/msk/latest/developerguide/images/tiered-storage-segments-2.png)
**時間 T2 - 本機保留生效。**
2 天後，達到區段 0 的本機保留閾值。local.retention.ms 為 2 天的設定決定了這一點。區段 0 現在已從主要儲存體中刪除，但仍可在分層儲存體中使用。請注意，區段 0 已在時間 T1 關閉時複製到分層儲存，而不是在本機保留過期時複製到時間 T2。作用中區段 1 不符合刪除資格，也不符合複製到分層儲存的資格，因為它仍然處於作用中狀態。
![\[時間 T2 - 本機保留生效。\]](http://docs.aws.amazon.com/zh_tw/msk/latest/developerguide/images/tiered-storage-segments-3.png)
**時間 T3 - 整體保留生效。**
5 天後，保留設定生效，Kafka 會從分層儲存中清除日誌區段 0 及關聯的訊息。區段 1 既不符合到期資格，也尚未符合複製到分層儲存的資格，因為區段 1 處於作用中狀態。區段 1 尚未關閉，因此不符合區段滾動的資格。
![\[時間 T3 - 整體保留生效。\]](http://docs.aws.amazon.com/zh_tw/msk/latest/developerguide/images/tiered-storage-segments-4.png)
# 使用 建立具有分層儲存的 Amazon MSK 叢集 AWS 管理主控台
此程序說明如何使用 建立分層儲存 Amazon MSK 叢集 AWS 管理主控台。
1. 開啟位於 [https://console.aws.amazon.com/msk/](https://console.aws.amazon.com/msk/) 的 Amazon MSK 主控台。
1. 選擇 **Create Cluster** (建立叢集)。
1. 選擇**自訂建立**，以便設定分層儲存。
1. 指定叢集的名稱。
1. 在**叢集類型**中，選取**佈建**。
1. 選擇一個支援分層儲存的 Amazon Kafka 版本以供 Amazon MSK 用於建立叢集。
1. 指定 **kafka.t3.small** 以外的中介裝置大小。
1. 選取您想要 Amazon MSK 在每個可用區域中建立的代理程式數量。下限為每個可用區域 1 個代理程式，上限為每個叢集 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 可以複製的位元組數量。如需有關支援組態屬性的詳細資訊，請參閱[主題層級組態](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 用戶端版本。
# 使用 CLI 在現有 Amazon MSK AWS 叢集上啟用分層儲存
**注意**
您只能在叢集的 log.cleanup.policy 設定為 `delete` 時啟用分層儲存，因為在分層儲存上不支援壓縮主題。您可以稍後將個別主題的 log.cleanup.policy 設定為 `compact` (如果該特定主題還未啟用分層儲存)。如需有關支援組態屬性的詳細資訊，請參閱[主題層級組態](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 叢集上的分層儲存
此程序說明如何使用 更新分層儲存 Amazon MSK 叢集 AWS 管理主控台。
請確定 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` (如果該特定主題還未啟用分層儲存)。如需有關支援組態屬性的詳細資訊，請參閱[主題層級組態](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 Standard 代理程式儲存
您可以增加每個代理程式的 EBS 儲存體數量。您無法減少儲存空間。
在此向上擴展操作期間，儲存磁碟區仍然可供使用。
**重要**
擴展 MSK 叢集的儲存後，會立即提供額外的儲存。但是，在每個儲存擴展事件之後，叢集都需要一段冷卻期間。Amazon MSK 會在此冷卻期間最佳化叢集，然後才能再次擴展叢集。此冷卻期間從最少 6 小時到 24 小時以上不等，具體取決於叢集的儲存大小、使用率以及流量。這適用於自動擴展事件和使用 [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 使用自動擴展之前，應考慮以下事項：
+
**重要**
儲存擴展動作只能每六小時執行一次。
我們建議您根據自己的儲存需求，從適當調整儲存磁碟區的大小開始。如需有關適當調整叢集大小的指引，請參閱[正確調整叢集大小：每個叢集的標準代理程式數量](bestpractices.md#brokers-per-cluster)。
+ Amazon MSK 不會為因為使用量的降低而減少叢集儲存容量。Amazon MSK 不支援降低儲存磁碟區的大小。如果您需要降低叢集儲存的大小，則必須將現有叢集遷移至儲存容量較小的叢集。如需有關遷移叢集的相關資訊，請參閱[遷移至 MSK 叢集](migration.md)。
+ Amazon MSK 在亞太區域 （大阪）、非洲 （開普敦） 和亞太區域 （馬來西亞） 區域不支援自動擴展。
+ 將自動擴展政策與叢集建立關聯後，Amazon EC2 Auto Scaling 會自動建立用於目標追蹤的 Amazon CloudWatch 警示。如果刪除具有自動擴展政策的叢集，則此 CloudWatch 警示仍會持續存在。若要刪除 CloudWatch 警示，您應該先將自動擴展政策從叢集中移除，然後再刪除叢集。若要進一步了解目標追蹤，請參閱 *Amazon EC2 Auto Scaling User Guide* 中的 [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 可為代理程式儲存容量設定的擴展上限。您可以將每個代理程式的儲存容量上限設為 16 TiB。如需詳細資訊，請參閱[Amazon MSK 配額](limits.md)。
當 Amazon MSK 偵測到 `Maximum Disk Utilization` 指標等於或大於 `Storage Utilization Target` 設定值時，它增加的儲存容量等於兩個數字中的較大者：10 GiB 或目前儲存容量的 10%。例如，如果您有 1000 GiB，則該增加容量為 100 GiB。此服務會每分鐘檢查儲存使用率。進一步擴展操作會持續增加儲存容量，增加容量等於兩個數字中的較大者：10 GiB 或目前儲存容量的 10%。
若要判斷是否已發生自動擴展操作，請使用 [ListClusterOperations](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-operations.html#ListClusterOperations) 操作。
# 為您的 Amazon MSK 叢集設定自動擴展
您可以使用 Amazon MSK 主控台、Amazon MSK API 或 CloudFormation 來實作儲存體的自動擴展。可透過 [Application Auto Scaling](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-applicationautoscaling-scalabletarget.html) 取得 CloudFormation 支援。
**注意**
您無法在建立叢集時實作自動擴展。您必須先建立叢集，然後為叢集建立並啟用自動擴展政策。不過，您可以在 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. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/) 開啟 Amazon MSK 主控台。
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
執行下列命令，使用您在建立叢集時獲得的 Amazon Resource Name (ARN) 取代 *ClusterArn*。若您沒有叢集的 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) 操作或 [describe-cluster](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI 命令。範例版本為`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 輸出輸送量都較高。
對於 10 GiB 或更大的磁碟區，您可以佈建每秒 250 MiB 或更高的儲輸送量。預設為每秒 250 MiB。若要佈建儲存輸送量，您必須選擇代理程式大小 kafka.m5.4xlarge 或更大 （或 kafka.m7g.2xlarge 或更大），而且您可以指定最大輸送量，如下表所示。
****
| 代理程式大小 | 儲存輸送量上限 (MiB/秒) |
| --- | --- |
| 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 小時才能生效，如果來源磁碟區並未充分利用，則可能需要更長的時間。不過，轉換磁碟區效能至少等同於遷移期間來源儲存磁碟區的效能。充分利用的 1 TiB 磁碟區通常需要大約六個小時才能遷移至更新的組態。
# 為 Amazon MSK 叢集中的標準代理程式佈建儲存輸送量
Amazon MSK 代理程式會將資料保留在儲存磁碟區上。當生產者寫入叢集、代理程式之間複寫資料，以及在取用者讀取不在記憶體中的資料時，就會取用儲存空間 I/O。磁碟區儲存輸送量是指將資料寫入儲存磁碟區和從儲存磁碟區讀取資料的速率。佈建儲存輸送量功能可在叢集中指定代理程式的速率。
對於代理程式大小`kafka.m5.4xlarge`或更大的叢集，以及儲存磁碟區大小為 10 GiB 或更高的叢集，您可以指定每秒 MiB 的佈建輸送量速率。 GiB 您可以在建立叢集期間指定佈建輸送量。您也可以針對處於 `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 管理主控台
此程序顯示如何使用 AWS 管理主控台 建立已啟用佈建輸送量的 Amazon MSK 叢集的範例。
1. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)：// 開啟 Amazon MSK 主控台。
1. 選擇 **Create Cluster** (建立叢集)。
1. 選擇**自訂建立**。
1. 指定叢集的名稱。
1. 在**儲存**區段中，選擇**啟用**。
1. 選擇每個代理程式的儲存輸送量值。
1. 選擇 VPC、區域、子網路和安全群組。
1. 選擇**下一步**。
1. 在**安全**步驟的底部，選擇**下一步**。
1. 在**監控和標籤**步驟的底部，選擇**下一步**。
1. 檢閱叢集設定，然後選擇**建立叢集**。
## 使用 佈建 Amazon MSK 叢集儲存輸送量 AWS CLI
此程序顯示如何使用 AWS CLI 建立已啟用佈建輸送量的叢集的範例。
1. 複製下方的 JSON 並貼到檔案中。以帳戶中的值取代子網路 ID 和安全群組 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 叢集時佈建儲存輸送量
若要在建立叢集時設定佈建儲存輸送量，請使用 [CreateClusterV2](https://docs.aws.amazon.com/MSK/2.0/APIReference/v2-clusters.html#CreateClusterV2)。
# 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)。
| 名稱 | 描述 |
| --- | --- |
| allow.everyone.if.no.acl.found | 如果要將此屬性設定為 false，請先確定您已為叢集定義 Apache Kafka ACL。如果將此屬性設定為 false，但卻並未先定義 Apache Kafka ACL，您就會失去對叢集的存取權。如果發生這種狀況，您可以再次更新組態並將此屬性設定為 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.after.max.mslog.message.timestamp.before.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 | 生產者將 ACK 設定為 `"all"` (或 `"-1"`) 時，min.insync.replicas 的值會指定寫入視為成功前，須接受的最小複本數量。若無法達成此最小值，則生產者會引發例外狀況 (NotEnoughReplicas 或 NotEnoughReplicasAfterAppend)。 您可以利用 min.insync.replicas 和 ACK 當中的值強制執行更大數量的耐久性保證。例如，您可以建立複寫係數為 3 的主題，將 min.insync.replicas 設定為 2，ACK 設為 `"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 會使用作業系統預設值。 |
| socket.request.max.bytes | 通訊端要求內的位元組數量上限。 |
| socket.send.buffer.bytes | 通訊端伺服器通訊埠的 SO\$1SNDBUF 緩衝區。您可以為此屬性設定的最小值為 -1。如果值為 -1，則 Amazon MSK 會使用作業系統預設值。 |
| transaction.max.timeout.ms | 交易的最大逾時值。若用戶端請求的交易時間超過此值，代理程式會在 InitProducerIdRequest 中傳回錯誤。如此可避免用戶端逾時時間過長，拖延取用者讀取交易中的主題。 |
| transaction.state.log.min.isr | 覆寫交易主題的 min.insync.replicas 組態。 |
| transaction.state.log.replication.factor | 交易主題的複寫係數。設定此屬性為更高的值，能增加可用性。在叢集大小符合此複寫係數要求前，內部主題建立會失敗。 |
| transactional.id.expiration.ms | 在交易協調器將交易 ID 視為過期之前，等待接收目前交易的交易狀態更新所用的時間 (毫秒)。此設定也會影響生產者 ID 過期時間，因為只要在指定生產者 ID 上次寫入後過了這麼多時間，該生產者 ID 就會過期。如果生產者 ID 的上次寫入由於主題的保留設定而被刪除，該生產者 ID 可能會提早過期。此屬性的最小值為 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 提供的組態屬性，您亦可動態設定無須重新啟動代理程式的叢集層級和代理程式層級的組態屬性。您可以動態設定某些組態屬性。這些是在 Apache Kafka 文件內[代理程式組態](https://kafka.apache.org/documentation/#brokerconfigs)下表格中未標記為唯讀的組態屬性。如需有關動態組態及範例命令的資訊，請參閱 Apache Kafka 文件中的 [Updating Broker Configs](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 Configuration](https://kafka.apache.org/documentation/#configuration)。
| 名稱 | 描述 | 非分層儲存叢集的預設值 | 已啟用分層儲存之叢集的預設值 |
| --- | --- | --- | --- |
| allow.everyone.if.no.acl.found | 如果沒有資源模式符合特定資源，資源就沒有相關聯的 ACL。在此情況下，若此屬性設定為 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 指示本機保留沒有限制。這對應於 -1 的 retention.ms/bytes 設定值。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 指示本機保留沒有限制。這對應於 -1 的 retention.ms/bytes 設定值。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.after.max.mslog.message.timestamp.before.max.ms和 。代理程式接收訊息的時間戳記與訊息中指定的時間戳記之最大允許差值。若 log.message.timestamp.type=CreateTime，且時間戳記差值超過此閾值，則訊息將被拒絕。若 log.message.timestamp.type=LogAppendTime，則此組態會被忽略。允許的時間戳記差值上限不應該大於 log.retention.ms，以避免不必要地頻繁滾動日誌。 | 9223372036854775807 | 86400000 表示 Kafka 2.8.2.tiered 和 Kafka 3.7.x 分層。 |
| log.segment.bytes | 單一日誌檔案的大小上限。 | 1073741824 | 134217728 |
| min.insync.replicas | 生產者將 ACK (生產者從 Kafka 代理程式獲取的確認) 值設定為 `"all"` (或 `"-1"`) 後，min.insync.replicas 的值會指定確認寫入視為成功前，須接受的複本數量下限。若未達到此下限，則生產者會引發例外狀況 (NotEnoughReplicas 或 NotEnoughReplicasAfterAppend)。 若同時使用 min.insync.replicas 和 ACK 的值，您可強制執行更大數量的耐用性保證。例如，您可以建立複寫係數為 3 的主題，將 min.insync.replicas 設定為 2，ACK 設為 `"all"` 來產生。若多數複本未接收寫入，如此可確保生產者會引發例外狀況。 | 如果是 3 個可用區域中的叢集，則是 2，如果是 2 個可用區域中的叢集，則是 1。 | 如果是 3 個可用區域中的叢集，則是 2，如果是 2 個可用區域中的叢集，則是 1。 |
| num.io.threads | 伺服器用於生產請求的執行緒數量，可能包含磁碟 I/O。 | 8 | 最大值 (8 個，vCPU)，vCPU 數量取決於代理程式的執行個體大小 |
| num.network.threads | 伺服器用來從網路接收請求並將回應傳送到網路的執行緒數量。 | 5 | 最大值 (5 個，vCPU/2 個)，vCPU 數量取決於代理程式的執行個體大小 |
| num.partitions | 每個主題的日誌磁碟分割預設數量。 | 1 | 1 |
| num.replica.fetchers | 用於從來源代理程式複寫訊息的擷取器執行緒數量。增加此值就可以增加追隨代理程式中的 I/O 平行處理程度。 | 2 | 最大值 (2 個，vCPU/4 個)，vCPU 數量取決於代理程式的執行個體大小 |
| remote.log.msk.disable.policy | 與 remote.storage.enable 搭配使用以停用分層儲存。將此政策設定為「刪除」即指示，當您將 remote.storage.enable 設定為 false 時，會刪除分層儲存中的資料。 | N/A | 無 |
| remote.log.reader.threads | 遠端日誌讀取器執行緒集區大小，用於排程從遠端儲存擷取資料的任務。 | N/A | 最大值 (10 個，vCPU \$1 0.67)，vCPU 數量取決於代理程式的執行個體大小 |
| 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 的值搭配 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，將採用 OS 預設值。 | 102400 | 102400 |
| socket.request.max.bytes | 通訊端要求內的位元組數量上限。 | 104857600 | 104857600 |
| socket.send.buffer.bytes | 通訊端伺服器通訊埠的 SO\$1SNDBUF 緩衝區。若此值為 -1，將採用 OS 預設值。 | 102400 | 102400 |
| unclean.leader.election.enable | 指示您是否不在 ISR 集中的複本作為領導者與最後手段，即使這可能會導致資料遺失。 | true | false |
| zookeeper.session.timeout.ms | 以毫秒為單位的 Apache ZooKeeper 工作階段逾時。 | 18000 | 18000 |
| zookeeper.set.acl | 設定使用安全 ACL的用戶端。 | false | false |
如需如何指定自訂組態值的資訊，請參閱 [自訂 Amazon MSK 組態](msk-configuration-properties.md)。
# Amazon MSK 分層儲存主題層級組態的指導方針
以下是您在主題層級設定分層儲存時的預設設定和限制。
+ 對於已啟用分層儲存的主題，Amazon MSK 不支援較小的日誌區段大小。如果您要建立區段，最小日誌區段大小為 48 MiB，或最小區段滾動時間為 10 分鐘。這些值會對應 segment.bytes 和 segment.ms 屬性。
+ local.retention.ms/bytes 的值不能等於或超過 retention.ms/bytes 的值。這是分層儲存保留設定。
+ local.retention.ms/bytes 的預設值為 -2。這意味著 retention.ms 的值會用於 local.retention.ms/bytes。在這種情況下，資料會同時保留在本機儲存和分層儲存 (每個儲存中一個副本) 中，而且會同時過期。對於此選項，本機資料的副本會保留至遠端儲存。在這種情況下，從取用流量讀取的資料來自本地儲存。
+ retention.ms 的預設值為 7 天。retention.bytes 沒有預設大小限制。
+ retention.ms/bytes 的最小值為 -1。這意味著無限保留。
+ local.retention.ms/bytes 的最小值為 -2。這意味著在本地儲存中無限保留。它與 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 Express 代理程式組態 （讀取/寫入存取）](msk-configuration-express-read-write.md)
+ [Express 代理程式唯讀組態](msk-configuration-express-read-only.md)
# 自訂 MSK Express 代理程式組態 （讀取/寫入存取）
您可以使用 Amazon MSK 的更新組態[功能或使用 Apache Kafka 的 AlterConfig API 來更新讀取/寫入代理程式組態](msk-update-cluster-config.md)。 AlterConfig Apache Kafka 代理程式組態為靜態或動態。靜態組態需要重新啟動代理程式才能套用組態，而動態組態則不需要重新啟動代理程式。如需組態屬性和更新模式的詳細資訊，請參閱[更新代理程式組態](https://kafka.apache.org/documentation/#dynamicbrokerconfigs)。
**Topics**
+ [MSK Express 代理程式上的靜態組態](#msk-configuration-express-static-configuration)
+ [Express Brokers 上的動態組態](#msk-configuration-express-dynamic-configuration)
+ [Express Brokers 上的主題層級組態](#msk-configuration-express-topic-configuration)
## MSK Express 代理程式上的靜態組態
您可以使用 Amazon MSK 建立自訂 MSK 組態檔案，以設定下列靜態屬性。Amazon MSK 會設定和管理您未設定的所有其他屬性。您可以從 MSK 主控台或使用組態[命令建立和更新靜態組態](msk-configuration-operations-create.md)檔案。
| 屬性 | Description | 預設值 |
| --- | --- | --- |
| allow.everyone.if.no.acl.found | 如果您想要將此屬性設定為 false，請先確定您為叢集定義 Apache Kafka ACLs。如果您將此屬性設定為 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 地址允許的連線數上限。0 如果使用 max.connections.per.ip.overrides 屬性設定覆寫，這可以設定為 。如果達到限制，則會捨棄來自 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，將採用 OS 預設值。 | 102400 |
| socket.request.max.bytes | 通訊端要求內的位元組數量上限。 | 104857600 |
| socket.send.buffer.bytes | 通訊端伺服器通訊埠的 SO\$1SNDBUF 緩衝區。若此值為 -1，將採用 OS 預設值。 | 102400 |
| transaction.max.timeout.ms | 交易的最大逾時值。若用戶端請求的交易時間超過此值，代理程式會在 InitProducerIdRequest 中傳回錯誤。如此可避免用戶端逾時時間過長，拖延取用者讀取交易中的主題。 | Apache Kafka 預設 |
| transactional.id.expiration.ms | 在交易協調器將交易 ID 視為過期之前，等待接收目前交易的交易狀態更新所用的時間 (毫秒)。此設定也會影響生產者 ID 過期，因為它會導致生產者 IDs 在具有指定生產者 ID 的最後一次寫入後經過此時間時過期。如果生產者 ID 的上次寫入由於主題的保留設定而被刪除，該生產者 ID 可能會提早過期。此屬性的最小值為 1 毫秒。 | Apache Kafka 預設 |
## Express Brokers 上的動態組態
您可以使用 Apache Kafka AlterConfig API 或 Kafka-configs.sh 工具來編輯下列動態組態。Amazon MSK 會設定和管理您未設定的所有其他屬性。您可以動態設定不需要重新啟動代理程式的叢集層級和代理程式層級組態屬性。
| 屬性 | Description | 預設值 |
| --- | --- | --- |
| 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 | 為日誌壓縮主題保留刪除 tombstone 標記的時間量。如果取用者從位移 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 | 中介裝置隨時允許的連線數上限。除了使用 設定的任何每個 IP 限制之外，也會套用此限制`max.connections.per.ip`。 | Apache Kafka 預設 |
| max.connections.per.ip | 每個 IP 地址允許的連線數上限。`0` 如果使用 max.connections.per.ip.overrides 屬性設定覆寫，則可以將此設定為 。如果達到限制，則會捨棄來自 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 之前等待的時間，以毫秒為單位。當與其相關聯的交易仍在進行中時，生產者 IDs 不會過期。請注意，如果由於主題IDs保留設定而刪除生產者 ID 的最後一次寫入，生產者 ID 可能會更快過期。將此值設定為等於或高於 `delivery.timeout.ms` ，有助於防止重試期間過期，並防止訊息重複，但對於大多數使用案例，預設值應該是合理的。 | Apache Kafka 預設 |
## Express Brokers 上的主題層級組態
您可使用 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)。
| 屬性 | Description |
| --- | --- |
| cleanup.policy | 此組態會指定要在日誌區段上使用的保留政策。「刪除」政策 （預設為預設值） 會在達到保留時間或大小限制時捨棄舊區段。「壓縮」政策將啟用日誌壓縮，這會保留每個金鑰的最新值。您也可以在逗號分隔清單中指定這兩個政策 （例如，「delete，compact」)。在此情況下，會根據保留時間和大小組態捨棄舊區段，而保留區段則會壓縮。在分割區中的資料達到 256 MB 之後，就會觸發 Express 代理程式上的壓縮。 |
| compression.type | 指定指定主題的最終壓縮類型。此組態接受標準壓縮轉碼器 (`gzip`、`snappy`、`lz4`、`zstd`)。此外，它會接受相當於沒有壓縮`uncompressed`的 ；`producer`這表示 會保留生產者設定的原始壓縮轉碼器。 |
| delete.retention.ms | 為日誌壓縮主題保留刪除 tombstone 標記的時間量。如果取用者從位移 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 Default |
| max.compaction.lag.ms | 訊息在日誌中仍不符合壓縮資格的時間上限。此設定僅適用於正在壓縮的日誌。此組態將限制在 【7 天，Long.Max】 的範圍內。 此設定的預設值為 9223372036854775807，Apache Kafka Default。 |
| retention.bytes | 此組態控制如果我們使用「刪除」保留政策，在我們捨棄舊日誌區段以釋放空間之前，分割區 （由日誌區段組成） 可以成長到的最大大小。根據預設，沒有只有時間限制的大小限制。由於此限制是在分割區層級強制執行，請將此限制乘以分割區數量，以位元組為單位計算主題保留。此外， 獨立於 `segment.ms`和 `segment.bytes`組態`retention.bytes configuration`運作。此外，如果 `retention.bytes` 設定為零，它會觸發新客群的滾動。 |
| retention.ms | 若我們使用「刪除」保留政策，則此組態會控制在捨棄舊日誌區段以釋放空間之前保留日誌的時間上限。這表示消費者必須多快讀取其資料的 SLA。如果設定為 `-1`，則不會套用時間限制。此外，`retention.ms`組態會獨立於 `segment.ms`和 `segment.bytes`組態運作。此外，如果滿足`retention.ms`條件，它會觸發新客群的滾動。 |
# Express 代理程式唯讀組態
Amazon MSK 會設定這些組態的值，並保護它們免受可能影響叢集可用性的變更。這些值可能會根據叢集上執行的 Apache Kafka 版本而變更，因此請記得檢查特定叢集中的值。
下表列出 Express 代理程式的唯讀組態。
| 屬性 | Description | Express Broker 值 |
| --- | --- | --- |
| broker.id | 此伺服器的中介裝置 ID。 | 1，2，3... |
| broker.rack | 代理程式的機架。這將用於容錯能力的機架感知複寫指派。範例：`RACK1`、`us-east-1d` | AZ 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 | 當生產者將 ack 設定為 `all`（或 `-1`) 時， 中的值會`min.insync.replicas`指定必須確認寫入才能視為成功的複本數目下限。如果無法達到此最小值，生產者會引發例外狀況 ( `NotEnoughReplicas`或 `NotEnoughReplicasAfterAppend`)。 您可以使用生產者提供的 ack 值來強制執行更高的耐用性保證。透過將 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 vCPUs |
| 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， vCPUs |
| 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 Resource Name (ARN)。儲存此 ARN，因為其他命令須用其來參照此組態。若您遺失組態 ARN，可列出帳戶內的所有組態來找到它。
# 更新組態
此程序說明如何更新自訂 Amazon MSK 組態。
1. 建立一個檔案，在其中指定欲更新的組態屬性及欲指派的值。以下為範例組態檔案的內容。
```
auto.create.topics.enable = true
min.insync.replicas = 2
```
1. 執行下列 AWS CLI 命令，使用您在上一步中儲存組態的檔案路徑取代 *config-file-path*。
使用建立組態時取得的 ARN 取代 *configuration-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. 若要執行此範例，請使用建立組態時取得的 ARN 取代 *configuration-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`。
若要執行此範例，請使用建立組態時取得的 ARN 取代 *configuration-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`。
+ 執行下列命令，請使用建立組態時取得的 ARN 取代 *configuration-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 日起，支援 Amazon 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 MSK APIs 或 AWS 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 主控台或使用 AWS CLI、Amazon MSK APIs 或 AWS SDK 和 來執行此操作 AWS CloudFormation。當您變更代理程式計數時，Amazon MSK 會執行下列動作：
+ 自動將分割區分發給新的代理程式。
+ 從要移除的代理程式移動分割區。
當您向上和向下擴展叢集時，用戶端產生和使用資料的叢集可用性不會受到影響。
**Topics**
------
#### [ Scaling clusters using AWS 管理主控台 ]
1. 開啟 Amazon MSK 主控台，網址為 [https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-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 佈建叢集開啟。當您向上或向下擴展叢集時，Amazon MSK 會自動處理分割區管理，方法是將分割區分配到新的代理程式，並從代理程式移動分割區以移除。為了確保工作負載在代理程式間的最佳分佈，智慧型重新平衡會使用 Amazon MSK 最佳實務來判斷自動啟動代理程式重新平衡的閾值。
您可以視需要暫停和恢復穩定狀態重新平衡。穩定狀態重新平衡會持續監控您的叢集，並執行下列動作：
+ 追蹤中介裝置資源用量 (CPU、網路、儲存）。
+ 自動調整分割區放置，不會影響資料可用性。
+ 與標準代理程式相比，快速代理程式完成重新平衡操作的速度快上 180 倍。
+ 維護叢集效能。
**Topics**
------
#### [ Pause and resume steady state rebalancing in AWS 管理主控台 ]
1. 開啟 Amazon MSK 主控台，網址為 [https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-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 ]
若要**ACTIVE**使用 將叢集的重新平衡狀態設定為 AWS CLI，請使用 [update-rebalancing](https://docs.aws.amazon.com/cli/latest/reference/kafka/update-rebalancing.html) 命令，如下列範例所示。在此命令中，使用 `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 會定期更新叢集中代理程式上的軟體。維護包括計劃的更新或非計劃的修復。計劃維護包括作業系統更新、安全性更新，以及維護叢集運作狀態、安全性和效能所需的其他軟體更新。我們會執行意外維護，以解決突然的基礎設施降級。我們會對 Standard 和 Express 代理程式執行維護，但體驗不同。
## 標準代理程式的修補
如果您遵循[最佳實務](bestpractices.md)，標準代理程式的更新不會影響您應用程式的寫入和讀取。
Amazon MSK 使用軟體的滾動更新來維持叢集的高可用性。在此過程中，代理程式一次重新啟動一個，Kafka 會自動將領導力移至另一個線上代理程式。當您在 中 AWS 管理主控台 或透過 `DescribeClusterOperation`和 `ListClusterOperations` APIs 檢視叢集操作時，這些維護操作會以 的操作類型顯示`SECURITY_PATCHING`。Kafka 用戶端具有內建機制，可自動偵測分割區領導層的變更，並繼續將資料寫入 MSK 叢集並讀取。隨時遵循 [Apache Kafka 用戶端的最佳實務](bestpractices-kafka-client.md) 可順暢操作叢集，包括修補期間。
在代理程式離線後，在您的用戶端上看到暫時性中斷連線錯誤是正常的。您也將觀察 p99 讀取和寫入延遲 （通常為高毫秒，最多 \$12 秒） 中的短暫時段 （最多 2 分鐘，通常較少）。這些峰值是預期的，由用戶端重新連線至新的領導者代理程式所造成；這不會影響您的生產或消耗，並在重新連線後解決。如需詳細資訊，請參閱[中介裝置離線和用戶端容錯移轉](https://docs.aws.amazon.com/msk/latest/developerguide/troubleshooting-offlinebroker-clientfailover.html)。
您也會觀察到指標 的增加`UnderReplicatedPartitions`，因為已關閉的代理程式上的分割區不會再複寫資料。這不會影響應用程式寫入和讀取，因為在其他代理程式上託管的這些分割區複本現在正在處理請求。
軟體更新之後，當代理程式重新上線時，它需要「追上」離線時產生的訊息。在追趕期間，您可能會發現磁碟區輸送量和 CPU 的使用量增加。如果您在代理程式上有足夠的 CPU、記憶體、網路和磁碟區資源，這些應該不會影響寫入和讀取至叢集。
## 針對 Express 代理程式的修補
Express 代理程式沒有維護時段。Amazon MSK 會以時間分佈的方式持續自動更新叢集，這表示您可以在該月偶爾重新啟動單一代理程式。這可確保您不需要針對整個叢集的一次性維護時段制定任何計劃或調整。一如往常，流量在代理程式重新開機期間將保持不中斷，因為領導層將變更為會繼續提供請求的其他代理程式。當您在 中 AWS 管理主控台 或透過 `DescribeClusterOperation`和 `ListClusterOperations` APIs 檢視叢集操作時，這些維護操作會以 的操作類型顯示`BROKER_UPDATE`。
快速代理程式具有最佳實務設定和護欄，讓您的叢集能夠彈性地載入在維護期間可能發生的變更。Amazon MSK 會在您的 Express 代理程式上設定輸送量配額，以減輕叢集超載的影響，這可能會在代理程式重新啟動期間導致問題。當您使用 Express 代理程式時，這些改進功能不需要預先通知、規劃和維護時段。
快速代理程式一律以三種方式複寫資料，讓您的用戶端在重新啟動期間自動容錯移轉。您不需要擔心因為複寫因素設為 1 或 2 而無法使用主題。此外，追上重新啟動的 Express 代理程式比標準代理程式更快。Express 代理程式的修補速度越快，表示針對叢集排程的任何控制平面活動，規劃中斷越少。
與所有 Apache Kafka 應用程式一樣，用戶端連線至 Express 代理程式仍有共用的用戶端-伺服器合約。設定您的用戶端來處理代理程式之間的領導容錯移轉仍然至關重要。隨時遵循 [Apache Kafka 用戶端的最佳實務](bestpractices-kafka-client.md)來順暢操作叢集，包括在修補期間。在代理程式重新啟動後，[在您的用戶端上看到暫時性中斷連線錯誤](troubleshooting-offlinebroker-clientfailover.md)是正常的。這不會影響您的生產和使用，因為跟隨中介裝置將接管分割區領導。您的 Apache Kafka 用戶端會自動容錯移轉，並開始傳送請求給新的領導者代理程式。
# 中介裝置離線和用戶端容錯移轉
Kafka 允許離線代理程式；根據最佳實務，運作狀態良好且平衡的叢集中的單一離線代理程式不會看到影響或導致無法產生或取用。這是因為另一個代理程式會接管分割區領導，而且 Kafka 用戶端 lib 會自動容錯移轉，並開始傳送請求給新的領導代理程式。
**用戶端伺服器合約**
這會導致用戶端程式庫與伺服器端行為之間的共用合約；伺服器必須成功指派一或多個新領導者，而且用戶端必須變更代理程式，以便及時將請求傳送給新領導者。
Kafka 使用例外狀況來控制此流程：
**範例程序**
1. 中介裝置 A 進入離線狀態。
1. Kafka 用戶端會收到例外狀況 （通常是網路中斷連線或 not\$1leader\$1for\$1partition)。
1. 這些例外狀況會觸發 Kafka 用戶端更新其中繼資料，使其了解最新的領導者。
1. Kafka 用戶端會繼續將請求傳送給其他代理程式上的新分割區領導者。
此程序通常需要不到 2 秒的時間來使用 版本的 Java 用戶端和預設組態。用戶端錯誤是詳細且重複的，但不會引起關注，如「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 的生產/使用延遲 （通常是 100 年代的高毫秒）。超過此長度通常表示用戶端組態或伺服器端控制器載入發生問題。請參閱疑難排解一節。
檢查其他代理程式的 `BytesInPerSec`和 `LeaderCount`指標是否增加，證明流量和領導力如預期般移動，即可驗證成功的容錯移轉。您也將觀察到`UnderReplicatedPartitions`指標增加，當複本與關機代理程式離線時，預期會增加此指標。
**疑難排解**
上述流程可能會因為中斷用戶端-伺服器合約而中斷。最常見的問題原因包括：
+ 設定錯誤或不正確使用 Kafka 用戶端 lib。
+ 使用第三方用戶端 libs 的非預期預設行為和錯誤。
+ 控制器過載導致分割區領導指派速度變慢。
+ 正在選擇新的控制器，導致分割區領導指派速度變慢。
為了確保正確的行為來處理領導容錯移轉，我們建議：
+ 必須遵循伺服器端[最佳實務](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html)，以確保適當地擴展控制器代理程式，以避免緩慢的領導指派。
+ 用戶端程式庫必須啟用重試，以確保用戶端處理容錯移轉。
+ 用戶端程式庫必須設定 retry.backoff.ms （預設 100)，以避免連線/請求風暴。
+ 用戶端程式庫必須將 request.timeout.ms 和 delivery.timeout.ms 設定為符合應用程式 SLA 的值。較高的值會導致特定失敗類型的容錯移轉速度變慢。
+ 用戶端程式庫必須確保 bootstrap.servers 包含至少 3 個隨機代理程式，以避免對初始探索造成可用性影響。
+ 有些用戶端程式庫的層級低於其他程式庫，並期望應用程式開發人員自行實作重試邏輯和例外狀況處理。如需使用範例，請參閱用戶端 lib 特定文件，並確保遵循正確的重新連線/重試邏輯。
+ 我們建議監控生產的用戶端延遲、成功的請求計數，以及不可重試錯誤的錯誤計數。
+ 我們觀察到較舊的第三方 golang 和 ruby 程式庫在整個代理程式離線期間仍保持詳細，儘管 會產生和取用不受影響的請求。除了請求成功指標和錯誤之外，我們建議您一律監控業務層級指標，以判斷日誌中是否有實際影響與雜訊。
+ 客戶不應對網路/not\$1leader 的暫時性例外狀況發出警示，因為它們是正常的、不影響的，並且預期是 kafka 通訊協定的一部分。
+ 客戶不應在 UnderReplicatedPartitions 上發出警示，因為它們在單一離線代理程式期間是正常、無影響且預期的。
# Amazon MSK 的安全性
的雲端安全性 AWS 是最高優先順序。身為 AWS 客戶，您可以受益於資料中心和網路架構，這些架構專為滿足最安全敏感組織的需求而建置。
安全性是 AWS 與您之間的共同責任。[共同責任模式](https://aws.amazon.com/compliance/shared-responsibility-model/)將其描述為雲端*的*安全性，和雲端*中*的安全性：
+ **雲端的安全性** – AWS 負責保護在 AWS Cloud 中執行 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)
+ [Amazon MSK API 的身分驗證和授權](security-iam.md)
+ [Apache Kafka API 的身分驗證和授權](kafka_apis_iam.md)
+ [變更 Amazon MSK 叢集的安全群組](change-security-group.md)
+ [控制對 Amazon MSK 叢集中 Apache ZooKeeper 節點的存取](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/)適用於 Amazon Managed Streaming for Apache Kafka 中的資料保護。如此模型所述， AWS 負責保護執行所有 的全域基礎設施 AWS 雲端。您負責維護在此基礎設施上託管內容的控制權。您也同時負責所使用 AWS 服務 的安全組態和管理任務。如需資料隱私權的詳細資訊，請參閱[資料隱私權常見問答集](https://aws.amazon.com/compliance/data-privacy-faq/)。如需有關歐洲資料保護的相關資訊，請參閱*AWS 安全性部落格*上的[AWS 共同責任模型和 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 端點的更多相關資訊，請參閱[聯邦資訊處理標準 (FIPS) 140-3](https://aws.amazon.com/compliance/fips/)。
我們強烈建議您絕對不要將客戶的電子郵件地址等機密或敏感資訊，放在標籤或自由格式的文字欄位中，例如**名稱**欄位。這包括當您使用 Amazon MSK 或使用 AWS 服務 主控台、API AWS CLI或其他 AWS SDKs 時。您在標籤或自由格式文字欄位中輸入的任何資料都可能用於計費或診斷日誌。如果您提供外部伺服器的 URL，我們強烈建議請勿在驗證您對該伺服器請求的 URL 中包含憑證資訊。
**Topics**
+ [Amazon MSK 加密](msk-encryption.md)
+ [開始使用 Amazon MSK 加密](msk-working-with-encryption.md)
+ [搭配界面 VPC 端點使用 Amazon MSK APIs](privatelink-vpc-endpoints.md)
# Amazon MSK 加密
Amazon MSK 提供資料加密選項，您可以使用這些選項來符合嚴格的資料管理需求。Amazon MSK 用於加密的憑證必須每 13 個月更新一次。Amazon MSK 會自動更新所有叢集的這些憑證。當 Amazon MSK 啟動憑證更新操作時，快速代理程式叢集會保持 `ACTIVE` 狀態。對於標準代理程式叢集，Amazon MSK 會在叢集啟動 certificate-update 操作`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 加密的資料。
+ 只允許純文字資料。
Amazon MSK 代理程式使用公有 AWS Certificate Manager 憑證。因此，任何信任 Amazon 信任服務的信任存放區，也會信任 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`，您可以指定[客戶自管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)，或為您的帳戶中的 MSK 選擇 AWS 受管金鑰 (`alias/aws/kafka`)。如果您未指定 `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 組態的文件。下列是 範例。使用 Apache Kafka 用戶端版本取代 *\$1YOUR MSK VERSION\$1*。如需有關如何尋找 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 已安裝 的機器上執行下列命令，以叢集的 ARN 取代 *clusterARN*。
```
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)。
# 搭配界面 VPC 端點使用 Amazon MSK APIs
您可以使用介面 VPC 端點，由 AWS PrivateLink 提供支援，以防止 Amazon VPC 和 Amazon MSK APIs 之間的流量離開 Amazon 網路。介面 VPC 端點不需要網際網路閘道、NAT 裝置、VPN 連線或 AWS Direct Connect 連線。[AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) 是一種 AWS 技術，可讓您在 Amazon VPC 中使用具有私有 IPs彈性網路界面，在 AWS 服務之間進行私有通訊。如需詳細資訊，請參閱 [Amazon 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)。
您的應用程式可以使用 AWS PrivateLink 與 Amazon MSK Provisioned 和 MSK Connect APIs 連線。若要開始使用，請為您的 Amazon MSK API 建立介面 VPC 端點，以啟動透過介面 VPC 端點往返 Amazon 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 流量的雙堆疊端點服務包括：
+ aws.api.region.kafka-api
+ aws.api.region.kafka-api-fips （啟用 FIPS)
若要設定雙堆疊端點，您必須遵循[雙堆疊和 FIPS 端點](https://docs.aws.amazon.com/sdkref/latest/guide/feature-endpoints.html)準則。
其中 region 是您的區域名稱。選擇此服務名稱以使用 MSK 佈建相容的 APIs。如需詳細資訊，請參閱 https：//*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
其中 region 是您的區域名稱。選擇此服務名稱以使用 MSK Connect 相容 APIs。如需詳細資訊，請參閱《*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)。
## 控制對 Amazon MSK 佈建或 MSK Connect APIs 的 VPC 端點的存取
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"
}
}
}
]
}
```
------
# Amazon MSK API 的身分驗證和授權
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 Amazon 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 使用者指南*中的 [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 Resource Name (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 Resource Name (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": "*"
```
若要在單一陳述式中指定多項資源，請使用逗號分隔 ARN。
```
"Resource": ["resource1", "resource2"]
```
若要查看 Amazon MSK 資源類型及其 ARN 的清單，請參閱《IAM 使用者指南**》中的 [Amazon Managed Streaming for 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) 或 [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) 等 AWS STS API 操作來取得臨時安全登入資料。
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 政策，授與使用者和角色在指定資源上執行特定 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)** – 如果您的案例需要 IAM 使用者或 中的根使用者 AWS 帳戶，請開啟 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)。服務連結角色是直接連結至 Amazon MSK 的一種特殊 IAM 角色類型。服務連結角色是由 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 CLI或 AWS API 中建立 Amazon MSK 叢集時，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 Amazon 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 最有可能更新 AWS 受管政策。
如需詳細資訊，請參閱 *IAM 使用者指南*中的 [AWS 受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
# AWS 受管政策：AmazonMSKFullAccess
此政策會授予管理許可，允許主體完整存取所有 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 受管政策：AmazonMSKReadOnlyAccess
此政策授予唯讀許可，允許使用者檢視 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 受管政策的更新。
| 變更 | 描述 | Date |
| --- | --- | --- |
| [已將 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 Replicator 使用 IAM 身分驗證連線至叢集的許可。同時授予描述和更改叢集的許可。
+ **`topic`** – 准許 Amazon MSK Replicator 描述、建立和更改主題，以及更改主題的動態組態。
+ **`consumer group`** – 授予 Amazon MSK Replicator 許可，以描述和變更取用者群組、從 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/*/*"
]
}
]
}
```
------
# AWS 受管政策的 Amazon MSK 更新
檢視自此服務開始追蹤 Amazon MSK AWS 受管政策更新以來的詳細資訊。
| 變更 | 描述 | Date |
| --- | --- | --- |
| [新增至 AWSMSKReplicatorExecutionRole 的 WriteDataIdempotently 許可](security-iam-awsmanpol-AWSMSKReplicatorExecutionRole.md) – 更新現有政策 | Amazon MSK 已將 WriteDataIdempotently 許可新增至 AWSMSKReplicatorExecutionRole 政策，以支援 MSK 叢集之間的資料複寫。 | 2024 年 3 月 12 日 |
| [AWSMSKReplicatorExecutionRole](security-iam-awsmanpol-AWSMSKReplicatorExecutionRole.md) – 新政策 | Amazon MSK 新增 AWSMSKReplicatorExecutionRole 政策以支援 Amazon MSK Replicator。 | 2023 年 12 月 4 日 |
| [AmazonMSKFullAccess](security-iam-awsmanpol-AmazonMSKFullAccess.md)：更新至現有政策 | Amazon MSK 新增許可以支援 Amazon MSK Replicator。 | 2023 年 9 月 28 日 |
| [KafkaServiceRolePolicy](security-iam-awsmanpol-KafkaServiceRolePolicy.md)：更新至現有政策 | Amazon MSK 新增許可以支援多 VPC 私有連線。 | 2023 年 3 月 8 日 |
| [AmazonMSKFullAccess](security-iam-awsmanpol-AmazonMSKFullAccess.md)：更新至現有政策 | Amazon MSK 新增 Amazon EC2 許可，可以連線到叢集。 | 2021 年 11 月 30 日 |
| [AmazonMSKFullAccess](security-iam-awsmanpol-AmazonMSKFullAccess.md)：更新至現有政策 | 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 會請求管理員更新他的政策，允許他使用 `purchaseQueriesCluster` 動作存取 `kafka:DeleteCluster` 資源。
# Apache Kafka API 的身分驗證和授權
您可以使用 IAM 來對用戶端進行身分驗證，以及允許或拒絕 Apache Kafka 動作。也可以使用 TLS 或 SASL/SCRAM 來來對用戶端進行身分驗證，以及使用 Apache Kafka ACL 來允許或拒絕動作。
如需有關如何控制誰可以在叢集上執行 [Amazon MSK 操作](https://docs.aws.amazon.com/msk/1.0/apireference/operations.html)的相關資訊，請參閱 [Amazon MSK API 的身分驗證和授權](security-iam.md)。
**Topics**
+ [IAM 存取控制](iam-access-control.md)
+ [Amazon MSK 的相互 TLS 用戶端身分驗證](msk-authentication.md)
+ [使用 AWS Secrets Manager 進行登入憑證身分驗證](msk-password.md)
+ [Apache Kafka ACL](msk-acls.md)
# IAM 存取控制
適用於 Amazon MSK 的 IAM 存取控制可讓您處理 MSK 叢集的身分驗證和授權。這樣，您就對身分驗證和授權分別使用不同的機制。例如，當用戶端嘗試寫入至您的叢集時，Amazon MSK 會使用 IAM 來檢查該用戶端是否為已驗證的身分，以及是否已獲授權可對您的叢集進行生產。
IAM 存取控制適用於 Java 和非 Java 用戶端，包括使用 Python、Go、JavaScript 和 .NET 編寫的 Kafka 用戶端。非 Java 用戶端的 IAM 存取控制適用於 Kafka 2.7.1 版或更新版本的 MSK 叢集。
為了讓 IAM 存取控制得以運作，Amazon MSK 會對 Apache Kafka 的原始程式碼進行輕微修改。這些修改不會對您的 Apache Kafka 使用產生明顯差異。Amazon MSK 會記錄存取事件以便您稽核。
您可以針對使用 IAM 存取控制的 MSK 叢集調用 Apache Kafka ACL API。不過，Apache Kafka ACLs不會影響 IAM 身分的授權。您必須使用 IAM 政策來控制 IAM 身分的存取。
**重要考量**
當您搭配 MSK 叢集使用 IAM 存取控制時，請記住下列重要考量事項：
IAM 存取控制不適用於 Apache ZooKeeper 節點。如需有關如何控制節點存取權的詳細資訊，請參閱[控制對 Amazon MSK 叢集中 Apache ZooKeeper 節點的存取](zookeeper-security.md)。
如果您的叢集使用 IAM 存取控制，則 `allow.everyone.if.no.acl.found` Apache Kafka 設定將無作用。
您可以針對使用 IAM 存取控制的 MSK 叢集調用 Apache Kafka ACL API。不過，Apache Kafka ACLs不會影響 IAM 身分的授權。您必須使用 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 或 AWS CLI 來建立使用 IAM 存取控制的 Amazon MSK 叢集。如需有關如何啟用現有叢集的 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. 選擇 **Create Cluster** (建立叢集)。
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](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/create-cluster.html) CLI 命令，並為 `ClientAuthentication` 參數傳遞下列 JSON：`"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-started](https://github.com/aws/aws-msk-iam-sasl-signer-js#getting-started)
+ Python：[https://github.com/aws/aws-msk-iam-sasl-signer-python\$1get-started](https://github.com/aws/aws-msk-iam-sasl-signer-python#get-started)
+ Go：[https://github.com/aws/aws-msk-iam-sasl-signer-go\$1getting-started](https://github.com/aws/aws-msk-iam-sasl-signer-go#getting-started)
+ .NET：[https://github.com/aws/aws-msk-iam-sasl-signer-net\$1getting-started](https://github.com/aws/aws-msk-iam-sasl-signer-net#getting-started)
+ JAVA：可透過 [https://github.com/aws/aws-msk-iam-auth/releases](https://github.com/aws/aws-msk-iam-auth/releases) jar 檔案獲得 Java 的 SASL\$1OAUTHBEARE 支援
## 使用 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";`請在用戶端組態檔案中包含 。如需具名設定檔的相關資訊，請參閱 AWS CLI 文件中的[具名設定檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)。
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 政策的詳細資訊，請參閱[建立 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。
以下是名為 MyTestCluster 之叢集的授權政策範例。若要了解 `Action` 和 `Resource` 元素的語意，請參閱[IAM 授權政策動作和資源的語意](kafka-actions.md)。
**重要**
您對 IAM 政策所做的變更會立即反映在 IAM API 與 AWS CLI 中。不過，政策變更可能需要一點時間才會生效。在大多數情況下，政策變更會在一分鐘內生效。有時網路狀況可能會增加延遲。
------
#### [ 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` 提供給 **ALL** 主題時，這不會影響案例。在這種情況下，`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 來終止交易。對於執行 3.8 之前 Kafka 版本的叢集，IAM 存取控制不支援內部叢集動作，包括 WriteTxnMarkers。對於這些舊版，若要終止交易，請使用 SCRAM 或 mTLS 身分驗證搭配適當的 ACLs，而非 IAM 身分驗證。
本節說明您可以在 IAM 授權政策中使用的動作和資源元素的語義。如需政策範例，請參閱 [建立 IAM 角色的授權政策](create-iam-access-control-policies.md)。
## 授權政策動作
下表列出在 Amazon MSK 使用 IAM 存取控制時，可包含在授權政策中的動作。當您在授權政策中加入來自表格*動作*資料欄中的動作時，您還必須加入*必要動作*資料欄中的對應動作。
| Action | Description | 必要的動作 | 必要的資源 | 適用於無伺服器叢集 |
| --- | --- | --- | --- | --- |
| kafka-cluster:Connect | 准許與叢集連線並進行身分驗證。 | 無 | 叢集 | 是 |
| kafka-cluster:DescribeCluster | 准許描述叢集的各方面，相當於 Apache Kafka 的 DESCRIBE CLUSTER ACL。 | `kafka-cluster:Connect` | 叢集 | 是 |
| kafka-cluster:AlterCluster | 准許改變叢集的各方面，相當於 Apache Kafka 的 ALTER CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeCluster` | 叢集 | 否 |
| kafka-cluster:DescribeClusterDynamicConfiguration | 准許描述叢集的動態組態，相當於 Apache Kafka 的 DESCRIBE\$1CONFIGS CLUSTER ACL。 | `kafka-cluster:Connect` | 叢集 | 否 |
| kafka-cluster:AlterClusterDynamicConfiguration | 准許改變叢集的動態組態，相當於 Apache Kafka 的 ALTER\$1CONFIGS CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeClusterDynamicConfiguration` | 叢集 | 否 |
| kafka-cluster:WriteDataIdempotently | 准許在叢集上等冪寫入資料，相當於 Apache Kafka 的 IDEMPOTENT\$1WRITE CLUSTER ACL。 | `kafka-cluster:Connect` `kafka-cluster:WriteData` | 叢集 | 是 |
| kafka-cluster:CreateTopic | 准許在叢集上建立主題，相當於 Apache Kafka 的 CREATE CLUSTER/TOPIC ACL。 | `kafka-cluster:Connect` | 主題 | 是 |
| kafka-cluster:DescribeTopic | 准許描述叢集上的主題，相當於 Apache Kafka 的 DESCRIBE TOPIC ACL。 | `kafka-cluster:Connect` | 主題 | 是 |
| kafka-cluster:AlterTopic | 准許改變叢集上的主題，相當於 Apache Kafka 的 ALTER TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | 主題 | 是 |
| kafka-cluster:DeleteTopic | 准許刪除叢集上的主題，相當於 Apache Kafka 的 DELETE TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | 主題 | 是 |
| kafka-cluster:DescribeTopicDynamicConfiguration | 准許描述叢集上主題的動態組態，相當於 Apache Kafka 的 DESCRIBE\$1CONFIGS TOPIC ACL。 | `kafka-cluster:Connect` | 主題 | 是 |
| kafka-cluster:AlterTopicDynamicConfiguration | 准許改變叢集上主題的動態組態，相當於 Apache Kafka 的 ALTER\$1CONFIGS TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopicDynamicConfiguration` | 主題 | 是 |
| kafka-cluster:ReadData | 准許讀取叢集上主題的資料，相當於 Apache Kafka 的 READ TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:AlterGroup` | 主題 | 是 |
| kafka-cluster:WriteData | 准許寫入叢集上主題的資料，相當於 Apache Kafka 的 WRITE TOPIC ACL。 | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | 主題 | 是 |
| 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 | 准許描述叢集上的交易 ID，相當於 Apache Kafka 的 DESCRIBE TRANSACTIONAL\$1ID ACL。 | `kafka-cluster:Connect` | transactional-id | 是 |
| kafka-cluster:AlterTransactionalId | 准許改變叢集上的交易 ID，相當於 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:*` 代表所有許可。
## 授權政策資源
下表顯示將 IAM 存取控制用於 Amazon MSK 時，可在授權政策中使用的四種資源類型。您可以從 取得叢集 Amazon Resource Name (ARN)， AWS 管理主控台 或使用 [DescribeCluster](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn.html#DescribeCluster) API 或 [describe-cluster](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI 命令。然後，您可以使用叢集 ARN 來建構主題、群組和交易 ID ARN。若要在授權政策中指定資源，請使用該資源的 ARN。
| 資源 | ARN 格式 |
| --- | --- |
| 叢集 | arn:aws:kafka:region:account-id:cluster/cluster-name/cluster-uuid |
| 主題 | arn:aws:kafka:region:account-id:topic/cluster-name/cluster-uuid/topic-name |
| Group | arn:aws:kafka:region:account-id:group/cluster-name/cluster-uuid/group-name |
| 交易 ID | arn:aws:kafka:region:account-id:transactional-id/cluster-name/cluster-uuid/transactional-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" 結尾的所有主題，所屬叢集名稱是 MyTestCluster，叢集 UUID 是 abcd1234-0123-abcd-5678-1234abcd-1。
+ `arn:aws:kafka:us-east-1:0123456789012:transactional-id/MyTestCluster/*/5555abcd-1111-abcd-1234-abcd1234-1`：您帳戶中名為 MyTestCluster 的叢集的所有化身中交易 ID 為 5555abcd-1111-ABCD-1234-ABCD1234-1 的所有交易。這表示，如果您建立名為 MyTestCluster 的叢集並將其刪除，然後以相同的名稱建立另一個叢集，您可以使用此資源 ARN 來代表這兩個叢集上的相同交易 ID。但是，您無法存取已刪除的叢集。
# 用戶端授權政策的常見使用案例
下表中的第一個資料欄顯示一些常見的使用案例。若要授權用戶端執行指定的使用案例，請在用戶端的授權政策中包含該使用案例所需的動作，然後將 `Effect` 設定為 `Allow`。
如需有關 Amazon MSK 上所有 IAM 存取控制動作的相關資訊，請參閱[IAM 授權政策動作和資源的語意](kafka-actions.md)。
**注意**
根據預設，動作會被拒絕。您必須明確允許要授權用戶端執行的每個動作。
****
| 使用案例 | 必要的動作 |
| --- | --- |
| 管理員 | `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 用戶端身分驗證
您可以使用 TLS 啟用用戶端身分驗證，以便從應用程式連線至 Amazon MSK 代理程式。如要使用用戶端身分驗證，您需要一個 AWS 私有 CA。 AWS 私有 CA 可以與您的叢集 AWS 帳戶 位於相同的 中，也可以位於不同的 帳戶中。如需 AWS 私有 CA的相關資訊，請參閱[建立和管理 AWS 私有 CA](https://docs.aws.amazon.com/acm-pca/latest/userguide/create-CA.html)。
Amazon MSK 不支援憑證撤銷清單 (CRL)。若要控制對叢集主題的存取或封鎖遭到入侵ACLs 和 AWS 安全群組。如需有關使用 Apache Kafka ACL 的詳細資訊，請參閱 [Apache Kafka ACL](msk-acls.md)。
**Topics**
+ [建立支援用戶端身分驗證的 Amazon MSK 叢集](msk-authentication-cluster.md)
+ [設定用戶端以使用身分驗證](msk-authentication-client.md)
+ [使用身分驗證產生和使用訊息](msk-authentication-messages.md)
# 建立支援用戶端身分驗證的 Amazon MSK 叢集
此程序說明如何使用 啟用用戶端身分驗證 AWS 私有 CA。
**注意**
當您使用交互 AWS 私有 CA TLS 控制存取時，強烈建議為每個 MSK 叢集使用獨立 。這樣做可確保由 PCA 簽署的 TLS 憑證僅透過單一 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. 在用戶端機器上，執行下列命令以建立用戶端私有金鑰。將 *Distinguished-Name*、*Example-Alias*、*Your-Store-Pass* 和 *Your-Key-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. 在生產者視窗中輸入訊息，並觀看訊息出現在取用者視窗中。
# 使用 AWS Secrets Manager 進行登入憑證身分驗證
您可以使用使用 AWS Secrets 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 (簡易身分驗證及安全性階層/Salted Challenge Response Mechanism) 身分驗證。若要設定叢集的登入憑證身分驗證，您可以在 [AWS Secrets Manager](https://docs.aws.amazon.com//secretsmanager/?id=docs_gateway) 中建立秘密資源，並將登入憑證與該秘密建立關聯。
SAS/SCRM 定義見 [RFC 5802](https://tools.ietf.org/html/rfc5802)。SCRAM 使用安全的雜湊演算法，不會在用戶端與伺服器之間傳輸純文字登入憑證。
**注意**
為叢集設定 SASL/SCRAM 身分驗證後，Amazon MSK 會為用戶端和代理程式之間的所有流量開啟 TLS 加密。
# 設定 Amazon MSK 叢集的 SASL/SCRAM 身分驗證
若要在 AWS Secrets Manager 中設定秘密，請遵循 [AWS Secrets Manager 使用者指南](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)中的[建立和擷取](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)秘密教學課程。
為 Amazon MSK 叢集建立秘密時，請注意以下要求：
+ 針對秘密類型，選擇**其他秘密類型 (如 API 金鑰)**。
+ 您的秘密名稱必須以 **Amazon MSK\$1** 字首開頭。
+ 您必須使用現有的自訂 AWS KMS 金鑰或為您的秘密建立新的自訂 AWS KMS 金鑰。Secrets Manager 預設會使用秘密的預設 AWS KMS 金鑰。
**重要**
使用預設 AWS KMS 金鑰建立的秘密無法與 Amazon MSK 叢集搭配使用。
+ 您的登入憑證資料必須採用下列格式，才能使用**純文字**選項輸入鍵值對。
```
{
"username": "alice",
"password": "alice-secret"
}
```
+ 記錄秘密的 ARN (Amazon Resource Name) 值。
+
**重要**
您無法將 Secret Manager 秘密與超過 [正確調整叢集大小：每個標準代理程式的分割區數量](bestpractices.md#partitions-per-broker) 中所述限制的叢集建立關聯。
+ 如果您使用 AWS CLI 建立秘密，請指定 `kms-key-id` 參數的金鑰 ID 或 ARN。請勿指定別名。
+ 若要將秘密與叢集建立關聯，請使用 Amazon MSK 主控台或 [BatchAssociateScramSecret](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-scram-secrets.html#BatchAssociateScramSecret) 操作。
**重要**
將秘密與叢集建立關聯後，Amazon MSK 會將資源政策連接至秘密，以便叢集能夠存取和讀取您定義的秘密值。您不應該修改此資源政策。這樣做可以防止您的叢集存取您的秘密。如果您對 Secrets 資源政策和/或用於秘密加密的 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 已安裝 的機器上執行下列命令。以叢集的 ARN 取代 *clusterARN*。
```
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`的檔案。使用執行個體上 JDK 資料夾的名稱取代 *JDKFolder*。例如，您的 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 分鐘的時間傳播。
如需有關搭配 Amazon MSK 使用 ACL 的詳細資訊，請參閱 [Apache Kafka ACL](msk-acls.md)。
對於使用 ZooKeeper 模式的叢集，我們建議您限制對 ZooKeeper 節點的存取，以防止使用者修改 ACLs。如需詳細資訊，請參閱[控制對 Amazon MSK 叢集中 Apache ZooKeeper 節點的存取](zookeeper-security.md)。
# 使用 SCRAM 秘密的限制
使用 SCRAM 秘密時，請注意以下限制：
+ Amazon MSK 僅支援 SCRAM-SHA-512 身分驗證。
+ 一個 Amazon MSK 叢集最多可以有 1000 個使用者。
+ 您必須將 AWS KMS key 與秘密搭配使用。您無法將採取預設 Secrets Manager 加密金鑰的秘密與 Amazon MSK 搭配使用。如需有關建立 KMS 金鑰的相關資訊，請參閱[建立對稱加密 KMS 金鑰](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 叢集相關聯的秘密名稱必須使用字首 **Amazon MSK\$1**。
+ 與 Amazon MSK 叢集相關聯的秘密必須與叢集位於相同的 Amazon Web Services 帳戶和 AWS 區域中。
# Apache Kafka ACL
Apache Kafka 具有可插入的授權方，並隨附out-of-box授權方實作。Amazon MSK 會在代理程式的 `server.properties` 檔案中啟用此授權。
Apache Kafka ACL 的格式為「主體 P 被主機 H [允許/拒絕] 在任何匹配 ResourcePattern RP 的資源 R 上進行操作 O」。如果 RP 不匹配特定的資源 R，那麼 R 和 ACL 無關聯，因此除了超級使用者以外沒有其他人能夠存取 R。若要變更此 Apache Kafka 行為，請將屬性 `allow.everyone.if.no.acl.found` 設定為 "true"。Amazon MSK 預設設定為 "true"。這表示使用 Amazon MSK 叢集時，如果您未在資源上明確設定 ACL，則所有委託人都可以存取此資源。如果您啟用資源上的 ACL，只有授權的委託人可以存取它。如果您想要限制對主題的存取，並授權使用 TLS 相互驗證的用戶端，請使用 Apache Kafka 授權方 CLI 來新增 ACL。如需有關新增、移除和列出 ACL 的詳細資訊，請參閱 [Kafka 授權命令列界面](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Authorization+Command+Line+Interface)。
由於 Amazon MSK 會將代理程式設定為超級使用者，因此他們可以存取所有主題。這有助於代理程式從主要分割區複寫訊息，無論是否為叢集的組態定義 `allow.everyone.if.no.acl.found` 屬性。
**若要新增或移除主題的讀取和寫入權限**
1. 將您的代理程式新增至 ACL 表格，以允許它們讀取所有具有 ACL 的主題。若要授予代理程式對主題的讀取權限，請在可與 MSK 叢集通訊的用戶端機器上執行下列命令。
使用叢集的任何引導代理程式的 DNS 取代 *Distinguished-Name*，然後以星號 (`*`) 取代此辨別名稱中第一個句點之前的字串。例如，如果其中一個叢集的引導代理程式具有 DNS，`b-6.mytestcluster.67281x.c4.kafka.us-east-1.amazonaws.com`請使用 `*.mytestcluster.67281x.c4.kafka.us-east-1.amazonaws.com` 取代下列命令中的 *Distinguished-Name*。如需有關如何取得引導代理程式的資訊，請參閱[取得 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 來取得叢集中的代理程式清單。此操作的結果包括與代理程式相關聯的彈性網路介面 (ENI) ID。
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)：// 開啟 Amazon EC2 主控台。
1. 使用靠近螢幕右上角的下拉式清單，選取部署叢集的區域。
1. 在左側窗格中**網路與安全**下，選擇**網路介面**。
1. 選擇您在第一步中獲得的第一個 ENI。選擇畫面頂端的**動作**選單，然後選擇**變更安全群組**。將新的安全群組指派給此 ENI。針對您在第一個步驟中取得的每個 ENI 重複此步驟。
**注意**
您使用 Amazon EC2 主控台對叢集安全群組所做的變更，不會反映在**網路設定**下的 MSK 主控台中。
1. 設定新安全群組的規則，以確保您的用戶端可以存取代理程式。如需有關設定安全群組規則的詳細資訊，請參閱《Amazon VPC 使用者指南》中的[新增、移除及更新規則](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html?shortFooter=true#AddRemoveRules)。
**重要**
如果您變更與叢集中代理程式相關聯的安全群組，然後將新代理程式新增至該叢集，Amazon MSK 會將新代理程式與叢集建立時相關聯的原始安全群組建立關聯。不過，若要讓叢集正常運作，叢集的所有代理程式都必須與相同的安全群組相關聯。因此，如果在變更安全群組後添加新代理程式，則必須再次執行之前的過程並更新新代理程式的 ENI。
# 控制對 Amazon MSK 叢集中 Apache ZooKeeper 節點的存取
基於安全考量，您可以對屬於 Amazon MSK 叢集的 Apache ZooKeeper 節點存取權進行限制。若要限制對這些節點的存取權，您可以將個別的安全群組指派給這些節點。然後，您可以決定誰可以存取該安全群組。
**重要**
本節不適用於在 KRaft 模式下執行的叢集。請參閱 [KRaft 模式](metadata-management.md#kraft-intro)。
**Topics**
+ [將 Apache ZooKeeper 節點放在個別的安全群組](zookeeper-security-group.md)
+ [搭配 Apache ZooKeeper 使用 TLS 安全功能](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 管理主控台 ，並在 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)：// 開啟 Amazon EC2 主控台。
1. 在左側窗格中的 **NETWORK & SECURITY (網路與安全)** 下，選擇 **Network Interfaces (網路界面)**。
1. 在網路界面表格上方的搜尋欄位中，輸入叢集的名稱，然後輸入 return。這會將表格中顯示的網路界面數量限制為與叢集相關聯的那些界面。
1. 在清單中與第一個網路界面相對應的資料列開頭選取核取方塊。
1. 在頁面底部的詳細資訊窗格中，尋找 **Primary private IPv4 IP (主要私有 IPv4 IP)**。如果此 IP 地址與您在此程序的第一步中獲得的其中一個 IP 地址相符，這意味著系統會將此網路界面指派給屬於您叢集的 Apache ZooKeeper 節點。否則，請取消選取此網路界面旁的核取方塊，然後選取清單中的下一個網路界面。網路界面的選取順序無關緊要。在接下來的步驟中，您將對指派給 Apache ZooKeeper 節點的所有網路界面一個接一個執行相同的操作。
1. 當您選取與 Apache ZooKeeper 節點對應的網路界面時，請選擇頁面頂端的 **Actions (動作)** 功能表，然後選擇 **Change Security Groups (變更安全群組)**。將新的安全群組指派至此網路界面。如需有關建立安全群組的詳細資訊，請參閱 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 ZooKeeper 使用 TLS 安全功能
您可以使用 TLS 安全功能加密用戶端與 Apache ZooKeeper 節點之間的傳輸。要搭配 Apache ZooKeeper 節點使用 TLS 安全功能，請執行以下操作：
+ 叢集必須使用 Apache Kafka 2.5.1 版或更高版本以搭配 Apache ZooKeeper 使用 TLS 安全功能。
+ 建立或設定叢集時啟用 TLS 安全功能。使用 Apache Kafka version 2.5.1 版或更高版本建立，且啟用 TLS 的叢集，會自動搭配 Apache ZooKeeper 端點使用 TLS 安全功能。如需有關 TLS 安全功能設定的資訊，請參閱 [開始使用 Amazon MSK 加密](msk-working-with-encryption.md)。
+ 使用 [DescribeCluste ](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 Shell 使用。搭配各個工具，您可以使用 `--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 命令。以下範例使用來自 `KAFKA_OPTS` 環境變量的 Apache ZooKeeper 組態建立 Apache Kafka 主題：
```
/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: Enable ZK client to use the new TLS supported authentication](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 Services 範圍](https://aws.amazon.com/compliance/services-in-scope/)。如需一般資訊，請參閱 [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/)。
您可以使用 下載第三方稽核報告 AWS Artifact。如需詳細資訊，請參閱[下載報告 in 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 合規資源](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 的基礎設施安全性
作為受管服務，Amazon Managed Streaming for Apache Kafka 受到 [Amazon Web Services：安全程序概觀](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf)白皮書中所述 AWS 的全球網路安全程序的保護。
您可以使用 AWS 發佈的 API 呼叫，透過網路存取 Amazon MSK。用戶端必須支援 Transport Layer Security (TLS) 1.0 或更新版本。建議使用 TLS 1.2 或更新版本。用戶端也必須支援具備完美轉送私密 (PFS) 的密碼套件，例如臨時 Diffie-Hellman (DHE) 或橢圓曲線臨時 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 代理程式日誌交付至下列一或多個目的地類型：Amazon CloudWatch Logs、Amazon S3、Amazon Data Firehose。您也可以使用 記錄 Amazon MSK API 呼叫 AWS CloudTrail。
**注意**
中介裝置日誌可在 MSK Standard 和 Express 中介裝置上取得。
## 代理程式日誌
代理程式日誌可讓您針對 Apache Kafka 應用程式進行疑難排解，並分析與 MSK 叢集的通訊。您可以設定新的或現有的 MSK 叢集，將 INFO 層級代理程式日誌交付至下列一或多個類型的目的地資源：CloudWatch 日誌群組、S3 儲存貯體、Firehose 交付串流。然後，您可以透過 Firehose 將日誌資料從交付串流交付至 OpenSearch Service。
您必須先建立目的地資源，才能設定叢集向其傳遞代理程式日誌。如果這些目的地資源尚未存在，Amazon MSK 不會為您建立它們。如需有關這三種目標資源類型以及如何建立這些資源的資訊，請參閱下列文件：
+ [Amazon CloudWatch Logs](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 受管政策：AmazonMSKFullAccess](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 串流`true`上將`LogDeliveryEnabled`標籤設定為 ，才能設定日誌交付。為 CloudWatch 日誌 AWS 建立的服務連結角色使用此標籤授予所有 Firehose 交付串流的許可。如果您移除此標籤，服務連結角色將無法將日誌交付至 Firehose 串流。若要查看顯示服務連結角色包含之許可的 IAM 政策範例，請參閱《*Amazon 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 設定代理程式日誌
您可以指定要傳遞給 [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) 操作之 JSON 的可選 `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 Logs 為日誌目的地，並且動態啟用 `DEBUG` 或 `TRACE` 層級日誌，Amazon MSK 可能會持續傳遞日誌樣本。這可能會大幅影響代理程式效能，只有在 `INFO` 日誌層級不夠詳細、無法判斷問題的根本原因時才應該使用方法。
# 使用 記錄 API 呼叫 AWS CloudTrail
**注意**
AWS CloudTrail 日誌僅適用於使用 的 Amazon MSK[IAM 存取控制](iam-access-control.md)。
Amazon MSK 已與 服務整合 AWS CloudTrail，此服務提供由 Amazon MSK AWS 中的使用者、角色或服務所採取之動作的記錄。CloudTrail 會擷取 API 呼叫當作事件。擷取的呼叫包括從 Amazon MSK 主控台執行的呼叫，以及對 Amazon MSK API 操作發出的程式碼呼叫。它也會擷取 Apache Kafka 的動作，例如建立、變更主題和群組。
如果您建立追蹤，就可以將 CloudTrail 事件 (包括 Amazon MSK 的事件) 持續交付到 Amazon S3 儲存貯體。即使您未設定追蹤，依然可以透過 CloudTrail 主控台中的**事件歷史記錄**檢視最新事件。您可以利用 CloudTrail 所收集的資訊來判斷向 Amazon MSK 或 Apache Kafka 發出的請求，以及發出請求的 IP 地址、人員、時間和其他詳細資訊。
若要進一步了解 CloudTrail，包括如何設定及啟用，請參閱[《AWS CloudTrail 使用者指南》](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## CloudTrail 中的 Amazon MSK 資訊
在您建立帳戶時，系統即會在 Amazon Web Services 帳戶中啟用 CloudTrail。當 MSK 叢集中發生支援的事件活動時，該活動會與**事件歷史記錄**中的其他 AWS 服務事件一起記錄在 CloudTrail 事件中。您可以檢視、搜尋和下載 Amazon Web Services 帳戶中的最近事件。如需詳細資訊，請參閱《使用 CloudTrail 事件歷史記錄檢視事件》[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html](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)
+ [設定 CloudTrail 的 Amazon SNS 通知](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-cluster:DescribeClusterDynamicConfiguration
+ kafka-cluster:AlterClusterDynamicConfiguration
+ kafka-cluster:CreateTopic
+ kafka-cluster:DescribeTopicDynamicConfiguration
+ kafka-cluster:AlterTopic
+ kafka-cluster:AlterTopicDynamicConfiguration
+ kafka-cluster:DeleteTopic
每一筆事件或日誌專案都會包含產生請求者的資訊。身分資訊可協助您判斷下列事項：
+ 請求是使用根使用者還是 AWS Identity and Access Management (IAM) 使用者登入資料提出。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 請求是否由其他 AWS 服務提出。
如需詳細資訊，請參閱 [CloudTrail userIdentity Element](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` 動作的 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"
}
```
# 中繼資料管理
Amazon MSK 支援 Apache ZooKeeper 或 KRaft 中繼資料管理模式。
從 Amazon MSK 上的 Apache Kafka 3.7.x 版，您可以建立使用 KRaft 模式而非 ZooKeeper 模式的叢集。KRaft 型叢集依賴 Kafka 內的控制器來管理中繼資料。
**Topics**
+ [ZooKeeper 模式](#msk-get-connection-string)
+ [KRaft 模式](#kraft-intro)
## ZooKeeper 模式
[Apache ZooKeeper](https://zookeeper.apache.org/) 是「一種集中式服務，用於維護組態資訊、命名、提供分散式同步，以及提供群組服務。包括 Apache Kafka 在內的分散式應用程式會以某種形式或其他形式使用這些類型的服務。
如果您的叢集使用 ZooKeeper 模式，您可以使用以下步驟來取得 Apache ZooKeeper 連線字串。不過，我們建議您使用 `BootstrapServerString` 連線到叢集和 Perfom 管理操作，因為 Kafka 2.5 中已棄用`--zookeeper`旗標，並從 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 Resource Name (ARN)，可以透過列出帳戶中的所有叢集來找到該 ARN。如需詳細資訊，請參閱[列出 Amazon MSK 叢集](msk-list-clusters.md)。
1. 若要獲得 Apache ZooKeeper 連線字串，以及叢集的其他相關資訊，請執行以下命令，使用叢集的 ARN 取代 *ClusterArn*。
```
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 模式
Amazon MSK 在 Kafka 3.7.x 版中推出對 KRaft (Apache Kafka Raft) 的支援。Apache Kafka 社群開發 KRaft 來取代 [Apache ZooKeeper](#msk-get-connection-string)，以在 Apache Kafka 叢集中進行中繼資料管理。在 KRaft 模式中，叢集中繼資料會在 Kafka 控制器群組中傳播，這是 Kafka 叢集的一部分，而不是跨 ZooKeeper 節點。包含 KRaft 控制器，您無需支付額外費用，也不需要您進行額外的設定或管理。如需 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 模式建立叢集。
+ 在 KRaft 和 ZooKeeper 型叢集上，每個代理程式的分割區數量相同。不過，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 版開始移除。因此，我們建議您針對叢集的所有`--bootstrap-server`連線使用最新的 Apache Kafka 用戶端版本和連線字串。
+ ZooKeeper 模式繼續可用於 Apache Kafka 也支援 zookeeper 的所有發行版本。[支援的 Apache Kafka 版本](supported-kafka-versions.md) 如需 Apache Kafka 版本和未來更新終止支援的詳細資訊，請參閱 。
+ 您應該檢查您使用的任何工具是否能夠在沒有 ZooKeeper 連線的情況下使用 Kafka Admin APIs。如需將叢集連線至 Cruise Control [將 LinkedIn 的 Apache Kafka 定速控制與 Amazon MSK 搭配使用](cruise-control.md) 的更新步驟，請參閱 。Cruise Control 也有在沒有 [ ZooKeeper 的情況下執行 Cruise Control](https://github.com/linkedin/cruise-control/wiki/Run-without-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 型叢集的開放式監控的更新步驟，請參閱 。
+ 您不需要透過 ZooKeeper 模式叢集監控 KRaft 模式叢集的其他 [CloudWatch 指標](https://docs.aws.amazon.com/msk/latest/developerguide/metrics-details.html)。MSK 會管理叢集中使用的 KRaft 控制器。
+ 您可以使用連線`--bootstrap-server`字串在 KRaft 模式叢集中使用 繼續管理 ACLs。您不應該使用`--zookeeper`連線字串來管理 ACLs。請參閱 [Apache Kafka ACL](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，您可以定義或讀取複寫係數和分割區計數等主題屬性，以及保留和清除政策等組態設定。您可以使用熟悉的界面以程式設計方式管理 Kafka 主題，包括 AWS CLI、SDK 和 AWS CloudFormation。 AWS SDKs 這些 APIs也會整合到 Amazon MSK 主控台，將所有主題操作集中到一處。您現在可以使用引導式預設值，只要按幾下滑鼠就能建立或更新主題，同時全面了解主題組態、分割區層級資訊和指標。
**重要**
這些主題 API 回應反映大約每分鐘更新的資料。對於進行變更後的最新主題狀態，請等待大約一分鐘再查詢。
## 使用主題 APIs的需求
+ 您的叢集必須是 MSK 佈建叢集。這些 APIs不適用於 MSK Serverless 叢集。
+ 您的叢集必須執行 Apache Kafka 3.6.0 版或更新版本。如需支援版本的詳細資訊，請參閱 [支援的 Apache Kafka 版本](supported-kafka-versions.md)。
+ 您的叢集必須處於 `ACTIVE` 狀態。如需有關叢集狀態的詳細資訊，請參閱 [了解 MSK 佈建叢集狀態](msk-cluster-states.md)。
+ 您必須擁有適當的 IAM 許可。如需詳細資訊，請參閱[主題操作 APIs IAM 許可](#topic-operations-permissions)。
## 主題操作 APIs IAM 許可
若要呼叫這些 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)
+ [主題操作 APIs IAM 許可](#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 佈建叢集中的所有主題，以檢視基本中繼資料，例如分割區計數和複寫因素。這對於監控叢集的主題、執行清查或識別主題以進行進一步調查非常有用。
**注意**
`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. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/) 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇要列出主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 資料表顯示叢集中的所有主題，包括主題名稱、分割區數量、複寫因素和out-of-sync複本計數。
# 使用 列出主題 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*。若您沒有叢集的 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 佈建叢集中特定主題的詳細資訊，包括其目前狀態、分割區計數、複寫因素和組態。這對於疑難排解、驗證主題設定或在操作期間監控主題狀態非常有用。
**注意**
此 API 回應會反映大約每分鐘更新一次的資料。對於進行變更後的最新主題狀態，請等待大約一分鐘再查詢。
**Topics**
+ [使用 描述主題 AWS 管理主控台](describe-topic-console.md)
+ [使用 描述主題 AWS CLI](describe-topic-cli.md)
+ [使用 API 描述主題](describe-topic-api.md)
# 使用 描述主題 AWS 管理主控台
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/) 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇包含您要描述之主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 在主題清單中，選擇您要檢視的主題名稱。
1. 主題詳細資訊頁面顯示主題的相關資訊，包括其狀態、分割區計數、複寫因素和組態設定。
# 使用 描述主題 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*，並以您要描述的主題名稱取代 *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` 欄位指出主題的目前狀態。下表說明可能的 狀態值。
**主題狀態值**
| 狀態 | Description |
| --- | --- |
| 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 佈建叢集中特定主題之分割區的詳細資訊。此資訊包括分割區編號、領導代理程式、複本代理程式和同步內複本 (ISR)。這有助於監控分割區分佈、識別複寫不足的分割區，或疑難排解複寫問題。
**注意**
此 API 回應會反映大約每分鐘更新一次的資料。對於進行變更後的最新主題狀態，請等待大約一分鐘再查詢。
**Topics**
+ [使用 檢視分割區資訊 AWS 管理主控台](describe-topic-partitions-console.md)
+ [使用 檢視分割區資訊 AWS CLI](describe-topic-partitions-cli.md)
+ [使用 API 檢視分割區資訊](describe-topic-partitions-api.md)
# 使用 檢視分割區資訊 AWS 管理主控台
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/) 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇包含主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 在主題清單中，選擇您要檢視分割區資訊的主題名稱。
1. 在主題詳細資訊頁面上，會顯示分割區資訊，顯示每個分割區的分割區編號、領導代理程式、複本和同步內複本。
# 使用 檢視分割區資訊 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*，並以主題名稱取代 *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]
}
]
}
```
## 了解分割區資訊
回應包含每個分割區的下列資訊：
+ **partition** — 分割區編號。分割區會從 0 開始編號。
+ **leader** — 此分割區之領導者的代理程式 ID。領導者會處理分割區的所有讀取和寫入請求。
+ **複本** — 具有此分割區複本的代理程式 IDs 清單。這包括同步內和out-of-sync複本。
+ **isr** — 同步內複本的代理IDs 清單。這些複本完全跟上領導者的進度，並且可以在需要時接管為領導者。
在上述範例中，分割區 2 out-of-sync的複本。`replicas` 清單包含代理程式 2，但`isr`清單不包含。這表示代理程式 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. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)：// 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇您要建立主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 請選擇**建立主題**。
1. 輸入主題名稱、分割區計數和複寫因素。或者，新增組態。您可以一次建立多個主題。
1. 請選擇**建立主題**。
# 使用 建立主題 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*。若您沒有叢集的 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. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)：// 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇包含您要更新之主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 選取您要更新的主題，然後選擇**編輯分割區設定**或從**動作****編輯組態**。
1. 視需要更新分割區計數或組態。
1. 選擇**儲存**。
# 使用 更新主題 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*，並以您要更新的主題名稱取代 *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. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/msk/home?region=us-east-1\$1/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/) 開啟 Amazon MSK 主控台。
1. 在叢集清單中，選擇包含您要刪除之主題的叢集名稱。
1. 在叢集詳細資訊頁面上，選擇**主題**索引標籤。
1. 選取您要刪除的主題，然後選擇從**動作****中刪除**。
1. 確認刪除，然後選擇**刪除**。
# 使用 刪除主題 AWS CLI
執行下列命令，以叢集的 Amazon Resource Name (ARN) 取代 *ClusterArn*，並以您要刪除的主題名稱取代 *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 中具有兩個含義，具體取決於內容。在 API 內容中，資源是您可以在其中調用操作的結構。如需這些資源的清單以及您可以在這些資源上調用之操作道清單，請參閱 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 （生命週期結束） 政策](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訊息傳遞的工作負載改善平行處理和輸送量。新的 Streams Rebalance Protocol 以 Kafka 4.0 的消費者重新平衡通訊協定為基礎，將代理程式協調功能擴展至 Kafka Streams，以最佳化任務指派和重新平衡。此外，ELR 現在預設為啟用，以增強可用性。
如需更多詳細資訊和改善和錯誤修正的完整清單，請參閱 [4.1 版的 Apache Kafka 版本備註。](https://downloads.apache.org/kafka/4.1.0/RELEASE_NOTES.html)
若要在 Amazon MSK 上開始使用 Apache Kafka 4.1，請在透過 AWS 管理主控台 AWS CLI或 AWS SDKs 建立新叢集時選擇 4.1.x 版。您也可以使用就地滾動更新來升級現有的 MSK 佈建叢集。Amazon MSK 會協調代理程式重新啟動，以在升級期間維持可用性並保護您的資料。Kafka 4.1 版支援可在提供 Amazon MSK 的所有 AWS 區域 中使用。
## Amazon MSK 4.0.x 版
Amazon Managed Streaming for Apache Kafka (Amazon MSK) 現在支援 Apache Kafka 4.0 版。此版本為 MSK Provisioned 帶來叢集管理和效能的最新進展。Kafka 4.0 推出新的消費者重新平衡通訊協定，現已全面推出，可協助確保更順暢且更快速的群組重新平衡。此外，Kafka 4.0 要求代理程式和工具使用 Java 17，提供更高的安全性和效能，包括各種錯誤修正和改進，並透過 Apache ZooKeeper 棄用中繼資料管理。
如需更多詳細資訊和改善和錯誤修正的完整清單，請參閱 [4.0 版的 Apache Kafka 版本備註。](https://downloads.apache.org/kafka/4.0.0/RELEASE_NOTES.html)
## Amazon 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 版的延伸支援。
如需更多詳細資訊和改善和錯誤修正的完整清單，請參閱 [3.9.x 版的 Apache Kafka 版本備註。](https://downloads.apache.org/kafka/3.9.0/RELEASE_NOTES.html)
## Amazon 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 等壓縮類型時的效能。
如需更多詳細資訊和改善和錯誤修正的完整清單，請參閱 [3.8.x 版的 Apache Kafka 版本備註。](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，以考慮版本命名中的此變更。
Amazon MSK 現在支援 Apache Kafka 3.7.x 版中的 KRaft 模式 (Apache Kafka Raft)。在 Amazon MSK 上，就像使用 ZooKeeper 節點一樣，KRaft 控制器包含在內，您無需支付額外費用，也不需要您進行額外的設定或管理。您現在可以在 Apache Kafka 3.7.x 版上以 KRaft 模式或 ZooKeeper 模式建立叢集。在 Kraft 模式中，相較於 Zookeeper 型叢集上的 30 個代理程式配額，您最多可以新增 60 個代理程式來託管每個叢集的更多分割區，而無需請求提高限制。若要進一步了解 MSK 上的 KRaft，請參閱 [KRaft 模式](metadata-management.md#kraft-intro)。
Apache Kafka 3.7.x 版也包含數個錯誤修正和改善效能的新功能。主要改進項目包括用戶端的領導者探索最佳化，以及日誌區段排清最佳化選項。如需改善和錯誤修正的完整清單，請參閱 [3.7.0](https://archive.apache.org/dist/kafka/3.7.0/RELEASE_NOTES.html) 的 Apache Kafka 版本備註。
## Apache Kafka 3.6.0 版本 (具有已準備好投入生產的分層儲存)
如需有關 Apache Kafka 3.6.0 版本 (具有已準備好投入生產的分層儲存) 的資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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 進行規定人數管理。如需改善和錯誤修正的完整清單，請參閱 3.5.1 的 Apache Kafka 版本備註。
如需有關 Apache Kafka 3.5.1 版的資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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 進行規定人數管理。如需改善和錯誤修正的完整清單，請參閱 3.4.0 的 Apache Kafka 版本備註。
如需有關 Apache Kafka 3.4.0 版的資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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 進行規定人數管理。如需改善和錯誤修正的完整清單，請參閱 3.3.2 的 Apache Kafka 版本備註。
如需有關 Apache Kafka 3.3.2 版的資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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 來進行規定人數管理，以確保穩定性。如需改善和錯誤修正的完整清單，請參閱 3.3.1 的 Apache Kafka 版本備註。
如需有關 Apache Kafka 3.3.1 版的資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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 進行規定人數管理，以確保穩定性。如需改善和錯誤修正的完整清單，請參閱 3.1.1 和 3.2.0 的 Apache Kafka 版本備註。
如需有關 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.tiered 版本包含分層儲存功能，與 [Apache Kafka 的 KIP-405](https://cwiki.apache.org/confluence/display/KAFKA/KIP-405%3A+Kafka+Tiered+Storage) 中引入之 API 相容。如需有關 Amazon MSK 分層儲存功能的詳細資訊，請參閱 [標準代理程式的分層儲存](msk-tiered-storage.md)。
## Apache Kafka 2.5.1 版
Apache Kafka 2.5.1 版本包含幾個錯誤修正和新功能，包括 Apache ZooKeeper 和管理用戶端的傳輸中加密。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) 操作輸出包括列出 TLS ZooKeeper 端點的 `ZookeeperConnectStringTls` 節點。
以下範例會顯示 `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 ZooKeeper 使用 TLS 安全功能](zookeeper-security-tls.md)。
如需有關 Apache Kafka 2.5.1 版的詳細資訊，請參閱 Apache Kafka 下載網站上的[版本備註](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) 的修正內容，KAFKA-9752 是一個罕見問題，會造成取用者群組持續重新平衡並維持在 `PreparingRebalance` 狀態。此問題會影響執行 Apache Kafka 2.3.1 和 2.4.1 版的叢集。此版本包含社群產生的修正內容，適用於 Apache Kafka 2.5.0 版。
**注意**
任何與 Apache Kafka 2.4.1 版相容的 Apache Kafka 用戶端，會與執行 2.4.1.1 版的 Amazon MSK 叢集相容。
若您要使用 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 Apache 2.4.1 版相容的用戶端。若你已有具有 Apache Kafka 2.4.1 版的 MSK 叢集，建議您進行更新，以改為使用 Apache Kafka 2.4.1.1 版。
KIP-392 是其中一個關鍵的 Kafka 改善提案，包含在 Apache Kafka 2.4.1 版本中。這項改善可讓取用者從最接近的複本擷取。如要使用此功能，請將取用者屬性中的 `client.rack` 設為取用者可用區域的 ID。範例 AZ ID 為 `use1-az1`。Amazon MSK 會將 `broker.rack` 設為代理程式可用區域的 ID。您也必須將 `replica.selector.class` 組態屬性設為 `org.apache.kafka.common.replica.RackAwareReplicaSelector`，此為 Apache Kafka 所提供機架意識的一種實作。
當您使用此版本的 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 頁面中的 [Allow Consumers to Fetch from Closest Replica](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 型版本時，您必須建立新的叢集。然後，將您的資料複製到新叢集，並將用戶端切換到新叢集。
1. （選用） 選擇**更新叢集組態**核取方塊，以套用與新版本相容的組態更新。這可啟用新版本的功能和改進。
如果您需要維護現有的自訂組態，可以略過此步驟。
**注意**
伺服器端升級不會自動更新用戶端應用程式。
為了維持叢集穩定性，不支援版本降級。
1. 選擇**升級**以開始程序。
**使用 升級 Apache Kafka 版本 AWS CLI**
1. 執行下列命令，使用您在建立叢集時獲得的 Amazon Resource Name (ARN) 取代 *ClusterArn*。若您沒有叢集的 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. 執行下列命令，使用您在建立叢集時獲得的 Amazon Resource Name (ARN) 取代 *ClusterArn*。若您沒有叢集的 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) 操作或 [describe-cluster](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kafka/describe-cluster.html) AWS CLI 命令。範例版本為`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` 操作的結果，請執行下列命令，使用您在 `update-cluster-kafka-version` 命令輸出中取得的 ARN 取代 *ClusterOperationArn*。
```
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 的特定代理程式開始修補，則用戶端連線字串中有多個代理程式允許容錯移轉。如需如何取得具有多個代理程式的連線字串的詳細資訊，請參閱[取得 Amazon MSK 叢集的引導代理](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 Replicator 進行故障診斷，請參閱 [MSK Replicator 故障診斷](msk-replicator-troubleshooting.md)。
**Topics**
+ [磁碟區取代因複寫過載而導致磁碟飽和](#replication-overload-disk-saturation)
+ [取用者群組停滯在 `PreparingRebalance` 狀態](#consumer-group-rebalance)
+ [將代理程式日誌傳送至 Amazon CloudWatch Logs 時出錯](#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)
+ [無法在 MSK 組態中更新 KafkaVersionsList](#troubleshoot-kafkaversionslist-cfn-update-failure)
## 磁碟區取代因複寫過載而導致磁碟飽和
在意外磁碟區硬體故障期間，Amazon MSK 可能會將磁碟區取代為新的執行個體。Kafka 透過從叢集中的其他代理程式複寫分割區來重新填入新磁碟區。複寫分割區並趕上之後，它們就符合領導階層和同步內複本 (ISR) 成員資格。
**問題**
在從磁碟區取代中復原的代理程式中，不同大小的某些分割區可能會先回到線上。這可能有問題，因為這些分割區可以提供來自仍在趕上 （複寫） 其他分割區之相同代理程式的流量。此複寫流量有時可能會使基礎磁碟區輸送量限制飽和，預設情況下為每秒 250 MiB。發生此飽和時，任何已追趕的分割區都會受到影響，導致與追趕分割區共用 ISR 的任何代理程式在叢集間延遲 （而不只是由於遠端 acks 而導致的領導分割區`acks=all`)。此問題在大小變化的分割區數量較大的叢集中更為常見。
**建議**
+ 若要改善複寫 I/O 狀態，請確定[最佳實務執行緒設定](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html#optimize-broker-threads)已就緒。
+ 為了降低基礎磁碟區飽和的可能性，請啟用具有較高輸送量的佈建儲存。對於高輸送量複寫案例，建議使用 500 MiB/s 的最低輸送量值，但所需的實際值會因輸送量和使用案例而有所不同。 [為 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 錯誤修正版的情況下，解決此問題的因應措施是設定 Kafka 用戶端使用[靜態成員通訊協定](#consumer-group-rebalance-static)或是[辨識與重新啟動](#consumer-group-rebalance-reboot)停滯的取用者群組的協調代理程式節點。
### 實施靜態成員通訊協定
若要在您的用戶端實施靜態成員通訊協定，請執行以下操作：
1. 將 [Kafka Consumers](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 Logs 時出錯
當您嘗試設定叢集以向 Amazon CloudWatch Logs 傳送代理程式日誌時,可能會出現兩種例外狀況之一。
如果出現 `InvalidInput.LengthOfCloudWatchResourcePolicyLimitExceeded` 例外狀況，請再試一次，但請使用開頭為 `/aws/vendedlogs/` 的日誌群組。如需詳細資訊，請參閱[啟用從特定 Amazon Web Services 記錄日誌](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html)。
如果出現 `InvalidInput.NumberOfCloudWatchResourcePoliciesLimitExceeded` 例外狀況，請在帳戶中選擇現有的 Amazon CloudWatch Logs 政策，然後將下列 JSON 附加其中。
```
{"Sid":"AWSLogDeliveryWrite","Effect":"Allow","Principal":{"Service":"delivery.logs.amazonaws.com"},"Action":["logs:CreateLogStream","logs:PutLogEvents"],"Resource":["*"]}
```
如果您嘗試將上述 JSON 附加到現有政策，但出現錯誤訊息，其中表示您已經達到所選政策的長度上限，請嘗試將 JSON 附加到另一個 Amazon CloudWatch Logs 政策中。將 JSON 附加至現有政策後，請再試一次，以設定將代理程式日誌傳遞至 Amazon CloudWatch Logs。
## 沒有預設安全群組
如果您嘗試建立叢集並收到錯誤，指出沒有預設安全群組，可能是因為您正使用與您共用的 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 2.1.0 版本，並可能導致一或多個代理程式死鎖。請考慮遷移到 Apache 卡夫卡 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)。如需如何使用 AWS CLI 執行 Amazon MSK 命令的資訊，請參閱 [Amazon MSK 主要功能和概念](operations.md)。
## 分割區離線或複本不同步
這些可能是磁碟空間不足的徵狀。請參閱 [磁碟空間不足](#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 (包括在低流量期間)，問題可能是您設定限制性 ACL，不授予主題對代理程式的存取權。若要複寫分割區，必須授權代理程式 READ 和 DESCRIBE 主題。READ 授權預設會授與 DESCRIBE 權限。如需有關設定 ACL 的詳細資訊，請參閱 Apache Kafka 文件中的 [授權和 ACL](https://kafka.apache.org/documentation/#security_authz)。
## 叢集具有名為 \$1\$1amazon\$1msk\$1canary 和 \$1\$1amazon\$1msk\$1canary\$1state 的主題
您可能會看到 MSK 叢集具有名為 `__amazon_msk_canary` 的主題，以及另一個名為 `__amazon_msk_canary_state` 的主題。這些是 Amazon MSK 針對叢集運作狀態和診斷指標建立和使用的內部主題。這些主題的大小可以忽略不計，且無法被刪除。
## 分區複寫失敗
請確定您尚未在 CLUSTER\$1ACTIONS 上設定 ACL。
## 無法存取已開啟公開存取的叢集
如果您的叢集已開啟公開存取，但仍無法從網際網路存取，請依照下列步驟執行：
1. 確定叢集安全群組的傳入規則允許您的 IP 地址和叢集的連接埠。如需叢集連接埠號碼的清單，請參閱[連接埠資訊](port-info.md)。同時確保安全群組的傳出規則允許傳出通訊。如需有關安全群組與其傳入、傳出規則的詳細資訊，請參閱《Amazon VPC 使用者指南》中的 [VPC 的安全群組](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。
1. 確定叢集 VPC 網路 ACL 的傳入規則中，允許您的 IP 地址和叢集的連接埠。與安全群組不同，網路 ACL 是無狀態的。這意味著您必須同時設定傳入和傳出規則。在傳出規則中，允許所有流量 (連接埠範圍：0-65535) 傳送到您的 IP 地址。如需詳細資訊，請參閱《Amazon VPC 使用者指南》中的[新增和刪除規則](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html#Rules)。
1. 確定您是使用公開存取 bootstrap-broker 字串來存取叢集。開啟公開存取的 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 [ VPCs 使用者指南》中的 VPC 和子網路的 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. 確保適用於 IPv6 支援的 JVM 屬性組態正確。在您的用戶端應用程式中，將 `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。
+ 9092 如果叢集未使用 TLS 身分驗證。
+ 如果啟用公有存取，則需要不同的連接埠號碼。
從用戶端機器執行命令。
1. 對所有引導代理程式重複前面的命令。
如果用戶端機器能夠存取代理程式，這表示沒有連線問題。在這種情況下，執行下列命令來檢查您的 Apache Kafka 用戶端是否已正確設定。若要取得 *bootstrap-brokers*，請使用 [取得 Amazon MSK 叢集的引導代理程式](msk-get-bootstrap-brokers.md) 中描述的任何方法。將 *主題* 替換為您的主題名稱。
```
/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)。
### 不同 VPC 中的 Amazon EC2 用戶端和 MSK 叢集
如果用戶端機器和叢集位於兩個不同的 VPC 中，請確定下列各項：
+ 兩個 VPC 是對等的。
+ 對等連線的狀態為作用中。
+ 兩個 VPC 的路由表已正確設定。
如需 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 受管政策：AmazonMSKFullAccess](security-iam-awsmanpol-AmazonMSKFullAccess.md)。
## 無法在 MSK 組態中更新 KafkaVersionsList
當您更新 [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`，您還必須在相同的操作中更新 [Name](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)。