[
https://issues.apache.org/jira/browse/ARTEMIS-3365?focusedWorklogId=614108&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-614108
]
ASF GitHub Bot logged work on ARTEMIS-3365:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 23/Jun/21 16:32
Start Date: 23/Jun/21 16:32
Worklog Time Spent: 10m
Work Description: gtully commented on a change in pull request #3634:
URL: https://github.com/apache/activemq-artemis/pull/3634#discussion_r657263437
##########
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.
Review comment:
it is just reachable. full stop. Does it really need to host a balancer?
##########
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:
Review comment:
client connection (not plural)
##########
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.
Review comment:
what happens when the quorum is set and not reached? Does the connection
just get rejected? expecting a retry?
##########
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.
Review comment:
is it just quorum (the size is implicit, as in quorum is the minimum
number of members that make the group valid.
##########
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;
+* `ROUND_ROBIN` to select a target sequentially from a pool.
+* `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 until the
target key 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: `SNI_HOST`, `SOURCE_IP`, `USER_NAME`.
+* the `local-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>
+ </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>
+</broker-balancers>
+```
+
+## Broker Balancer Workflow
+The broker balancer workflow include the following steps:
+* Retrieve the target key from the incoming connection;
+* Return the local target broker if the target key matches the local filter;
+* Return the cached target broker if it is ready;
+* Get ready target brokers from the pool;
+* Select one target broker using the policy;
+* Add the selected broker in the cache;
+* Return the selected broker.
+
+Let's take a look at flowchart of the broker balancer workflow:
+
+
+
+## Redirection
+Apache ActiveMQ Artemis 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.
+The acceptor with the `redirect-to` url parameter will redirect the incoming
connections.
+The `redirect-to` url parameter specifies the name of the broker balancer to
use,
+ie the following acceptor will redirect the incoming CORE client connections
using the broker balancer with the name `bb1`:
Review comment:
maybe it makes sense to reuse the name from above. in place of bb1 use
'consistent-hash-balancer' just to tie the url parameter to the name element of
the xml. If I have that correct!
##########
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;
+* `ROUND_ROBIN` to select a target sequentially from a pool.
+* `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 until the
target key is present in the cache and is ready.
Review comment:
until? should that be "as long as"
##########
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:
the _ELEMENT seems odd? FIRST on it's own or HEAD (but that implies a
list). Can you add a one liner when FIRST would make sense, ROUND_ROBIN with a
single entry in a pool would behave the same.
--
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: 614108)
Time Spent: 20m (was: 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: 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)
