Chapter 4. Configuring Operator-based broker deployments

1. The Operator runs the Init Container before the broker application container. The Init Container generates a default address settings configuration. The default address settings configuration is shown below.

   <address-settings>
       <!--
       if you define auto-create on certain queues, management has to be auto-create
       -->
       <address-setting match="activemq.management#">
           <dead-letter-address>DLQ</dead-letter-address>
           <expiry-address>ExpiryQueue</expiry-address>
           <redelivery-delay>0</redelivery-delay>
           <!--
           with -1 only the global-max-size is in use for limiting
           -->
           <max-size-bytes>-1</max-size-bytes>
           <message-counter-history-day-limit>10</message-counter-history-day-limit>
           <address-full-policy>PAGE</address-full-policy>
           <auto-create-queues>true</auto-create-queues>
           <auto-create-addresses>true</auto-create-addresses>
           <auto-create-jms-queues>true</auto-create-jms-queues>
           <auto-create-jms-topics>true</auto-create-jms-topics>
       </address-setting>
   
       <!-- default for catch all -->
       <address-setting match="#">
           <dead-letter-address>DLQ</dead-letter-address>
           <expiry-address>ExpiryQueue</expiry-address>
           <redelivery-delay>0</redelivery-delay>
           <!--
           with -1 only the global-max-size is in use for limiting
           -->
           <max-size-bytes>-1</max-size-bytes>
           <message-counter-history-day-limit>10</message-counter-history-day-limit>
           <address-full-policy>PAGE</address-full-policy>
           <auto-create-queues>true</auto-create-queues>
           <auto-create-addresses>true</auto-create-addresses>
           <auto-create-jms-queues>true</auto-create-jms-queues>
           <auto-create-jms-topics>true</auto-create-jms-topics>
       </address-setting>
   <address-settings>

   Copy to Clipboard Toggle word wrap
2. If you have also specified an address settings configuration in your Custom Resource (CR) instance, the Init Container processes that configuration and converts it to XML.
3. Based on the value of the applyRule property in the CR, the Init Container merges or replaces the default address settings configuration shown above with the configuration that you have specified in the CR. The result of this merge or replacement is the final address settings configuration that the broker will use.
4. When the Init Container has finished generating the broker configuration (including address settings), the broker application container starts. When starting, the broker container copies its configuration from the installation directory previously used by the Init Container. You can inspect the address settings configuration in the broker.xml configuration file. For a running broker, this file is located in the /home/jboss/amq-broker/etc directory.

Procedure

1. Edit the ActiveMQArtemis CR instance for your broker deployment.

2. In the spec section of the CR, add a brokerProperties attribute if it is not already in the CR.

   spec:
     ...
     brokerProperties:
     ...

   Copy to Clipboard Toggle word wrap

3. Configure an address in the format:

   - addressConfigurations.<address name>.routingTypes=<routing type>

   For example:

   spec:
     ...
     brokerProperties:
     - addressConfigurations.usa-news-address.routingTypes=MULTICAST
     ...

   Copy to Clipboard Toggle word wrap

4. Configure a queue for the address you created in the format:

   - addressConfigurations.<address name>.queueConfigs.<queue name>.address<address>

   Important

   The value of <address> for the .address setting must match the <address name> for each queue you create. If these values are different, separate addresses are created for each. In the following example, both the address name and the .address setting have the same value of usa-news-address.

   spec:
     ...
     brokerProperties:
     - addressConfigurations.usa-news-address.queueConfigs.usa-news-queue.address=usa-news-address
     ...

   Copy to Clipboard Toggle word wrap

5. Add a separate line for each setting you want to configure for a queue in the format:

   • addressConfigurations.<address name>.queueConfigs.<queue name>.<queue setting>

   For example:

   spec:
     ...
     brokerProperties:
     - addressConfigurations.usa-news-address.queueConfigs.usa-news-queue.routingType=ANYCAST
     - addressConfigurations.usa-news-address.queueConfigs.usa-news-queue.purgeOnNoConsumers=true
     - addressConfigurations.usa-news-address.queueConfigs.usa-news-queue.maxConsumers=20
     ...

   Copy to Clipboard Toggle word wrap
6. Save the CR.
7. Check that no errors were detected in the brokerProperties configuration by reviewing the status section of the ActiveMQArtemis CR. For more information, see Section 2.4, “Configuring items not exposed in a custom resource definition (CRD)”.

Procedure

1. Start configuring a custom resource (CR) instance to define addresses and queues for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to deploy CRs in the project for the broker deployment.

         oc login -u <user> -p <password> --server=<host:port>

         Copy to Clipboard Toggle word wrap
      2. Open the sample CR file called broker_activemqartemisaddress_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.

   2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
      2. Start a new CR instance based on the address CRD. In the left pane, click Administration Custom Resource Definitions.
      3. Click the ActiveMQArtemisAddresss CRD.
      4. Click the Instances tab.

      5. Click Create ActiveMQArtemisAddress.

         Within the console, a YAML editor opens, enabling you to configure a CR instance.

