You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2026/10/06 00:29:17 UTC
(pulsar-site) 02/03: Link the 5.0.x upgrade guide from the docs front page and drop etcd and subscription-thread dispatch items from it
This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
commit cbd28626e29a8a0db31e581929e3a2ccbd83f74f
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Mon Oct 5 17:22:25 2026 -0700
Link the 5.0.x upgrade guide from the docs front page and drop etcd and subscription-thread dispatch items from it
---
docs/about.md | 2 +-
docs/administration-upgrade-to-5.0.x.md | 3 +--
versioned_docs/version-5.0.x/about.md | 2 +-
versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md | 3 +--
4 files changed, 4 insertions(+), 6 deletions(-)
diff --git a/docs/about.md b/docs/about.md
index 8c6ebaf2855..88a87ab8e58 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -21,7 +21,7 @@ Quick links:
- [Blog: Apache Pulsar 5.0 LTS: Scalable Topics and Faster Existing Workloads](pathname:///blog/2026/10/05/announcing-apache-pulsar-5-0)
- [Release highlights and upgrading](release-highlights.md)
-- [Cluster upgrade guide](administration-upgrade.md)
+- [Upgrading to Pulsar 5.0.x](administration-upgrade-to-5.0.x.md)
- [Java client dependency configuration for Pulsar @pulsar:version:major@](pathname:///docs/client-libraries/java-dependency-configuration)
:::
diff --git a/docs/administration-upgrade-to-5.0.x.md b/docs/administration-upgrade-to-5.0.x.md
index 9ffae42a1bc..618fc8059ef 100644
--- a/docs/administration-upgrade-to-5.0.x.md
+++ b/docs/administration-upgrade-to-5.0.x.md
@@ -58,11 +58,10 @@ Use the [configuration default comparison](administration-upgrade-to-5.0.x-confi
- **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
-- **etcd is no longer a metadata-store backend.** Migrate deployments using `etcd:` metadata URLs to a supported backend before upgrading. The [ZooKeeper-to-Oxia migration procedure](administration-metadata-store-migration.md) introduced in 5.0 does not migrate etcd. Complete the software upgrade separately from an optional ZooKeeper-to-Oxia migration.
- **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
- **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
- **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
-- **Review dispatch scheduling for expensive entry filters.** `dispatcherDispatchMessagesInSubscriptionThread` changes from `true` to `false`, avoiding an extra subscription-thread handoff. Configurations with compute-heavy server-side broker entry filters may benefit from setting it back to `true`, but this is not a general recommendation: test the change separately with representative workloads. The related `managedLedgerReadEntriesCallbackInline` optimization (default `true`) enables [...]
+- **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
- **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]
diff --git a/versioned_docs/version-5.0.x/about.md b/versioned_docs/version-5.0.x/about.md
index 8c6ebaf2855..88a87ab8e58 100644
--- a/versioned_docs/version-5.0.x/about.md
+++ b/versioned_docs/version-5.0.x/about.md
@@ -21,7 +21,7 @@ Quick links:
- [Blog: Apache Pulsar 5.0 LTS: Scalable Topics and Faster Existing Workloads](pathname:///blog/2026/10/05/announcing-apache-pulsar-5-0)
- [Release highlights and upgrading](release-highlights.md)
-- [Cluster upgrade guide](administration-upgrade.md)
+- [Upgrading to Pulsar 5.0.x](administration-upgrade-to-5.0.x.md)
- [Java client dependency configuration for Pulsar @pulsar:version:major@](pathname:///docs/client-libraries/java-dependency-configuration)
:::
diff --git a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
index 9ffae42a1bc..618fc8059ef 100644
--- a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
+++ b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x.md
@@ -58,11 +58,10 @@ Use the [configuration default comparison](administration-upgrade-to-5.0.x-confi
- **Preserve rollback before the first 5.0 broker starts.** If you need to retain an existing-feature rollback path, set `scalableTopicsEnabled=false` on every target 5.0 broker and keep applications on the v4 client API. If you enable package management for Functions or IO connectors (disabled by default), preserve the Java metadata format as described below. Complete the [rollback preparation](#preserve-and-rehearse-rollback) before rolling any brokers.
-- **etcd is no longer a metadata-store backend.** Migrate deployments using `etcd:` metadata URLs to a supported backend before upgrading. The [ZooKeeper-to-Oxia migration procedure](administration-metadata-store-migration.md) introduced in 5.0 does not migrate etcd. Complete the software upgrade separately from an optional ZooKeeper-to-Oxia migration.
- **Existing shadow topics require an explicit opt-in.** Set `enableShadowTopics=true` on every target 5.0 broker before rolling a cluster that uses shadow topics. The new default is `false`, which disables shadow-topic creation, loading, and replication. Changing this setting requires a broker restart.
- **Remove obsolete dispatcher overrides.** The classic persistent Shared and Key_Shared dispatcher implementations have been removed. Remove `subscriptionSharedUseClassicPersistentImplementation` and `subscriptionKeySharedUseClassicPersistentImplementation` from file configuration and dynamic overrides. Test reconnects, redelivery, and per-key ordering with your Shared and Key_Shared workloads if either override was enabled.
- **Review changed defaults against explicit overrides.** The modular load manager changes its default shedding and placement strategies from `ThresholdShedder` / `LeastLongTermMessageRate` to `AvgShedder`. `maxUnloadPercentage` increases from `0.2` to `0.5`, and `loadBalancerDistributeBundlesEvenlyEnabled` changes from `true` to `false`. `dispatcherMaxReadBatchSize` increases from 100 to 500. Check both file and dynamic configuration; explicit old values are preserved. See [Load balanci [...]
-- **Review dispatch scheduling for expensive entry filters.** `dispatcherDispatchMessagesInSubscriptionThread` changes from `true` to `false`, avoiding an extra subscription-thread handoff. Configurations with compute-heavy server-side broker entry filters may benefit from setting it back to `true`, but this is not a general recommendation: test the change separately with representative workloads. The related `managedLedgerReadEntriesCallbackInline` optimization (default `true`) enables [...]
+- **Inline read completion and publish handover batching are enabled by default.** `managedLedgerReadEntriesCallbackInline` (default `true`) enables inline read completion. Publish-request handover batching is controlled by `managedLedgerAddEntryHandoverMaxBatchItems` (default 1,024) and `managedLedgerAddEntryHandoverMaxBatchBytesSize` (default 5 MiB). These batching limits can change publishing patterns, but handover batching has greatly improved performance in tests. There should norma [...]
- **Namespace creation defaults:** the broker default increases from 4 to 32 bundles. Cluster initialization changes `public/default` from 16 to 32 and `pulsar/system` from 16 to 64. New `defaultNumberOfSystemNamespaceBundles` and `--system-namespace-bundle-number` settings select the system-namespace count. Existing layouts are preserved; see [Namespace bundles](administration-namespace-bundles.md).
- **Load-manager initialization now fails fast.** Check `loadManagerClassName` and custom implementations during the canary. Instantiation or initialization failures no longer silently fall back to `SimpleLoadManagerImpl`.
- **Validate batch reads under representative load.** `managedLedgerBatchReadEnabled` defaults to `true`. Batch reads can greatly improve backlog-draining performance, but they change memory allocation patterns: entries are copied from batch responses into the entry cache using the `ml-cache` allocator. Keep `pulsar.allocator.ml-cache.type` at its default, `adaptive`. Some environments may need to establish stability before enabling batch reads during an existing-cluster upgrade. To defe [...]