AWS msk: MSK: custom domain names migration guidance for ZK-to-KRaft
Summary
Adds a 'Migrate from ZooKeeper to KRaft mode' section explaining that dynamic advertised.listeners overrides set via kafka-configs.sh block the in-place upgrade, and instructs operators to add custom.advertised.listeners to the MSK configuration and delete the dynamic override on each broker before migrating. Adds corresponding nav/TOC entry.
Security assessment
The change is migration/operational documentation about listener configuration blocking an upgrade path. It has no authentication, encryption, authorization, or exposure content and references no vulnerability.
Evidence
+If you currently use `kafka-configs.sh` to set `advertised.listeners` dynamically in ZooKeeper mode, you must set up `custom.advertised.listeners` in your Amazon MSK configuration before you initiate your migration from ZooKeeper to KRaft mode. The in-place upgrade checks for existing dynamic advertised listener overrides. If it detects any, the upgrade doesn't proceed, and you receive an error that asks you to remove them first. For a seamless experience, do the following:
Diff
diff --git a/msk/latest/developerguide/custom-domain-names.md b/msk/latest/developerguide/custom-domain-names.md index 2c00f94d3..425ee7ebd 100644 --- a//msk/latest/developerguide/custom-domain-names.md +++ b//msk/latest/developerguide/custom-domain-names.md @@ -7 +7 @@ -How custom domain names workPrerequisites +How custom domain names workPrerequisitesMigrate from ZooKeeper to KRaft mode @@ -18,0 +19,2 @@ You can configure your MSK Provisioned cluster to advertise custom domain names + * Migrate from ZooKeeper to KRaft mode + @@ -88,0 +91,15 @@ Before you configure custom domain names on your cluster, make sure that the fol +## Migrate from ZooKeeper to KRaft mode + +If you currently use `kafka-configs.sh` to set `advertised.listeners` dynamically in ZooKeeper mode, you must set up `custom.advertised.listeners` in your Amazon MSK configuration before you initiate your migration from ZooKeeper to KRaft mode. The in-place upgrade checks for existing dynamic advertised listener overrides. If it detects any, the upgrade doesn't proceed, and you receive an error that asks you to remove them first. For a seamless experience, do the following: + + 1. Add `custom.advertised.listeners` to your Amazon MSK configuration with the same domain pattern that you use today. For the steps, see [Set up a custom domain name end to end](./custom-domain-setup.html). + + 2. Remove the dynamic override by running `kafka-configs.sh --alter --delete-config advertised.listeners` on each broker. This removes only the advertised listeners override and doesn't affect other dynamic configurations. + + 3. Initiate the migration. + + + + +For more information about migrating a cluster to KRaft mode, see [Migrate from ZooKeeper to KRaft mode](./zk-to-kraft-migration.html). +