Chapter 3. New and Changed Features This section describes a highlighted set of enhancements and new features in AMQ Broker 7.11. Validation changes for image and version attributes in a CR In 7.11.5, the Operator validates the configuration of image and version attributes in a CR differently to versions. Before 7.11.5, the Operator validates that a CR does not have: A spec.deploymentPlan.image attribute without a spec.deploymentPlan.initImage attribute or vice versa. A spec.version attribute with either a spec.deploymentPlan.image and a spec.deploymentPlan.initImage attribute, or both. In 7.11.5, the Operator continues to validate that a CR does not have a spec.deploymentPlan.image attribute without a spec.deploymentPlan.initImage attribute or vice versa. In 7.11.5, the Operator validation is changed to also verify that: The version number specified in the spec.version attribute, if present, matches the version of the broker container images deployed. If the versions are not the same, the Operator sets the status of the BrokerVersionAligned condition in the CR to Unknown to highlight the mismatch for information purposes, but the mismatch does not affect the running of the brokers in the deployment. A CR does not have spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes without a spec.version attribute. If a CR has spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes without a spec.version attribute, the Operator sets the status of the Valid condition in the CR to Unknown to warn that the configuration is incomplete. Note A missing spec.version attribute causes the Operator to restart the broker Pods in the deployment each time the Operator is upgraded. The Pod restart is required because the Operator updates a label in the StatefulSet with the latest supported broker version, unless a version number is explicitly set in the spec.version attribute. To prevent each future Operator upgrade from restarting the broker, you must set the version number of the broker deployed in the spec.version attribute in the CR. In 7.11.5, you can find the version number of the broker deployed in the status section of the CR after you start the broker. For more information, see Viewing status information for your broker deployment in Deploying AMQ Broker on Openshift . Prior to 7.11.5, you can find the version number in a broker Pod's log file by using the OpenShift Container Platform web console: Click Workloads Pods . Click a broker Pod name. Click the Logs tab. The version number is displayed after the Artemis banner at the top of the log output. Note Conditions that have a status value of Unknown do not prevent the Operator from completing the broker deployment. Leader election settings for the Operator can be customized Starting in 7.11.5, you can customize the settings used by the Operator for leader elections. If you use Operator Hub to install the Operator, you can use the OpenShift Container Platform web console to configure the leader election settings in the Operator subscription after you install the Operator. If you use the OpenShift Container Platform command-line interface to install the Operator, you can configure the leader elections settings in the Operator configuration file, operator.yaml , either before or after you install the Operator. The following is an example of the leader elections settings configured in the operator.yaml file: apiVersion: apps/v1 kind: Deployment ... template ... spec: containers: - args: - --leader-elect - --lease-duration=60 - --renew-deadline=40 - --retry-period=5 ... The following is an example of the leader elections settings configured in the Operator subscription: apiVersion: operators.coreos.com/v1alpha1 kind: Subscription ... spec: ... config: env: - name: ARGS value: "--leader-elect --lease-duration=60 --renew-deadline=60 --retry-period=5" leader-elect : Enables the Operator to compete in a leader election with other instances to ensure that no more than one instance operates at a time. lease-duration : The duration, in seconds, that a non-leader Operator waits before it attempts to acquire the lease that was not renewed by the leader. The default is 15 . renew-deadline : The duration, in seconds, a leader Operator waits between attempts to renew the leader role before it stops leading. The default is 10 . retry-period : The duration, in seconds, that the Operator waits between attempts to acquire and renew the leader role. The default is 2 . Individual attributes in an address-settings element can be updated In 7.11.5, you can use the Jolokia REST interface to JMX to update individual attributes in an address-settings element in JSON format. Previously, if you wanted to update an attribute or subset of attributes in an address-settings element, it was necessary to also include all the unchanged address-settings attributes in the update operation. Warning level messages changed to error level in the Critical Analyzer In 7.11.5, the Critical Analyzer assigns an ERROR level to messages that were previously assigned a WARN level. New parameters to provide greater control over the flow of paged messages into memory Before 7.11.3, you control the flow of paged messages into memory by setting limits for the max-read-page-bytes and max-read-page-messages parameters. When applying these limits, the broker counts both messages in memory that are ready for delivery to consumers and messages that are currently delivering. If consumers are slow to acknowledge messages, the memory or message limit can be used by messages that are currently delivering, which prevents the broker reading new messages into memory. As a result, the broker can be starved of messages. Starting in 7.11.3 you can set limits for two new parameters to control the flow of paged messages into memory. When applying these limits the broker does not take into account delivering messages. prefetch-page-bytes Memory, in bytes, that is available to read paged messages into memory per-queue. The default value is 20MB. prefetch-page-messages Number of paged messages that the broker can read from disk into memory per-queue. The default value is -1, which means that no limit applies. If consumers are slow to acknowledge messages, you can increase the default limits for the max-read-page-bytes and max-read-page-message parameters to provide capacity for delivering messages. The default limits for the prefetch-page-bytes and the prefetch-page-messages parameters then allow the broker to read new messages into memory. Note If the value of the max-read-page-bytes parameter is reached before the value of the prefetch-page-bytes parameter, the broker stops reading further paged messages into memory. AMQ Core Protocol JMS client can fail over to other live brokers in a cluster Prior to 7.11.2, if an AMQ Core Protocol JMS client loses the connection to a live broker, it can fail over only to a backup broker when both brokers are configured as a live/backup pair for high availability (HA). Starting in 7.11.2, the AMQ Core Protocol JMS client can be configured to fail over to a backup broker in a HA pair or to any other live broker in a cluster. To enable the client to fail over to any live broker in a cluster, specify the failoverAttempts configuration option in the connection URI of the client. For example: With the failoverAttempts option set to a value of 2, the client attempts to connect to 2 other live brokers in the cluster. The failover attempts occur if the client fails all connection attempts to the live broker in a non-HA configuration and the live and backup broker in a HA configuration. Note The reconnnectAttempts configuration option, shown in the example, is used to fail over only from the live broker to a backup broker if both brokers are configured in a HA pair. Paging performance improvements when AMQ Broker uses JDBC persistence Starting in 7.11.2, paging performance is improved when AMQ Broker is configured to use JDBC persistence. As part of the paging improvements, a new parameter, jdbc-max-page-size-bytes , limits the page size to 100KB by default when using JDBC. You can customize the default limit. For more information, see Configuring JDBC persistence in Configuring AMQ Broker . Batching of federated messages If the backlog on your queues exceeds the available capacity of local consumers, any lower priority federation consumer becomes a candidate to receive messages. Eventually, too many messages may move to federated consumers and cause the same scenario to occur on the other cluster, with the result that messages move back and forth between brokers. Starting in 7.11.2, you can configure federated consumers to pull batches of messages only when the local queue has excess capacity. As a result, federation does not move more messages than federated consumers can process, which avoids a scenario where messages move back and forth between brokers. To configure federated consumers to pull batches of messages, set the consumerWindowSize value to 0 on the connection URI of federated consumers. With the consumerWindowSize value set to 0 , AMQ Broker uses the value of the defaultConsumerWindowSize attribute in the address settings for a matching address to determine the batch size of messages moved between brokers. The default value for the defaultConsumerWindowSize attribute is 1048576 bytes. Use this batching mode of operation for bidirectional federation between active brokers. For more information about federation, see Federating addresses and queues in Configuring AMQ Broker . Broker startup health check Starting in 7.11.2, you can configure a startup probe to check that the AMQ Broker application within an OpenShift Container Platform container started successfully. To learn how to configure health checks, see Configuring broker health checks in Deploying AMQ Broker on Openshift . Limiting disk space used for paging If you configure AMQ Broker to page messages, you can limit the disk space used to page incoming messages to prevent the paging operation from using excessive disk space. For more information, see Limiting disk usage during paging for specific addresses in Configuring AMQ Broker . Limiting the memory used for messages read from paging If you configure AMQ Broker to page messages, you can limit the memory used to store messages that the broker transfers from disk back to memory when clients are ready to consume messages. For more information, see Controlling the flow of paged messages into memory in Configuring AMQ Broker . Important If client applications leave too many messages pending acknowledgment, the broker does not read paged messages until the pending messages are acknowledged, which can cause message starvation on the broker. For example, if the limit for the transfer of paged messages into memory, which is 20MB by default, is reached, the broker waits for an acknowledgment from a client before it reads any more messages. If, at the same time, clients are waiting to receive sufficient messages before they send an acknowledgment to the broker, which is determined by the batch size used by clients, the broker is starved of messages. To avoid starvation, either increase the broker limits that control the transfer of paged message into memory or reduce the number of delivering messages. You can reduce the number of delivering messages by ensuring that clients either commit message acknowledgments sooner or use a timeout and commit acknowledgments when no more messages are received from the broker. You can see the number and size of delivering messages in a queue's Delivering Count and Delivering Bytes metrics in AMQ Management Console. Log4j 2 logging support Starting in 7.11, AMQ Broker uses the Log4j 2 logging utility instead of the JBoss Logging framework to provide message logging. You can customize the Log4j 2 logging configuration on both OpenShift Container Platform and RHEL platforms. Changing the Operator logging level In AMQ Broker 7.11 on OpenShift Container Platform, you can change the default logging level to increase or decrease the detail that is written to the Operator logs. For more information, see Changing the logging level for the Operator in Deploying AMQ Broker on Openshift . Support for Java Authentication and Authorization Service (JAAS) login modules In AMQ Broker 7.11 on OpenShift Container Platform, you can configure JAAS login modules in a secret instead of using the ActiveMQArtemisSecurity CR to configure user authentication and authorization for AMQ Broker. By configuring JAAS login modules in a secret, you can update user and role information in properties files without needing to restart the broker. In addition, you can configure login modules, such as LDAP, which are not configurable in the CR. For more information, see Configuring JAAS login modules in a secret in Deploying AMQ Broker on Openshift . Restricting upgrades In AMQ Broker 7.11 on OpenShift Container Platform, the Operator automatically upgrades the broker container images to the latest available version. You can configure the Custom Resource (CR) for your deployment to prevent automatic upgrades or to permit automatic upgrades only to specific versions or to specific broker and init container images. Note If you want to restrict automatic upgrades, you must specify either the combined spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes or the spec.version attribute, but not both, in the CR. For more information, see Restricting automatic upgrades in Deploying AMQ Broker on Openshift . Extended status reporting In AMQ Broker 7.11 on OpenShift Container Platform, the status information reported by the Operator in the main broker CR is extended to include: The validity of the content of the CR. The application of properties configured in the brokerProperties attribute. The propagation of Java Authentication and Authorization Service (JAAS) login module files in a secret to the broker Pods. The version of the broker that is deployed and the URLs of the broker and init container images for that version. The ability to apply major, minor, patch and security upgrades to the deployment. Synchronous mirroring support Starting in 7.11, you can configure synchronous mirroring between brokers to ensure that messages are written to the volumes of both brokers in the mirror at the same time. By using synchronous mirroring, you ensure that the mirrored broker is up-to-date for disaster recovery. For more information, see Configuring broker connections in Configuring AMQ Broker . Pod disruption budget In AMQ Broker 7.11 on OpenShift Container Platform, you can configure a Pod disruption budget to specify the minimum number of Pods in a cluster that must be available simultaneously during a voluntary disruption, such as a maintenance window. For more information, see Configuring a Pod disruption budget in Deploying AMQ Broker on OpenShift . brokerProperties configuration is stored in a mutable secret In AMQ Broker 7.11 on OpenShift Container Platform, the configuration created by using the brokerProperties attribute in the CR is stored in a mutable secret. A mutable secret can be updated without requiring a broker restart. Therefore, configuration updates are applied when the broker reloads the configuration periodically, apart from any update that specifically requires a broker restart. Operations to control the embedded web server Starting in 7.11, you can stop and restart the embedded web server for AMQ Broker by using the stopEmbeddedWebServer , startEmbeddedWebServer and restartEmbeddedWebServer operations on the ActiveMQServerControl JMX MBean. By using these operations, you can avoid restarting AMQ Broker if, for example, you renew the SSL certificate for AMQ Broker. The credentials used to log in to AMQ Management Console are used to send messages In versions of AMQ Broker, it was necessary to specify a username and password in the AMQ Management Console Preferences page in order to send messages in AMQ Management Console. Starting in 7.11, messages are sent using the credentials that you use to log in to AMQ Management Console. You can override the default behavior and specify different credentials to send individual messages. For more information, see, Sending messages to an address in Managing AMQ Broker . AMQ Broker on OpenShift Container Platform is preconfigured to collect metric data for Prometheus In AMQ Broker 7.11 on OpenShift Container Platform, the AMQ Broker container Pods are preconfigured to allow the Prometheus Operator Service Monitor to collect metric data. In releases, you needed to expose the port required by Service Monitor to collect metric data. Setting environment variables for broker containers In AMQ Broker 7.11 on OpenShift Container Platform, you can set environment variables in a Custom Resource (CR) that are passed to each broker container. For example, you can add the TZ environment variable to set the timezone of the broker container. For more information, see Setting environment variables for broker containers in Deploying AMQ Broker on OpenShift . Proxy forwarding support on OpenShift Container Platform In AMQ Broker 7.11 on OpenShift Container Platform, the embedded web server, which hosts AMQ Management Console, is preconfigured to handle X-Forwarded headers. By handling X-Forwarded headers, AMQ Management Console can receive header information that is otherwise altered or lost when a proxy is involved in the path of a request. For example, AMQ Management Console uses HTTP but the OpenShift Container Platform router, which is a proxy, exposes AMQ Management Console using a HTTPS route that terminates at the router. From the X-Forwarded header, AMQ Management Console can identify that the connection between the browser and the router uses HTTPS and switch to HTTPS to serve browser requests. Some redelivery attributes are supported only in the brokerProperties CR attribute If a 7.8.x or 7.9.x deployment has the redeliveryDelayMultiplier or the redeliveryCollisionAvoidanceFactor attributes configured in the spec.deploymentPlan.addressSettings.addressSetting CR element, you must configure these attributes in the brokerProperties CR attribute after you upgrade to 7.11.x. This is required because the data type of both attributes changed from float to string in 7.10.0. As a result, these attributes are no longer supported in the spec.deploymentPlan.addressSettings.addressSetting attribute. The following example shows how to configure both attributes in the brokerProperties element: spec: ... brokerProperties: - "addressSettings.#.redeliveryMultiplier=2.1" - "addressSettings.#.redeliveryCollisionAvoidanceFactor=1.2" ... Note In the brokerProperties attribute, use the redeliveryMultiplier attribute name instead of the redeliveryDelayMultiplier attribute name that was used in the spec.deploymentPlan.addressSettings.addressSetting element. Disabling XML External Entity (XXE) processing If you don't need to modularize your broker configuration in separate files that are included in the broker.xml file, you can now disable XXE processing to protect against XXE security vulnerabilities. Where possible, Red Hat recommends that you disable XXE processing. For more information, see Disabling External XML Entity (XXE) processing in Configuring AMQ Broker . JGroups 5.x Versions of AMQ Broker before 7.10.0 used JGroups 3.x. AMQ Broker 7.11 uses JGroups 5.x which is not backwardly compatible with JGroups 3.x. Some protocols and protocol properties changed between the two JGroup versions, so you may have to change the JGroups stack configuration when you upgrade to AMQ Broker 7.11. Contents of AMQ Broker archive extracted to a specific directory name When you extract the AMQ Broker archive on Red Hat Enterprise Linux, the contents of the archive are extracted to a directory called apache-artemis-2.28.0.redhat-00022 in your current directory. Operator channels The AMQ Broker Operator, Red Hat Integration - AMQ Broker for RHEL 8 (Multiarch) , is available with the following channels: 7.11.x - This channel provides updates for version 7.11 only and is a Long Term Support (LTS) channel. 7.10.x - This channel provides updates for version 7.10 only and is a Long Term Support (LTS) channel. Note It is not possible to upgrade the Operator by switching channels. You must uninstall the existing Operator and install the new version of the Operator from the appropriate channel. To determine which Operator to choose, see the Red Hat Enterprise Linux Container Compatibility Matrix . Change to class name of the Prometheus metrics plugin In AMQ Broker 7.11, the class name of the Prometheus metrics plugin that is included with AMQ Broker changed from org.apache.activemq.artemis.core.server.metrics.plugins.ArtemisPrometheusMetricsPlugin to com.redhat.amq.broker.core.server.metrics.plugins.ArtemisPrometheusMetricsPlugin . If the Prometheus metrics plugin is enabled in a version of AMQ Broker, you must update the class name in the broker.xml configuration file when you upgrade to AMQ Broker 7.11. For more information, see Upgrading a broker instance from 7.10.x to 7.11.x in Managing AMQ Broker . Changes to the data returned by the listProducers API method and the listProducersInfoAsJSON JMX method In AMQ Broker 7.11, the following are enhancements to how data is returned by the listProducers method, which is used by AMQ Management Console: In the data returned in versions, a producer was displayed per-session. Therefore, if you created a producer using the Core protocol, which creates two sessions per-producer, separate producers are shown for each of the two sessions. Also, if you created a producer without sending messages from the producer, the address returned for the producer was empty. In AMQ Broker 7.11, the listProducers method returns a single producer for the two sessions created by the Core protocol. In addition, the address column shows the correct address, even before you send messages. Previously, when you used an anonymous producer to send messages to multiple addresses using the Core or AMQP protocols a producer was displayed for each address. In addition, the address shown was for the first address to which the producer sent the message, which made it appear like a normal producer sending to a single queue. In AMQ Broker 7.11, when you use an anonymous producer to send messages to multiple addresses, a single producer is displayed for each anonymous producer. In addition, the address is not connected to a specific address and has a value of ANONYMOUS . Previously, the listProducersInfoAsJSON method provided a count of messages sent to each queue by a particular session. However, this method incorrectly returned a producer for each queue that a message was sent to. For example, if an anonymous producer sent a message to 1000 queues, this method returned 1000 producers. In AMQ Broker 7.11, the listProducersInfoAsJSON method now returns accurately the same data as the listProducers method, but in a different format. In AMQ Broker 7.11, the following new metric data is returned: Consumers messagesInTransit - The number of messages for delivery which have not yet been acknowledged messagesInTransitSize - The total size of messages for delivery which have not yet been acknowledged messagesDelivered - The number of messages delivered messagesDeliveredSize - The total size of messages delivered messagesAcknowledged - The total number of messages acknowledged messagesAcknowledgedAwaitingCommit - The total number of messages in a transaction that are acknowledged but awaiting a commit lastDeliveredTime - The time in milliseconds of the last message delivered lastAcknowledgedTime - The time in milliseconds of the last message acknowledged Producers msgSent - The number of messages sent by a producer msgSizeSent - The total size of messages sent by a producer lastProducedMessageID - The ID of the last message sent

Commands:
apiVersion: apps/v1 kind: Deployment template spec: containers: - args: - --leader-elect - --lease-duration=60 - --renew-deadline=40 - --retry-period=5
apiVersion: operators.coreos.com/v1alpha1 kind: Subscription spec: config: env: - name: ARGS value: "--leader-elect --lease-duration=60 --renew-deadline=60 --retry-period=5"
ConnectionFactory connectionFactory = new ActiveMQConnectionFactory("(tcp://host1:port,tcp://host2:port,tcp://host3:port,tcp://host4:port,tcp://host5:port)?ha=true&failoverAttempts=2&reconnectAttempts=2");
tcp://<host>:<port>?consumerWindowSize=0
spec: brokerProperties: - "addressSettings.#.redeliveryMultiplier=2.1" - "addressSettings.#.redeliveryCollisionAvoidanceFactor=1.2"