Goals

Understanding the concepts of AMQ Online.

Learning how to use AMQ Online.

1. AMQ Online Components

AMQ Online is a solution (Operator) to manage multiple components to provide the overall functionality of running self-service (Messaging as a Service) messaging platform on OpenShift.

AMQ Broker:

AMQ Broker is a full-featured, message-oriented middleware broker. It offers advanced addressing and queueing, fast message persistence, and high availability. AMQ Broker supports multiple protocols and operating environments, enabling you to use your existing assets.



This is where all your brokers hosted, and it is responsible for persisting messages.

AMQ Interconnect:

AMQ Interconnect provides flexible routing of messages between AMQP-enabled endpoints, including clients, brokers, and standalone services. With a single connection into a network of AMQ Interconnect routers, a client can exchange messages with any other endpoint connected to the network.



This is where all your routes are hosted (this will come later when explaining address).

Tip For more information regarding different AMQ separate products, please refer to: https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html/introducing_red_hat_amq_7/components#broker

Keycloak:

Open Source Identity and Access Management, which is used to host access control information for queues, topic, etc.

2. Understanding AMQ Online Custom Types

The installed AMQ Online defines new types (CRDs), which will be briefly explained.

2.1. AuthenticationService

AuthenticationService describes an authentication service instance used to authenticate massaging clients. This is simply your way to configure the Keycloak server itself.

2.2. AddressSpacePlan

Address SpacePlan describes the messaging resources available for address spaces (which will be explained later) using this plan (as an aggregate of AddressPlan), such as the available address plans and the amount of router and broker resources that can be used. Think of it as the main quota control. It knows how much hardware can be used by referring to infrastructure configuration. [IMPORTANT] It defines the infrastructure to be deployed, and as its name depicts "plan," it defines quota restrictions (in other words,, the maximum number of addresses).

2.3. AddressPlan

The Address Plan describes the messaging resources consumed by a particular address using this plan, such as what fraction of routers and brokers an address will use and other properties that should be set for multiple addresses.

2.4. Infrastructure Configuration

As the name suggests, it configures the hardware resource allocated to the components, such as CPU, memory, storage of console, broker, router, and some other specific config, too, of mainly two types:

2.4.1. StandardInfraConfig

This allow hosting the AMQ Brokers and AMQ Interconnect routes.

2.4.2. BrokeredInfraConfig

This allows hosting AMQ Brokers only.

2.4.3. Address Space

This is a group of addresses accessible through single connection.

2.4.4. Address

Defines semantics of address and has a set of properties:

Available address types determined by the address space type

Available plans determined by the address type

Address Space — Refers back to AddressSpacePlan, which creates the AMQ Broker Pod and the AMQ Interconnect Pod based on the type (standard or brokered), and like them with Keycloak (AuthenticationService) as an authentication/authorization source and does the needed configuration.

Address — The destinations that use the spinned pods from AddressSpace to configure broker or routers.

Message User — Defines the authentication/authorization attributes (meaning which user can do what) for a specific destination (such as a queue or topic). It mainly writes the rules to Keycloak.

Important A single router and broker pod has a maximum usage of one. If a new address requires additional resources, and the resource consumption is within the address space plan limits, a new pod will be created automatically to handle the increased load.

A single router can support five instances of addresses (0.2), and a broker can support three instances of addresses (0.3) with this plan. If the number of addresses with this plan increases to four, another broker is created. If it increases further to six, another router is created as well.

In the standard address space, address plans for the queue address type may contain a field partition, which allows a queue to be shared across multiple brokers for HA and improved performance. Specifying an amount of broker resource above one will automatically cause a queue to be partitioned.

3. Understanding AMQ Online from Roles and Responsibilities Points of View

There are two main roles in AMQ Online:

3.1. Admins

Admin does the installation of the platform foundation on OpenShift. The admin installs all the basic elements that control the necessary brokers, routers, user console, monitoring tools and also takes care of setting up the authentication and authorization of who has access to the platform. We don’t always have unlimited computing resources for all users. Admin also has control over the resource limitation and creates different plans that can apply to accompany different users’ needs.

3.2. Developers / Application Owners / Tenants

Developers are the users of the platform, they will be creating "Address Space," and they will creating destinations by applying the plans on top of it. After the queue and topics are created, the tenants can create credentials maps (MessagingUser) to different access roles. They can also decide which account has access to the admin console and which account has consume/produce rights to any addresses (queues/ topics) in the Address Space. Please note:, Tenants will have no visibility to the queue or topics of other Address Space, unless specially specified. Once the address are created and config correctly, application will be able to use the credential to read/write to the messaging address.