2. In the spec section of the CR, add lines to define an address, queue, and routing type. For example:

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemisAddress
   metadata:
       name: myAddressDeployment0
       namespace: myProject
   spec:
       ...
       addressName: myAddress0
       queueName: myQueue0
       routingType: anycast
       ...

   Copy to Clipboard Toggle word wrap

   The preceding configuration defines an address named myAddress0 with a queue named myQueue0 and an anycast routing type.

   Note

   In the metadata section, you need to include the namespace property and specify a value only if you are using the OpenShift Container Platform web console to create your CR instance. The value that you should specify is the name of the OpenShift project for your broker deployment.

3. Deploy the CR instance.

   1. Using the OpenShift command-line interface:

      1. Save the CR file.

      2. Switch to the project for the broker deployment.

         $ oc project <project_name>

         Copy to Clipboard Toggle word wrap

      3. Create the CR instance.

         $ oc create -f <path/to/address_custom_resource_instance>.yaml

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift web console:

      1. When you finish configuring the CR, click Create.

1. Edit the ActiveMQArtemis CR instance for your broker deployment.

2. Create a dead letter address and queue to receive undelivered messages. For example:

   spec:
     ...
     brokerProperties:
     ...
     - addressConfigurations.usDeadLetter.routingTypes=MULTICAST
     - addressConfigurations.usDeadLetter.queueConfigs.usDeadLetter-queue.address=usDeadLetter

   Copy to Clipboard Toggle word wrap

   For more information on creating addresses and queues by using brokerProperties, see, Section 4.2.1, “Configuring addresses and queues”.

