[
https://issues.apache.org/jira/browse/ARTEMIS-3365?focusedWorklogId=614225&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-614225
]
ASF GitHub Bot logged work on ARTEMIS-3365:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 23/Jun/21 20:50
Start Date: 23/Jun/21 20:50
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_r657451663
##########
File path: docs/user-manual/en/broker-balancers.md
##########
@@ -0,0 +1,156 @@
+# 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).
+
+## 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 broker reachable by the broker that hosts the
broker balancer.
+
+## Target Key
+The broker balancer uses a target key to select a target broker.
+It is a string retrieved from an incoming client connections, the supported
values are:
+* `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 brokers and checks periodically their state.
+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 target broker, to include it the
`local-target-enabled` parameter must be `true`.
+A pool becomes ready when the minimum number of ready targets defined by the
`quorum-size` parameter is reached.
+This behaviour avoids weird distribution at startup or after a restart.
+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 numbers of ready tagrets;
+* 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>
+ <check-period>1000</check-period>
+ <local-target-enabled>true</local-target-enabled>
+ <quorum-size>2</quorum-size>
+ <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 a pool;
Review comment:
I can't find a better name so I used `FIRST_ELEMENT` to be consistent
with the similar client load balancing policy:
org.apache.activemq.artemis.api.core.client.loadbalance.FirstElementConnectionLoadBalancingPolicy
--
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.
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 614225)
Time Spent: 1h 20m (was: 1h 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: 1h 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)
