[
https://issues.apache.org/jira/browse/ARTEMIS-3365?focusedWorklogId=634736&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-634736
]
ASF GitHub Bot logged work on ARTEMIS-3365:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 05/Aug/21 18:55
Start Date: 05/Aug/21 18:55
Worklog Time Spent: 10m
Work Description: brusdev commented on a change in pull request #3634:
URL: https://github.com/apache/activemq-artemis/pull/3634#discussion_r683710314
##########
File path: docs/user-manual/en/broker-balancers.md
##########
@@ -0,0 +1,176 @@
+# Broker Balancers
+Apache ActiveMQ Artemis broker balancers allow incoming client connections to
be distributed across multiple [target brokers](target-brokers).
+The target brokers are grouped in [pools](#pools) and the broker balancers use
a [target key](#target-key)
+to select a target broker from a pool of brokers according to a
[policy](#policies).
+
+### This feature is still **EXPERIMENTAL** and not meant to be run in
production yet. Furthermore, its configuration can change until declared as
**officially stable**.
+
+## Target Broker
+Target broker is a broker that can accept incoming client connections and is
local or remote.
+The local target is a special target that represents the same broker hosting
the broker balancer.
+The remote target is another reachable broker.
+
+## Target Key
+The broker balancer uses a target key to select a target broker.
+It is a string retrieved from an incoming client connection, the supported
values are:
+* `CLIENT_ID` is the JMS client ID;
+* `SNI_HOST` is the hostname indicated by the client in the SNI extension of
the TLS protocol;
+* `SOURCE_IP` is the source IP address of the client;
+* `USER_NAME` is the username indicated by the client.
+
+## Pools
+The pool is a group of target brokers and checks periodically their state.
+It provides a list of ready target brokers to distribute incoming client
connections only when it is active.
+A pool becomes active when the minimum number of ready target brokers defined
by the `quorum-size` parameter is reached.
+When it is not active, it doesn't provide any target avoiding weird
distribution at startup or after a restart.
+Including the local target broker in the pool allows broker hosting the broker
balancer to accept incoming client connections.
+By default, a pool doesn't include the local broker, to include it as a target
the `local-target-enabled` parameter must be `true`.
+There are two pool types: [discovery pool](#discovery-pool) and [static
pool](#static-pool).
+
+### Discovery Pool
+The discovery pool uses a [discovery group](clusters.md#discovery-groups) to
discover the target brokers to add.
+Let's take a look at a discovery pool example from broker.xml that uses a
discovery group:
+```xml
+<pool>
+ <discovery-group-ref discovery-group-name="dg1"/>
+</pool>
+```
+
+### Static Pool
+The static pool uses a list of static connectors to define the target brokers
to add.
+Let's take a look at a static pool example from broker.xml that uses a list of
static connectors:
+```xml
+<pool>
+ <static-connectors>
+ <connector-ref>connector1</connector-ref>
+ <connector-ref>connector2</connector-ref>
+ <connector-ref>connector3</connector-ref>
+ </static-connectors>
+</pool>
+```
+
+### Defining pools
+A pool is defined by the `pool` element that includes the following items:
+* the `username` element defines the username to connect to the target broker;
+* the `password` element defines the password to connect to the target broker;
+* the `check-period` element defines the often to check the target broker;
+* the `quorum-size` element defines the minimum number of ready targets to
activate the pool;
+* the `quorum-timeout` element defines the timeout to get the minimum number
of ready targets;
+* the `local-target-enabled` element defines whether the pool has to include a
local target;
+* the `static-connectors` element defines a list of static connectors used by
the [static pool](#static-pool);
+* the `discovery-group` element defines the [discovery
group](clusters.md#discovery-groups) used by the [discovery
pool](#discovery-pool).
+
+Let's take a look at a pool example from broker.xml:
+```xml
+<pool>
+ <quorum-size>2</quorum-size>
+ <check-period>1000</check-period>
+ <local-target-enabled>true</local-target-enabled>
+ <static-connectors>
+ <connector-ref>connector1</connector-ref>
+ <connector-ref>connector2</connector-ref>
+ <connector-ref>connector3</connector-ref>
+ </static-connectors>
+</pool>
+```
+
+## Policies
+The policy define how to select a broker from a pool. The included policies
are:
+* `FIRST_ELEMENT` to select the first target broker from the pool which is
ready. It is useful to select the ready target brokers
+ according to the priority defined with their sequence order, ie supposing
there are 2 target brokers
+ this policy selects the second target broker only when the first target
broker isn't ready.
+* `ROUND_ROBIN` to select a target sequentially from a pool, this policy is
useful to evenly distribute;
+* `CONSISTENT_HASH` to select a target by a key. This policy always selects
the same target broker for the same key until it is removed from the pool.
+* `LEAST_CONNECTIONS` to select the targets with the fewest active
connections. This policy helps you maintain an equal distribution of active
connections with the target brokers.
+
+A policy is defined by the `policy` element. Let's take a look at a policy
example from broker.xml:
+```xml
+<policy name="FIRST_ELEMENT"/>
+```
+
+## Cache
+The broker balancer provides a cache with a timeout to improve the stickiness
of the target broker selected.
+The broker balancer returns the same target broker for a target key as long as
it is present in the cache and is ready.
+By default, the cache is enabled, to disable the cache the `cache-timeout`
parameter must be `0`.
+
+## Defining broker balancers
+A broker balancer is defined by `broker-balancer` element, it includes the
following items:
+* the `name` attribute defines the name of the broker balancer;
+* the `target-key` element defines what key to select a target broker, the
supported values are: `CLIENT_ID`, `SNI_HOST`, `SOURCE_IP`, `USER_NAME`.
+* the `target-key-filter` element defines a regular expression to filter the
resolved keys;
+* the `local-target-filter` element defines a regular expression to filter the
keys that have to return a local target;
+* the `cache-timeout` element is the time period for a target broker to remain
in the cache;
+* the `pool` element defines the pool to group the target brokers, see
[pools](#pools).
+* the `policy` element defines the policy used to select the target brokers,
see [policies](#policies);
+
+Let's take a look at some broker balancer examples from broker.xml:
+```xml
+<broker-balancers>
+ <broker-balancer name="simple-balancer">
+ <policy name="FIRST_ELEMENT"/>
+ <pool>
+ <static-connectors>
+ <connector-ref>connector1</connector-ref>
+ <connector-ref>connector2</connector-ref>
+ <connector-ref>connector3</connector-ref>
+ </static-connectors>
+ </pool>
+ </broker-balancer>
+ <broker-balancer name="consistent-hash-balancer">
+ <target-key>USER_NAME</target-key>
+ <local-filter>admin</local-filter>
+ <policy name="CONSISTENT_HASH"/>
+ <pool>
+ <local-target-enabled>true</local-target-enabled>
+ <discovery-group-ref discovery-group-name="dg1"/>
+ </pool>
+ <policy name="CONSISTENT_HASH"/>
+ </broker-balancer>
+ <broker-balancer name="least-connections-balancer">
+ <policy name="LEAST_CONNECTIONS"/>
+ <pool>
+ <discovery-group-ref discovery-group-name="dg2"/>
+ </pool>
+ </broker-balancer>
Review comment:
doc updated
##########
File path: examples/features/broker-balancer/evenly-redirect/readme.md
##########
@@ -0,0 +1,6 @@
+# Evenly Redirect Example
+
+To run the example, simply type **mvn verify** from this directory, or **mvn
-PnoServer verify** if you want to create and start the broker manually.
+
+This example demonstrates how incoming client connections are evenly
redirected across two brokers
+using a third broker with a broker balancer to redirect incoming client
connections.
Review comment:
doc updated
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 634736)
Time Spent: 9h 20m (was: 9h 10m)
> Broker Balancers
> ----------------
>
> Key: ARTEMIS-3365
> URL: https://issues.apache.org/jira/browse/ARTEMIS-3365
> Project: ActiveMQ Artemis
> Issue Type: New Feature
> Reporter: Domenico Francesco Bruscino
> Assignee: Domenico Francesco Bruscino
> Priority: Major
> Time Spent: 9h 20m
> Remaining Estimate: 0h
>
> This feature adds the broker balancers to distribute the incoming client
> connections across multiple brokers.
> It provides a native redirection for supported clients and a new management
> API for other clients. The native redirection can be enabled per acceptor and
> is supported only for CORE and AMQP clients.
> See the [draft
> documentation|https://github.com/brusdev/activemq-artemis/blob/broker_balancers/docs/user-manual/en/broker-balancers.md]
> for further details.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