3. Add separate lines under the brokerProperties attribute in the format addressSettings.<address name>.<address setting> to:

   • Set the dead letter address for undelivered messages to the dead letter address you created.

   • Specify the number of delivery attempts after which a message that cannot be delivered to a matching address is sent to the dead letter address.

     For example:

     spec:
       ...
       brokerProperties:
       ...
       - addressSettings.usa-news.deadLetterAddress=usDeadLetter
       - addressSettings.usa-news.maxDeliveryAttempts=5
       ...

     Copy to Clipboard Toggle word wrap

     You can use an asterisk (*) or a number sign (#) character as wildcards to create address patterns. Matching of patterns is done at each delimiter boundary, which is represented by a period (.). The number sign character matches any sequence of zero or more words and can be used at the end of the address string. The asterisk character matches a single word and can be used anywhere within the address string. For example:

     spec:
       ...
       brokerProperties:
       ...
       - addressSettings."usa-news.*".deadLetterAddress=usDeadLetter
       - addressSettings."europe-news.#".deadLetterAddress=euDeadLetter
       ...

     Copy to Clipboard Toggle word wrap

     In the preceding example, the following addresses are matched:

   • The usa-news.* address pattern matches any word that follows the usa-news. string, such as usa-news.domestic and usa-news.intl, but not usa-news.domestic.politics.

   • The europe-news.# address pattern matches any address that starts with europe-news, such as europe-news, europe-news.politics and europe-news.politics.fr.

     Note

     In brokerProperties entries, a period (.) is a reserved character. If you want to create an address pattern that contains a period, you must enclose the address in quotation marks. For example, "usa-news.*"

4. Save the CR.
5. Check that no errors were detected in the brokerProperties configuration by reviewing the status section of the ActiveMQArtemis CR. For more information, see Section 2.4, “Configuring items not exposed in a custom resource definition (CRD)”.

Procedure

1. Edit the ActiveMQArtemis CR instance for your broker deployment.

    oc edit ActiveMQArtemis <CR instance name> -n <namespace>

   Copy to Clipboard Toggle word wrap
   1. Using the OpenShift Container Platform web console:
2. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
3. In the left pane, click Operators Installed Operator.
4. Click the Red Hat Integration - AMQ Broker for RHEL 8 (Multiarch) operator.
5. Click the AMQ Broker tab.
6. Click the name of the ActiveMQArtemis instance name.

7. Click the YAML tab.

   Within the console, a YAML editor opens, enabling you to edit the CR instance.

   Note

   In the metadata section, you need to include the namespace property and specify a value only if you are using the OpenShift Container Platform web console to create your CR instance. The value that you should specify is the name of the OpenShift project for your broker deployment.

   1. In the spec section of the CR, add a new addressSettings section that contains a single addressSetting section, as shown below.

      spec:
        ...
        addressSettings:
          addressSetting:

      Copy to Clipboard Toggle word wrap

   2. Add a single instance of the match property to the addressSetting block. Specify an address-matching expression. For example:

      spec:
        ...
        addressSettings:
          addressSetting:
          - match: myAddress

      Copy to Clipboard Toggle word wrap

      match

      Specifies the address, or set of addresses to which the broker applies the configuration that follows. In this example, the value of the match property corresponds to a single address called myAddress.

   3. Add properties related to undelivered messages and specify values. For example:

      spec:
        ...
        addressSettings:
          addressSetting:
          - match: myAddress
            deadLetterAddress: myDeadLetterAddress
            maxDeliveryAttempts: 5

      Copy to Clipboard Toggle word wrap

      deadLetterAddress

      Address to which the broker sends undelivered messages.

      maxDeliveryAttempts

      Maximum number of delivery attempts that a broker makes before moving a message to the configured dead letter address.

      In the preceding example, if the broker makes five unsuccessful attempts to deliver a message to an address that begins with myAddress, the broker moves the message to the specified dead letter address, myDeadLetterAddress.

   4. (Optional) Apply similar configuration to another address or set of addresses. For example:

      spec:
        ...
        addressSettings:
          addressSetting:
          - match: myAddress
            deadLetterAddress: myDeadLetterAddress
            maxDeliveryAttempts: 5
          - match: 'myOtherAddresses#'
            deadLetterAddress: myDeadLetterAddress
            maxDeliveryAttempts: 3

      Copy to Clipboard Toggle word wrap

      In this example, the value of the second match property includes a hash wildcard character. The wildcard character means that the preceding configuration is applied to any address that begins with the string myOtherAddresses.

      Note

      If you use a wildcard expression as a value for the match property, you must enclose the value in single quotation marks, for example, 'myOtherAddresses#'.

   5. At the beginning of the addressSettings section, add the applyRule property and specify a value. For example:

      spec:
        ...
          applyRule: merge_all
          addressSetting:
          - match: myAddress
            deadLetterAddress: myDeadLetterAddress
            maxDeliveryAttempts: 5
          - match: 'myOtherAddresses#'
            deadLetterAddress: myDeadLetterAddress
            maxDeliveryAttempts: 3

      Copy to Clipboard Toggle word wrap

      The applyRule property specifies how the Operator applies the configuration that you add to the CR for each matching address or set of addresses. The values that you can specify are:

      merge_all

      • For address settings specified in both the CR and the default configuration that match the same address or set of addresses:

        • Replace any property values specified in the default configuration with those specified in the CR.
        • Keep any property values that are specified uniquely in the CR or the default configuration. Include each of these in the final, merged configuration.
      • For address settings specified in either the CR or the default configuration that uniquely match a particular address or set of addresses, include these in the final, merged configuration.

      merge_replace

      • For address settings specified in both the CR and the default configuration that match the same address or set of addresses, include the settings specified in the CR in the final, merged configuration. Do not include any properties specified in the default configuration, even if these are not specified in the CR.
      • For address settings specified in either the CR or the default configuration that uniquely match a particular address or set of addresses, include these in the final, merged configuration.

      replace_all

      Replace all address settings specified in the default configuration with those specified in the CR. The final, merged configuration corresponds exactly to that specified in the CR.

      Note

      If you do not explicitly include the applyRule property in your CR, the Operator uses a default value of merge_all.

   6. Save the CR instance.

Procedure

1. Edit the ActiveMQArtemis CR instance for your broker deployment.

2. Add the following brokerProperties entries to allow the broker to delete any address, which is represented by the number sign (#), and associated queues that it no longer finds in the CR.

   spec:
     ...
     brokerProperties:
     - addressSettings.#.configDeleteAddresses=FORCE
     - addressSettings.#.configDeleteQueues=FORCE
     ...

   Copy to Clipboard Toggle word wrap

3. Under the brokerProperties attribute, delete all the lines that reference an address and queue that you want to remove. For example, delete all the lines that reference the usa-news address to remove this address and queue:

   spec:
     ...
     brokerProperties:
     - addressConfigurations.usa-news.queueConfigs.usa-news-queue.routingType=MULTICAST
     - addressConfigurations.usa-news.queueConfigs.usa-news-queue.purgeOnNoConsumers=true
     - addressConfigurations.usa-news.queueConfigs.usa-news-queue.maxConsumers=20
     ...

   Copy to Clipboard Toggle word wrap

4. Save the CR.

   When the broker applies the updated configuration, it deletes addresses and queues that you removed from the CR.

Procedure

1. Ensure that you have an address CR file with the details, for example, the name, addressName and queueName, of the address and queue you want to delete. For example:

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemisAddress
   metadata:
       name: myAddressDeployment0
       namespace: myProject
   spec:
       ...
       addressName: myAddress0
       queueName: myQueue0
       routingType: anycast
       ...

   Copy to Clipboard Toggle word wrap

2. In the spec section of the address CR, add the removeFromBrokerOnDelete attribute and set it to a value of true.

   ..
   spec:
      addressName: myAddress1
      queueName: myQueue1
      routingType: anycast
      removeFromBrokerOnDelete: true

   Copy to Clipboard Toggle word wrap

   Setting the removeFromBrokerOnDelete attribute to true causes the Operator to remove the address and any associated message for all brokers in the deployment when you delete the address CR.

3. Apply the updated address CR to set the removeFromBrokerOnDelete attribute for the address you want to delete.

   $ oc apply -f <path/to/address_custom_resource_instance>.yaml

   Copy to Clipboard Toggle word wrap

4. Delete the address CR to delete the address from the brokers in the deployment.

   $ oc delete -f <path/to/address_custom_resource_instance>.yaml

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a text file with your new JAAS login modules configuration and save the file as login.config. By saving the file as login.config, the correct key is inserted in the secret that you create from the text file. The following is an example login module configuration:

   activemq {
      org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
         reload=true
         org.apache.activemq.jaas.properties.user="new-users.properties"
         org.apache.activemq.jaas.properties.role="new-roles.properties";
   
      org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
         reload=false
         org.apache.activemq.jaas.properties.user="artemis-users.properties"
         org.apache.activemq.jaas.properties.role="artemis-roles.properties"
         baseDir="/home/jboss/amq-broker/etc";
   };

   Copy to Clipboard Toggle word wrap

   After you configure JAAS login modules in a secret and add a reference to the secret in the CR, the default login module is no longer used by AMQ Broker. However, a user in the artemis-users.properties file, which is referenced in the default login module, is required by the Operator to authenticate with the broker. To ensure that the Operator can authenticate with the broker after you configure a new JAAS login module, you must either:

   • Include the default properties login module in the new login module configuration, as shown in the example above. In the example, the default properties login module uses the artemis-users.properties and artemis-roles.properties files. If you include the default login module in the new login module configuration, you must set the baseDir to the /home/jboss/amq-broker/etc directory, which contains the default properties files on each broker Pod.

   • Add the user and role information required by the Operator to authenticate with the broker to a properties file referenced in the new login module configuration. You can copy this information from the default artemis-users.properties and artemis-roles.properties files, which are in the /home/jboss/amq-broker/etc directory on a broker Pod.

     Note

     The properties files referenced in a login module are loaded only when the broker calls the login module for the first time. A broker calls the login modules in the order that they are listed in the login.config file until it finds the login module to authenticate a user. By placing the login module that contains the credentials used by the Operator at the end of the login.config file, all preceding login modules are called when the broker authenticates the Operator. As a result, any status message which states that property files are not visible on the broker is cleared.

2. If the login.config file you created includes a properties login module, ensure that the users and roles files specified in the module contain user and role information. For example:

   new-users.properties

   ruben=ruben01!
   anne=anne01!
   rick=rick01!
   bob=bob01!

   Copy to Clipboard Toggle word wrap

   new-roles.properties

   admin=ruben, rick
   group1=bob
   group2=anne

   Copy to Clipboard Toggle word wrap

3. Use the oc create secret command to create a secret from the text file that you created with the new login module configuration. If the login module configuration includes a properties login module, also include the associated users and roles files in the secret. For example:

   oc create secret generic custom-jaas-config --from-file=login.config --from-file=new-users.properties --from-file=new-roles.properties

   Copy to Clipboard Toggle word wrap
   Note

   The secret name must have a suffix of -jaas-config so the Operator can recognize that the secret contains login module configuration and propagate any updates to each broker Pod.

   For more information about how to create secrets, see Secrets in the Kubernetes documentation.

4. Add the secret you created to the Custom Resource (CR) instance for your broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to deploy CRs in the project for the broker deployment.

      2. Edit the CR for your deployment.

          oc edit ActiveMQArtemis <CR instance name> -n <namespace>

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to deploy CRs in the project for the broker deployment.
      2. In the left pane, click Operators Installed Operator.
      3. Click the Red Hat Integration - AMQ Broker for RHEL 8 (Multiarch) operator.
      4. Click the AMQ Broker tab.
      5. Click the name of the ActiveMQArtemis instance name.

      6. Click the YAML tab.

         Within the console, a YAML editor opens, enabling you to configure a CR instance.

5. Create an extraMounts element and a secrets element and add the name of the secret. The following example adds a secret named custom-jaas-config to the CR.

   deploymentPlan:
     ...
     extraMounts:
       secrets:
       - "custom-jaas-config"
     ...

   Copy to Clipboard Toggle word wrap

6. In the CR, grant permissions to the roles that are configured on the broker.

   1. In the spec section of the CR, add a brokerProperties element and add the permissions. You can grant a role permissions to a single address. Or, you can specify a wildcard match using the # sign to grant a role permissions to all addresses. For example:

      spec:
        ...
        brokerProperties:
        - securityRoles.#.group2.send=true
        - securityRoles.#.group1.consume=true
        - securityRoles.#.group1.createAddress=true
        - securityRoles.#.group1.createNonDurableQueue=true
        - securityRoles.#.group1.browse=true
        ...

      Copy to Clipboard Toggle word wrap

      In the example, the group2 role is assigned send permissions to all addresses and the group1 role is assigned consume, createAddress, createNonDurableQueue and browse permissions to all addresses.

      Note

      In a Java properties file, a colon (:) is a reserved character that is used to separate a key and a value in a key/value pair. If you want to grant permissions to a fully qualified queue name (FQQN), which consists of an address name and a queue name separated by colons (::), you must use the backslash (\) character to escape the colon characters in the FQQN. For example:

      spec:
        ...
        brokerProperties:
        - 'securityRoles."my-address\:\:my-queue".group2.send=true'

      Copy to Clipboard Toggle word wrap

7. Save the CR.

   The Operator mounts the login.config file in the secret in a /amq/extra/secrets/secret name directory on each Pod and configures the broker JVM to read the mounted login.config file instead of the default login.config file. If the login.config file contains a properties login module, the referenced users and roles properties file are also mounted on each Pod.

8. View the status information in the CR to verify that the brokers in your deployment are using the JAAS login modules in the secret for authentication.

   1. Using the OpenShift command-line interface:

      1. Get the status conditions in the CR for your brokers.

         $ oc get activemqartemis -o yaml

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift web console:

      1. In the CR, navigate to the status section.

   3. In the status information, verify that a JaasPropertiesApplied type is present, which indicates that the broker is using the JAAS login modules configured in the secret. For example:

      - lastTransitionTime: "2023-02-06T20:50:01Z"
        message: ""
        reason: Applied
        status: "True"
        type: JaasPropertiesApplied

      Copy to Clipboard Toggle word wrap

      When you update any of the files in the secret, the value of the reason field shows OutofSync until OpenShift Container Platform propagates the latest files in the secret to each broker Pod. For example, if you add a new user to the new-users-properties file and update the secret, you see the following status information until the updated file is propagated to each Pod:

      - lastTransitionTime: "2023-02-06T20:55:20Z"
        message: 'new-users.properties status out of sync, expected: 287641156, current: 2177044732'
        reason: OutOfSync
        status: "False"
        type: JaasPropertiesApplied

      Copy to Clipboard Toggle word wrap

9. When you update user or role information in a properties file that is referenced in the secret, use the oc set data command to update the secret. You must readd all the files to the secret again, including the login.config file. For example, if you add a new user to the new-users.properties file that you created earlier in this procedure, use the following command to update the custom-jaas-config secret:

   oc set data secret/custom-jaas-config --from-file=login.config=login.config --from-file=new-users.properties=new-users.properties --from-file=new-roles.properties=new-roles.properties

   Copy to Clipboard Toggle word wrap

Procedure

1. Use the oc create secret command to create a secret that contains the third-party JAR file that you want to add. For example:

   oc create secret generic log4j-template --from-file=log4j-layout-template-json-2.22.1.jar

   Copy to Clipboard Toggle word wrap

   For more information about how to create secrets, see Secrets in the Kubernetes documentation.

2. Edit the CR for your broker deployment and configure the Operator to mount the secret that contains the third-party JAR file on each broker pod. For example, the following configuration mounts a secret named log4j-template.

   deploymentPlan:
     ...
     extraMounts:
       secrets:
       - "log4j-template"
     ...

   Copy to Clipboard Toggle word wrap

   The JAR file is mounted in a /amq/extra/secrets/secret name directory on each broker pod. For example, /amq/extra/secrets/postgresql-driver/log4j-template.jar.

3. Create an ARTEMIS_EXTRA_LIBS environment variable to extend the broker’s Java classpath so the broker loads the JAR file from the mounted directory on each pod. For example:

   spec:
     ...
     env:
     - name: ARTEMIS_EXTRA_LIBS
       value: /amq/extra/secrets/log4j-template

   Copy to Clipboard Toggle word wrap
4. Save the CR.

Procedure

1. Edit the ActiveMQArtemis CR for your broker deployment.

2. In the broker CR, use the extraVolumes and extraVolumeMounts attributes to add a persistent volume and mount the volume on each broker pod. For example:

   deploymentPlan:
     ...
     extraVolumes:
     - name: extra-volume
       persistentVolumeClaim:
         claimName: extra-jars
     extraVolumeMounts:
     - name: extra-volume
       mountPath: /opt/extra-lib
     ...

   Copy to Clipboard Toggle word wrap

3. Use the resourceTemplates attribute to customize the StatefulSet resource for the deployment. In the customization, use an init container to mount the extra-volume volume that you created on each pod and to download the JAR file to the volume. For example:

   spec:
     ...
     resourceTemplates:
     - selector:
         kind: StatefulSet
       patch:
         kind: StatefulSet
         spec:
           template:
             spec:
               initContainers:
               - name: mysql-jdbc-driver-init
                 volumeMounts:
                 - mountPath: /opt/extra-lib
                   name: extra-volume
                 image: curlimages/curl:8.6.0
                 command:
                 - /bin/sh
                 args:
                 - -c
                 - "if ! [ -f /opt/extra-lib/mysql-connector.jar ]; then curl https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.23/mysql-connector-java-8.0.23.jar --output /opt/extra-lib/mysql-connector.jar ; fi"

   Copy to Clipboard Toggle word wrap

   In the example, a curl image is used to download a mysql-connector.jar file to the mounted path of the volume, /opt/extra-lib, if the file is not already on the volume.

4. Create an ARTEMIS_EXTRA_LIBS environment variable to extend the broker’s Java classpath so the broker loads the JAR file from the shared volume. For example:

   spec:
     ...
     env:
     - name: ARTEMIS_EXTRA_LIBS
       value: /opt/extra-lib

   Copy to Clipboard Toggle word wrap
5. Save the CR.

Procedure

1. Edit the ActiveMQArtemis custom resource (CR) for your broker deployment.

2. Set the persistenceEnabled attribute to true. For example:

   spec:
     ...
     deploymentPlan:
       persistenceEnabled: true
     ...

   Copy to Clipboard Toggle word wrap
3. Save the CR.

Procedure

1. Edit the ActiveMQArtemis custom resource (CR) for your broker deployment.

2. Enable JDBC database persistence by using the brokerProperties attribute. For example:

   spec:
     ...
     brokerProperties:
     - storeConfiguration=DATABASE
     - storeConfiguration.jdbcDriverClassName=<class name>
     - storeConfiguration.jdbcConnectionUrl=jdbc:<URL>
     - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     ...

   Copy to Clipboard Toggle word wrap

   storeConfiguration

   Specify a value of DATABASE to persist messages to a JDBC database.

   storeConfiguration.jdbcDriverClassName

   Fully-qualified class name of the JDBC database driver. For example, org.postgresql.Driver.

   For information about supported databases, see Red Hat AMQ 7 Supported Configurations on the Red Hat Customer Portal.

   storeConfiguration.jdbcConnectionUrl

   Full JDBC connection URL for your database server including the database name and all configuration parameters. For example:

   jdbc:postgresql://postgresql-service.default.svc.cluster.local:5432/postgres?user=postgres&password=postgres

   In the example, the database name is postgres.

   HAPolicyConfiguration

   Set to SHARED_STORE_PRIMARY to ensure that the broker uses a JDBC lease lock to protect the database tables from concurrent access by multiple brokers. If a second broker instance is deployed unintentionally, the lease lock prevents the second broker from writing to the database.

3. (Optional) Change the default values for the following attributes, if required:

   storeConfiguration.jdbcNetworkTimeout

   JDBC network connection timeout, in milliseconds. The default value is 20000 milliseconds.

   storeConfiguration.jdbcLockRenewPeriod

   Length, in milliseconds, of the renewal period for the current JDBC lock. When this time elapses, the broker can renew the lock. Set a value that is several times smaller than the value of storeConfiguration.jdbcLockExpiration to give the broker sufficient time to extend the lease and also gives the broker time to try to renew the lock in the event of a connection problem. The default value is 2000 milliseconds.

   storeConfiguration.jdbcLockExpiration

   Time, in milliseconds, that the current JDBC lock is considered owned (that is, acquired or renewed), even if the value of storeConfiguration.jdbcLockRenewPeriod has elapsed. The broker periodically tries to renew a lock that it owns according to the value of storeConfiguration.jdbcLockRenewPeriod. If the broker fails to renew the lock, for example, due to a connection problem, the broker keeps trying to renew the lock until the value of storeConfiguration.jdbcLockExpiration has passed since the lock was last successfully acquired or renewed. An exception to the renewal behavior described above is when another broker acquires the lock. This can happen if there is a time misalignment between the Database Management System (DBMS) and the brokers, or if there is a long pause for garbage collection. In this case, the broker that originally owned the lock considers the lock lost and does not try to renew it. If the JDBC lock has not been renewed by the broker that currently owns it after the expiration time elapses, another broker can establish a JDBC lock. The default value of is 20000 milliseconds.

   storeConfiguration.jdbcJournalSyncPeriod

   Duration, in milliseconds, for which the broker journal synchronizes with JDBC. The default value is 5 milliseconds.

   storeConfiguration.jdbcMaxPageSizeBytes

   Maximum size, in bytes, of each page file when AMQ Broker persists messages to a JDBC database. The default value is 102400, which is 100KB. The value that you specify also supports byte notation such as "K" "MB", and "GB".

4. Save the CR.

Procedure

1. Start configuring a Custom Resource (CR) instance for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to deploy CRs in the project in which you are creating the deployment.

         oc login -u <user> -p <password> --server=<host:port>

         Copy to Clipboard Toggle word wrap
      2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.

   2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to deploy CRs in the project in which you are creating the deployment.
      2. Start a new CR instance based on the main broker CRD. In the left pane, click Administration Custom Resource Definitions.
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.

      5. Click Create ActiveMQArtemis.

         Within the console, a YAML editor opens, enabling you to configure a CR instance.

   For a basic broker deployment, a configuration might resemble that shown below.

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
   spec:
     deploymentPlan:
       size: 1
       image: placeholder
       requireLogin: false
       persistenceEnabled: true
       journalType: nio
       messageMigration: true

   Copy to Clipboard Toggle word wrap

   Observe that in the broker_activemqartemis_cr.yaml sample CR file, the image property is set to a default value of placeholder. This value indicates that, by default, the image property does not specify a broker container image to use for the deployment. To learn how the Operator determines the appropriate broker container image to use, see Section 2.7, “How the Operator chooses container images”.

2. To specify the broker storage size, in the deploymentPlan section of the CR, add a storage section. Add a size property and specify a value. For example:

   spec:
     deploymentPlan:
       size: 1
       image: placeholder
       requireLogin: false
       persistenceEnabled: true
       journalType: nio
       messageMigration: true
       storage:
         size: 4Gi

   Copy to Clipboard Toggle word wrap

   storage.size

   Size, in bytes, of the Persistent Volume Claim (PVC) that each broker Pod requires for persistent storage. This property applies only when persistenceEnabled is set to true. The value that you specify must include a unit using byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi).

3. To specify the storage class that each broker Pod requires for persistent storage, in the storage section, add a storageClassName property and specify a value. For example:

   spec:
     deploymentPlan:
       size: 1
       image: placeholder
       requireLogin: false
       persistenceEnabled: true
       journalType: nio
       messageMigration: true
       storage:
         size: 4Gi
         storageClassName: gp3

   Copy to Clipboard Toggle word wrap

   storage.storageClassName

   The name of the storage class to request in the Persistent Volume Claim (PVC). Storage classes provide a way for administrators to describe and classify the available storage. For example, different storage classes might map to specific quality-of-service levels, backup policies and so on.

   If you do do not specify a storage class, a persistent volume with the default storage class configured for the cluster is claimed by the PVC.

   Note

   If you specify a storage class, a persistent volume is claimed by the PVC only if the volume’s storage class matches the specified storage class.

4. Deploy the CR instance.

   1. Using the OpenShift command-line interface:

      1. Save the CR file.

      2. Switch to the project in which you are creating the broker deployment.

         $ oc project <project_name>

         Copy to Clipboard Toggle word wrap

      3. Create the CR instance.

         $ oc create -f <path/to/custom_resource_instance>.yaml

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift web console:

      1. When you have finished configuring the CR, click Create.

Procedure

1. Start configuring a Custom Resource (CR) instance for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift as a user that has privileges to deploy CRs in the project in which you are creating the deployment.

         oc login -u <user> -p <password> --server=<host:port>

         Copy to Clipboard Toggle word wrap
      2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.

   2. Using the OpenShift Container Platform web console:

      1. Log in to the console as a user that has privileges to deploy CRs in the project in which you are creating the deployment.
      2. Start a new CR instance based on the main broker CRD. In the left pane, click Administration Custom Resource Definitions.
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.

      5. Click Create ActiveMQArtemis.

         Within the console, a YAML editor opens, enabling you to configure a CR instance.

   For a basic broker deployment, a configuration might resemble that shown below.

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
   spec:
     deploymentPlan:
       size: 1
       image: placeholder
       requireLogin: false
       persistenceEnabled: true
       journalType: nio
       messageMigration: true

   Copy to Clipboard Toggle word wrap

   Observe that in the broker_activemqartemis_cr.yaml sample CR file, the image property is set to a default value of placeholder. This value indicates that, by default, the image property does not specify a broker container image to use for the deployment. To learn how the Operator determines the appropriate broker container image to use, see Section 2.7, “How the Operator chooses container images”.

2. In the deploymentPlan section of the CR, add a resources section. Add limits and requests sub-sections. In each sub-section, add a cpu and memory property and specify values. For example:

   spec:
     deploymentPlan:
       size: 1
       image: placeholder
       requireLogin: false
       persistenceEnabled: true
       journalType: nio
       messageMigration: true
       resources:
         limits:
           cpu: "500m"
           memory: "1024M"
         requests:
           cpu: "250m"
           memory: "512M"

   Copy to Clipboard Toggle word wrap

   limits.cpu

   Each broker container running in a Pod in the deployment cannot exceed this amount of host-node CPU usage.

   limits.memory

   Each broker container running in a Pod in the deployment cannot exceed this amount of host-node memory usage.

   requests.cpu

   Each broker container running in a Pod in the deployment requests this amount of host-node CPU. This value is the minimum amount of CPU required for the broker container to run.

   requests.memory

   Each broker container running in a Pod in the deployment requests this amount of host-node memory. This value is the minimum amount of memory required for the broker container to run.

   Note

   If you specify limits for a resource, but do not specify requests, a broker container requests the configured limits values for that resource. For example, in the following configuration, a broker container requests the configured limits values of 500m cpu and 1024M memory.

   spec:
     deploymentPlan:
       size: 3
       ...
       resources:
         limits:
           cpu: "500m"
           memory: "1024M"

   Copy to Clipboard Toggle word wrap

   Important

   Set limits without setting requests to control the precise amount of memory and CPU requested and to ensure that the same values are requested for each broker container if there are multiple brokers in your deployment.

3. Deploy the CR instance.

   1. Using the OpenShift command-line interface:

      1. Save the CR file.

      2. Switch to the project in which you are creating the broker deployment.

         $ oc project <project_name>

         Copy to Clipboard Toggle word wrap

      3. Create the CR instance.

         $ oc create -f <path/to/custom_resource_instance>.yaml

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift web console:

      1. When you have finished configuring the CR, click Create.

Procedure

1. Edit the ActiveMQArtemis custom resource (CR) for your broker deployment.

2. In the acceptors attribute, add a named acceptor. Add the protocols and port attributes. Set values to specify the messaging protocols to be used by the acceptor and the port on each broker pod to expose for those protocols. For example:

   spec:
     ..
     acceptors:
     - name: my-acceptor
       protocols: amqp
       port: 5672
     ..

   Copy to Clipboard Toggle word wrap

   The configured acceptor exposes port 5672 to AMQP clients. The full set of values that you can specify for the protocols attribute is shown in the table.

   Expand

   Table 4.4. Acceptor protocols

   Protocol	Value
   Core Protocol	core
   AMQP	amqp
   OpenWire	openwire
   MQTT	mqtt
   STOMP	stomp
   All supported protocols	all

   Show more
   Note
   • For each broker pod in your deployment, the Operator also creates a default acceptor that uses port 61616. This default acceptor is required for broker clustering and has Core Protocol enabled.
   • By default, the AMQ Broker management console uses port 8161 on the broker pod. Each broker pod in your deployment has a dedicated Service that provides access to the console. For more information, see Chapter 5, Connecting to AMQ Management Console for an Operator-based broker deployment.

3. To use another protocol on the same acceptor, modify the protocols attribute. Specify a comma-separated list of protocols. For example:

   spec:
    ..
     acceptors:
     - name: my-acceptor
       protocols: amqp,openwire
       port: 5672
   ...

   Copy to Clipboard Toggle word wrap

   The configured acceptor now exposes port 5672 to AMQP and OpenWire clients.

4. To specify the number of concurrent client connections that the acceptor allows, add the connectionsAllowed attribute and set a value. For example:

   spec:
     ...
     acceptors:
     - name: my-acceptor
       protocols: amqp,openwire
       port: 5672
       connectionsAllowed: 5
     ...

   Copy to Clipboard Toggle word wrap

5. By default, an acceptor is exposed only to clients in the same OpenShift cluster as the broker deployment. To also expose the acceptor to clients outside OpenShift, set both the expose attribute and the sslEnabled attribute to true.

   spec:
     ...
     acceptors:
     - name: my-acceptor
       protocols: amqp,openwire
       port: 5672
       connectionsAllowed: 5
       expose: true
       sslEnabled: true
     ...

   Copy to Clipboard Toggle word wrap

   When you enable SSL (that is, Secure Sockets Layer) security on an acceptor (or connector), you can add related configuration, such as:

   • The secret name used to store authentication credentials in your OpenShift cluster. A secret is required when you enable SSL on the acceptor.
   • The Transport Layer Security (TLS) protocols to use for secure network communication. TLS is an updated, more secure version of SSL. You specify the TLS protocols in the enabledProtocols attribute.
   • Whether the acceptor uses mTLS, also known as mutual authentication, between the broker and the client. You specify this by setting the value of the needClientAuth attribute to true.

   For more information about these tasks, see Section 4.12.2, “Securing broker-client connections”.

   When you expose an acceptor to clients outside OpenShift, the Operator automatically creates a dedicated service and Openshift route for the acceptor on each broker pod in the deployment.

6. If you want to customize the host name of the route that is exposed for the acceptor on each pod to match the internal routing configuration on your Openshift cluster, you can do one or both of the following:

   • Use the ingressHost attribute to replace the default host name with a custom host name for a specific acceptor.

   • Use the ingressDomain attribute to append a custom domain to the host name. The custom domain is also applied to all other routes, such as routes for other acceptors and the console, that are exposed by the CR configuration.

     1. To set a custom host name for the acceptor routes, add the ingressHost attribute and specify the host string. For example:

        spec:
          ...
          acceptors:
          - name: my-acceptor
            protocols: amqp,openwire
            port: 5672
            connectionsAllowed: 5
            expose: true
            ingressHost: my-acceptor-production.my-subdomain.com
          ...

        Copy to Clipboard Toggle word wrap
        Note

        The ingressHost value must be unique on your Openshift cluster. If your broker cluster has multiple broker pods, you can make the ingressHost value unique by including the $(BROKER_ORDINAL) variable in the value. The Operator replaces this variable on each broker pod with the ordinal number the StatefulSet assigned to the pod. For example, an ingressHost value of my-acceptor-$(BROKER_ORDINAL)-production.my-subdomain.com sets the host name of the route to my-acceptor-0-production.my-subdomain on the first pod, my-acceptor-1-production.my-subdomain on the second pod and so on.

        You can include any the following variables in the custom host name string for an acceptor route:

        Expand

        Table 4.5. Variables in a custom host name string for an acceptor route

        Name	Description
        $(CR_NAME)	The value of the metadata.name attribute in the CR.
        $(CR_NAMESPACE)	The namespace of the custom resource.
        $(BROKER_ORDINAL)	The ordinal number assigned to the broker pod by the StatefulSet.
        $(ITEM_NAME)	The name of the acceptor.
        $(RES_TYPE)	The resource type. A route has a resource type of rte. An ingress has a resource type of ing.
        $(INGRESS_DOMAIN)	The value of the spec.ingressDomain attribute if it is configured in the CR.

        Show more

     2. To append a custom domain to the host name in routes, add a spec.ingressDomain attribute and specify a custom string. For example:

        spec:
          ...
          ingressDomain: my.domain.com

        Copy to Clipboard Toggle word wrap

7. If your organization’s network policy require that you expose acceptors by using an ingress instead of a route, complete the following steps:

   1. Add the exposeMode attribute and set the value to ingress.

      spec:
        ...
        acceptors:
        - name: my-acceptor
          protocols: amqp,openwire
          port: 5672
          connectionsAllowed: 5
          expose: true
          exposeMode: ingress
        ...

      Copy to Clipboard Toggle word wrap

   2. If you want to customize the host name of the ingresses that are exposed for the acceptor to match the internal routing configuration on your Openshift cluster, you can do one or both of the following:

      • Use the ingressHost attribute to replace the default host name with a custom host name.

      • Use the ingressDomain attribute to append a custom domain to the host name. The custom domain is also applied to all other ingresses, such as ingresses for other acceptors and the console, that are exposed by the CR configuration.

        1. To set a custom host name for the ingresses for the acceptor, add the ingressHost attribute and specify the host string. For example:

           spec:
             ...
             acceptors:
             - name: my-acceptor
               protocols: amqp,openwire
               port: 5672
               connectionsAllowed: 5
               expose: true
               exposeMode: ingress
               ingressHost: my-acceptor-production.my-subdomain.com
             ...

           Copy to Clipboard Toggle word wrap

           You can include the same variables to customize an ingress host as a route host, which are described earlier in this procedure.

        2. To append a custom domain to the host name in ingresses, add a spec.ingressDomain attribute and specify a custom string. For example:

           spec:
             ...
             ingressDomain: my-subdomain.domain.com

           Copy to Clipboard Toggle word wrap

           For acceptors, the default host name of an ingress is in the format of <cr-name>-<acceptor name>-<ordinal>-svc-ing-<namespace>. If, for example, you have a CR named production in the amqbroker name space, an ingressDomain value of mydomain.com gives a host value of production-wconsj-0-svc-ing-mynamespace.amqbroker.com for the ingress created on pod 0.