So a typical workflow will be:

Admins install AMQ Online from Operator Hub or install it manually. Admins will create needed objects in amq-online namespace Define AuthenticationService(s) Define StandardInfraConfig(s) Or BrokeredInfraConfig(s) Define AddressSpacePlan Define AddressPlan Each Tenant will create needed objects in his own namespace. Define AddressSpace Define Address Define MessageUser

Important Each application owner will create separate Address and AddressSpce in the namespace using what Administrators created as infra objects.

4. Understanding the Difference between Standard and Brokered InfraConfig

Table 1. Supported Features Reference Table

Feature Brokered address space Standard address space Address type Queue Yes Yes Topic Yes Yes Multicast No Yes Anycast No Yes Subscription No Yes Messaging protocol AMQP Yes Yes MQTT Yes Technology preview only CORE Yes No OpenWire Yes No STOMP Yes No Transports TCP Yes Yes WebSocket Yes Yes Durable subscriptions JMS durable subscriptions Yes No "Named" durable subscriptions No Yes JMS Transaction support Yes No Selectors on queues Yes No Message ordering guarantees (including prioritization) Yes No Scalability Scalable distributed queues and topics No Yes

Installing AMQ Online on OpenShift 4.x server

There are two ways for installing AMQ online.

Using the source files for RedHat portal. Using the AMQ online operator from OperatorHub.

For ease of use i created a oc cli script which effectively use OperatorHub for installation install-amq-online.sh.

JMS clients and libraries

There are multiple JMS Clients depending on the underlying Messaging Protocol (as shown in above table) each one has a set features and may also have some limitations.

Messaging Protocol

AMQP: AMQP JMS client provides full AMQP 1.0 support and works with any AMQ server.

AMQ AMQP JMS is a Java Message Service (JMS) 2.0 client for use in messaging applications that send and receive AMQP messages.

Key features

JMS 1.1 and 2.0 compatible SSL/TLS for secure communication Flexible SASL authentication Automatic reconnect and failover Distributed tracing based on the OpenTracing standard Ready for use with OSGi containers Pure-Java implementation

Procedure

Add the Red Hat repository to your Maven settings or POM file. For example configuration files, see Section B.1, “Using the online repository”.

<repository>

<id>red-hat-ga</id>

<url>https://maven.repository.redhat.com/ga</url>

</repository>

Add the client dependency to your POM file.



<dependency>

<groupId>org.apache.qpid</groupId>

<artifactId>qpid-jms-client</artifactId>

<version>0.45.0.redhat-00002</version>

</dependency>

The client library is now available in your Maven project.



Important



Important Note on AMQ JMS client for AMQP

AMQ JMS does not currently support distributed transactions (XA). If your application requires distributed transactions, it is recommended that you use the AMQ Core Protocol JMS client.

for more info refer to https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_the_amq_jms_client/index









OPENWIRE: OPENWIRE JMS CLIENT

AMQ OpenWire JMS is a Java Message Service (JMS) 1.1 client for use in messaging applications that send and receive OpenWire messages. To support existing applications based on A-MQ 6

Key features

JMS 1.1 compatible SSL/TLS for secure communication Automatic reconnect and failover Distributed transactions (XA) Pure-Java implementation

Procedure

Add the Red Hat repository to your Maven settings or POM file. For example configuration files, see Section B.1, “Using the online repository”.





<repository>

<id>red-hat-ga</id>

<url>https://maven.repository.redhat.com/ga</url>

</repository>

Add the library dependency to your POM file.





<dependency>

<groupId>org.apache.activemq</groupId>

<artifactId>activemq-client</artifactId>

<version>5.11.0.redhat-630329</version>

</dependency>



The client is now available in your Maven project.

for more info refer to https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_the_amq_openwire_jms_client/index

CORE: AMQ Core Protocol JMS is a Java Message Service (JMS) 2.0 client for use in messaging applications that send and receive Artemis Core Protocol messages. Artemis core is a messaging system with its own API.

Key features

JMS 1.1 and 2.0 compatible SSL/TLS for secure communication Automatic reconnect and failover Distributed transactions (XA) Pure-Java implementation

Procedure

Add the Red Hat repository to your Maven settings or POM file.

<repository>

<id>red-hat-ga</id>

<url>https://maven.repository.redhat.com/ga</url>

</repository>

Add the library dependency to your POM file.

<dependency>

<groupId>org.apache.activemq</groupId>

<artifactId>artemis-jms-client</artifactId>

<version>2.9.0.redhat-00002</version>

</dependency>

The client is now available in your Maven project.

for more info refer to https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_the_amq_core_protocol_jms_client/index