This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 0dc06561a97 [feat][doc] add migration tutorials for broker load
balancing (#657)
0dc06561a97 is described below
commit 0dc06561a97b0ebd21349f6af4fbcae91edf5836
Author: Anonymitaet <[email protected]>
AuthorDate: Thu Aug 3 09:31:42 2023 +0800
[feat][doc] add migration tutorials for broker load balancing (#657)
---
docs/concepts-broker-load-balancing-benefits.md | 4 +-
docs/concepts-broker-load-balancing-concepts.md | 2 +
docs/concepts-broker-load-balancing-features.md | 4 +-
docs/concepts-broker-load-balancing-migration.md | 170 +++++++++++++++++++++
docs/concepts-broker-load-balancing-overview.md | 2 +
docs/concepts-broker-load-balancing-types.md | 1 +
... => concepts-broker-load-balancing-use-case.md} | 4 +-
sidebars.json | 3 +-
8 files changed, 186 insertions(+), 4 deletions(-)
diff --git a/docs/concepts-broker-load-balancing-benefits.md
b/docs/concepts-broker-load-balancing-benefits.md
index 1e5e969dd12..5acbe52cc48 100644
--- a/docs/concepts-broker-load-balancing-benefits.md
+++ b/docs/concepts-broker-load-balancing-benefits.md
@@ -48,4 +48,6 @@ It helps seamlessly scale up or down broker clusters since it
allows you to:
- To learn essential fundamentals, see [Broker load balancing |
Concepts](./concepts-broker-load-balancing-concepts.md).
-- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
\ No newline at end of file
+- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
+
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
\ No newline at end of file
diff --git a/docs/concepts-broker-load-balancing-concepts.md
b/docs/concepts-broker-load-balancing-concepts.md
index 37d0ce25dd5..c2c269cfc0e 100644
--- a/docs/concepts-broker-load-balancing-concepts.md
+++ b/docs/concepts-broker-load-balancing-concepts.md
@@ -563,3 +563,5 @@ For implementation details, see [PIP-220:
TransferShedder](https://github.com/ap
- To understand advantages, see [Broker load balancing |
Benefits](./concepts-broker-load-balancing-benefits.md).
- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
+
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
\ No newline at end of file
diff --git a/docs/concepts-broker-load-balancing-features.md
b/docs/concepts-broker-load-balancing-features.md
index d26ff470a5f..0e67e7ad400 100644
--- a/docs/concepts-broker-load-balancing-features.md
+++ b/docs/concepts-broker-load-balancing-features.md
@@ -22,4 +22,6 @@ In general, the main features of the broker load balancer are:
- To learn essential fundamentals, see [Broker load balancing |
Concepts](./concepts-broker-load-balancing-concepts.md).
-- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
\ No newline at end of file
+- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
+
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
\ No newline at end of file
diff --git a/docs/concepts-broker-load-balancing-migration.md
b/docs/concepts-broker-load-balancing-migration.md
new file mode 100644
index 00000000000..17e22ee19f4
--- /dev/null
+++ b/docs/concepts-broker-load-balancing-migration.md
@@ -0,0 +1,170 @@
+---
+id: concepts-broker-load-balancing-migration
+title: Migration
+sidebar_label: "Migration"
+---
+
+Pulsar has 3 types of broker load balancers, that is, simple, modular, and
extensible.
+
+You can perform the following migrations.
+
+Migration|When to use
+|---|---
+[Migrate from simple to
modular](#migrate-from-simple-to-modular-broker-load-balancer)| If you want to
use the [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
of OverloadShedder, ThresholdShedder, or UniformLoadShedder.
+[Migrate from modular to
extensible](#migrate-from-modular-to-extensible-broker-load-balancer)| If you
want to use the [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
of TransferShedder.
+[Migrate from extensible to
modular](#migrate-from-modular-to-extensible-broker-load-balancer)| If you want
to use the [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
of OverloadShedder, ThresholdShedder, or UniformLoadShedder.
+
+:::note
+
+It is not recommended to migrate from the modular or extensible to the simple
broker load balancer since the simple broker load balancer is deprecated and no
longer in use.
+
+:::
+
+
+## Considerations
+
+Before migrating from one broker load balancer type to another, review the
relationship between [broker load balancer
type](./concepts-broker-load-balancing-types.md), Pulsar version, and [bundle
unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies).
You may need to upgrade Pulsar versions or update the [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies).
Below are brief summaries.
+
+This broker load balancer type | is available in this Pulsar version
+|---|---
+Simple|All versions
+Modular|1.7 and later
+Extensible|3.0 and later
+
+This bundle unloading strategy|is available for this broker load balancer
type|in available this Pulsar version
+|---|---|---
+OverloadShedder|Modular|1.18 and later
+ThresholdShedder|Modular|2.6 and later
+UniformLoadShedder|Modular|2.10 and later
+TransferShedder|Extensible|3.0 and later
+
+## Migrate from simple to modular broker load balancer
+
+You can migrate from the simple to the modular broker load balancer, by
manually changing the configuration settings in the broker.conf file or by
using the pulsar-admin tool.
+
+### Change broker.conf file
+
+1. Access to the broker.conf file.
+
+ ```bash
+ vim apache-pulsar-@pulsar:version@/conf/broker.conf
+ ``````
+
+2. Change the broker load balancer by setting
[loadManagerClassName](https://github.com/apache/pulsar/blob/69d7a2bf14555f11a716a9545c5cf391d8179a27/conf/broker.conf#L1309C20-L1309C20)
to `ModularLoadManagerImpl` in the broker.conf file.
+
+ ```conf
+
loadManagerClassName=org.apache.pulsar.broker.loadbalance.extensions.ModularLoadManagerImpl
+ ```
+
+3. Restart the Pulsar cluster. The new setting will take effect after the
restart.
+
+### Use pulsar-admin tool
+
+1. Access the [pulsar-admin
tool](https://pulsar.apache.org/docs/next/reference-cli-tools/).
+
+ ```bash
+ cd apache-pulsar-@pulsar:version@/bin
+ ```
+
+2. Set `--config` to `loadManagerClassName` and `--value` to
`org.apache.pulsar.broker.loadbalance.impl.ModularLoadManagerImpl`.
+
+ ```bash
+ pulsar-admin brokers update-dynamic-config \
+ --config loadManagerClassName \
+ --value org.apache.pulsar.broker.loadbalance.impl.ModularLoadManagerImpl
+ ```
+
+ You do not need to restart the Pulsar cluster. The new settings will take
effect after 1 to 2 minutes.
+
+## Migrate from modular to extensible broker load balancer
+
+You can migrate from the modular to the extensible broker load balancer, by
manually changing settings in the broker.conf file. During the migration, the
lookup and assignment will be redirected to the brokers with the extensible
load balancer.
+
+:::note
+
+The pulsar-admin tool is not supported for this migration.
+
+:::
+
+### Change broker.conf file
+
+1. [Upgrade the Pulsar cluster](./helm-upgrade.md) to 3.0.0 or later versions.
+
+2. Access to the broker.conf file.
+
+ ```bash
+ vim apache-pulsar-@pulsar:version@/conf/broker.conf
+ ```
+
+3. Change the following settings in the broker.conf file:
+
+ - Update [broker load
balancer](./concepts-broker-load-balancing-overview.md) by setting
[loadManagerClassName](https://github.com/apache/pulsar/blob/69d7a2bf14555f11a716a9545c5cf391d8179a27/conf/broker.conf#L1309C20-L1309C20)
to `ExtensibleLoadManagerImpl`.
+
+ - Update [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
by setting `loadBalancerLoadSheddingStrategy` to `TransferShedder`.
+
+ ```conf
+
loadManagerClassName=org.apache.pulsar.broker.loadbalance.extensions.ExtensibleLoadManagerImpl
+
+
loadBalancerLoadSheddingStrategy=org.apache.pulsar.broker.loadbalance.extensions.scheduler.TransferShedder
+ ```
+
+ :::note
+
+ - The [extensible broker load
balancer](./concepts-broker-load-balancing-types.md) is **available in Pulsar
3.0.0** or later.
+ - The [TransferShedder unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
is **only available** in the [extensible load
balancer](./concepts-broker-load-balancing-types.md).
+
+ :::
+
+4. Restart the Pulsar cluster. The new settings will take effect after the
restart.
+
+## Migrate from extensible to modular broker load balancer
+
+You can migrate from the extensible to the modular broker load balancer, by
manually changing the setting in the broker.conf file. During the migration,
the lookup and assignment will be redirected to the brokers with the modular
load balancer.
+
+:::note
+
+The pulsar-admin tool is not supported for this migration.
+
+:::
+
+### Change broker.conf file
+
+1. Access to the broker.conf file.
+
+ ```bash
+ vim apache-pulsar-@pulsar:version@/conf/broker.conf
+ ```
+
+2. Change the following settings in the broker.conf file:
+
+ - Update broker load balancer by setting
[loadManagerClassName](https://github.com/apache/pulsar/blob/69d7a2bf14555f11a716a9545c5cf391d8179a27/conf/broker.conf#L1309C20-L1309C20)
to ModularLoadManagerImpl
+
+ - Update [bundle unloading
strategy](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
to OverloadShedder, ThresholdShedder, or UniformLoadShedder based on your
needs.
+
+ ```
+
loadManagerClassName=org.apache.pulsar.broker.loadbalance.impl.ModularLoadManagerImpl
+
+
loadBalancerLoadSheddingStrategy=org.apache.pulsar.broker.loadbalance.impl.ThresholdShedder
+ ```
+
+ :::note
+
+
[TransferShedder](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies)
is **only supported** in the extensible broker load balancer, so you need to
change TransferShedder to other [bundle unloading
strategies](./concepts-broker-load-balancing-concepts.md#bundle-unloading-strategies).
+
+ :::
+
+3. Restart the Pulsar cluster. The new settings will take effect after the
restart.
+
+## Related topics
+
+- To get a comprehensive understanding and discover the key insights, see
[Broker load balancing |
Overview](./concepts-broker-load-balancing-overview.md).
+
+- To discover different usage scenarios, see [Broker load balancing | Use
cases](./concepts-broker-load-balancing-use-cases.md).
+
+- To explore functionalities, see [Broker load balancing |
Features](./concepts-broker-load-balancing-features.md).
+
+- To understand advantages, see [Broker load balancing |
Benefits](./concepts-broker-load-balancing-benefits.md).
+
+- To learn essential fundamentals, see [Broker load balancing |
Concepts](./concepts-broker-load-balancing-concepts.md).
+
+- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
diff --git a/docs/concepts-broker-load-balancing-overview.md
b/docs/concepts-broker-load-balancing-overview.md
index 32e6a19e135..55cee04b8f6 100644
--- a/docs/concepts-broker-load-balancing-overview.md
+++ b/docs/concepts-broker-load-balancing-overview.md
@@ -39,3 +39,5 @@ Pulsar uses automatic broker load balancing to monitor the
brokers' load interna
- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
+
diff --git a/docs/concepts-broker-load-balancing-types.md
b/docs/concepts-broker-load-balancing-types.md
index 917e2735b6c..b436f841c68 100644
--- a/docs/concepts-broker-load-balancing-types.md
+++ b/docs/concepts-broker-load-balancing-types.md
@@ -44,3 +44,4 @@ However, for bundle ownership and load data stores, the
modular load balancer us
- To learn essential fundamentals, see [Broker load balancing |
Concepts](./concepts-broker-load-balancing-concepts.md).
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
\ No newline at end of file
diff --git a/docs/concepts-broker-load-balancing-use-cases.md
b/docs/concepts-broker-load-balancing-use-case.md
similarity index 91%
rename from docs/concepts-broker-load-balancing-use-cases.md
rename to docs/concepts-broker-load-balancing-use-case.md
index a18e3fa6438..61bfb54b7ea 100644
--- a/docs/concepts-broker-load-balancing-use-cases.md
+++ b/docs/concepts-broker-load-balancing-use-case.md
@@ -26,4 +26,6 @@ The broker load balancer can increase cluster availability by
re-routing data lo
- To learn essential fundamentals, see [Broker load balancing |
Concepts](./concepts-broker-load-balancing-concepts.md).
-- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
\ No newline at end of file
+- To review various versions of broker load balancers, see [Broker load
balancing | Types](./concepts-broker-load-balancing-types.md).
+
+- To migrate one broker load balancer type to another, see [Broker load
balancing | Migration](./concepts-broker-load-balancing-migration.md).
\ No newline at end of file
diff --git a/sidebars.json b/sidebars.json
index 170cba090bc..1e96d0d434f 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -35,7 +35,8 @@
"concepts-broker-load-balancing-features",
"concepts-broker-load-balancing-benefits",
"concepts-broker-load-balancing-concepts",
- "concepts-broker-load-balancing-types"
+ "concepts-broker-load-balancing-types",
+ "concepts-broker-load-balancing-migration"
]
},
"concepts-replication",
