Chapter 4. Configuring a broker

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>

2. If you 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. 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.

   Note

   You must include the credentials required by the Operator to authenticate with the broker in the login.config file. You can do this by adding the default properties login module, which uses the artemis-users.properties and artemis.roles properties files, as shown in the following examples. Alternatively, you can add the contents of the artemis-users.properties and artemis.roles.properties to other user and roles properties files configured in the login.config file.

   Example login.config files

   The following example has a properties login module that is used to authenticate users and the default properties login module required by the Operator to authenticate with the broker:

   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";
   };

   The following example has an LDAP login module that is used to authenticate users and the default properties login module required by the Operator to authenticate with the broker:

   activemq {
      org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule sufficient
          debug=true
          reload=true
          initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"
          connectionURL="ldap://ldap.company.com:389"
          connectionUsername="cn=read-only-admin,dc=example,dc=com"
          connectionPassword="password"
          connectionProtocol="s"
          connectionTimeout="5000"
          authentication="simple"
          userBase="dc=example,dc=com"
          userSearchMatching="(uid={0})"
          userSearchSubtree=true
          readTimeout="5000"
          roleBase="dc=example,dc=com"
          roleName="cn"
          roleSearchMatching="(uniqueMember={0})"
          roleSearchSubtree=false
          ;
      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"
          ;
   };

   Note

   Place the properties files that contain the credentials used by the Operator to authenticate with the broker at the end of the login.config file. This ensures that the properties files in all login modules are loaded when the broker authenticates the Operator. Otherwise, the custom resource might have a status message showing that some property files are not visible on the broker, until all login modules are used.

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!

   new-roles.properties

   admin=ruben, rick
   group1=bob
   group2=anne

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

   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. 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"
        ...

5. 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
        ...

      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'

6. 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.

7. 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. In the CR, navigate to the status section.

   2. 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

      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

8. 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 add 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

   Note

   The broker JVM reads the configuration in the login.config file only when it starts. If you change the configuration in the login.config file, for example, to add a new login module, and update the secret, the broker does not use the new configuration until the broker is restarted.

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

   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"
     ...

   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

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
     ...

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"

   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

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
     ...

   Note

   When persistenceEnabled is set to true, the Operator creates the required resources to deploy broker pods that have persistent volumes. In addition, the Operator configures the broker to create the journal and other data files on the persistent volume.

3. Save the CR.

Procedure

1. Edit the ActiveMQArtemis 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
     ...

   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. Edit the ActiveMQArtemis (CR) instance for your broker deployment.

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

   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

   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. Save the CR.

Procedure

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

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"

   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"

   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. Save the CR.

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
     ..

   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
   ...

   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
     ...

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
     ...

   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
          ...

        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

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
        ...

   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
             ...

           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

           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.

Procedure

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

2. Add an environment variable to set a Java system property that disables FIPS mode on the broker. For example:

   spec:
     ...
     env:
     - name: JDK_JAVA_OPTIONS
       value: com.redhat.fips=false
     ..

3. Save the ActiveMQArtemis CR.

Procedure

1. Open the Custom Resource (CR) instance in which you previously defined an AMQP acceptor.

   1. Using the OpenShift command-line interface:

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

   2. Using the OpenShift Container Platform web console:

      1. In the left navigation menu, click menu:Administration[Custom Resource Definitions]
      2. Click the ActiveMQArtemis CRD.
      3. Click the Instances tab.
      4. Locate the CR instance that corresponds to your project namespace.

   A previously-configured AMQP acceptor might resemble the following:

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

2. Specify the minimum size, in bytes, of an AMQP message that the broker handles as a large message. For example:

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

   In the preceding example, the broker is configured to accept AMQP messages on port 5672. Based on the value of amqpMinLargeMessageSize, if the acceptor receives an AMQP message with a body larger than or equal to 204800 bytes (that is, 200 kilobytes), the broker stores the message as a large message.

   The broker stores the message in the large messages directory (/opt/<custom_resource_name>/data/large-messages, by default) on the persistent volume (PV) used by the broker for message storage.

   If you do not explicitly specify a value for the amqpMinLargeMessageSize property, the broker uses a default value of 102400 (that is, 100 kilobytes).

   If you set amqpMinLargeMessageSize to a value of -1, large message handling for AMQP messages is disabled.

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift Container Platform 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>

   2. Using the OpenShift Container Platform web console:

      1. Log in to OpenShift Container Platform as a user that has privileges to deploy CRs in the project for the broker deployment.
      2. In the left pane, click menu:Administration[Custom Resource Definitions].
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.
      5. Click the instance for your broker deployment.

      6. Click the YAML tab.

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

2. In the deploymentPlan section of the CR, add a startupProbe section. For example:

   spec:
     deploymentPlan:
       startupProbe:
         exec:
           command:
             - /bin/bash
             - '-c'
             - /opt/amq/bin/artemis
             - 'check'
             - 'node'
             - '--up'
             - '--url'
             - 'tcp://$HOSTNAME:61616'
         initialDelaySeconds: 5
         periodSeconds: 10
         timeoutSeconds: 3
         failureThreshold: 30

   command

   The startup probe command to run within the container. In the example, the startup probe uses the artemis check node command to verify that AMQ Broker has started in the container for a broker Pod.

   initialDelaySeconds

   The delay, in seconds, before the probe runs after the container starts. The default is 0.

   periodSeconds

   The interval, in seconds, at which the probe runs. The default is 10.

   timeoutSeconds

   Time, in seconds, that the startup probe command waits for a reply from the broker. If a response to the command is not received, the command is terminated. The default value is 1.

   failureThreshold

   The minimum consecutive failures, including timeouts, of the startup probe after which the probe is deemed to have failed. When the probe is deemed to have failed, it restarts the Pod. The default value is 3.

   Depending on the resources of the cluster and the size of the broker journal, you might need to increase the failure threshold to allow the broker sufficient time to start and pass the probe check. Otherwise, the broker enters a loop condition whereby the failure threshold is reached repeatedly and the broker is restarted each time by the startup probe. For example, if you set the failureThreshold to 30 and the probe runs at the default interval of 10 seconds, the broker has 300 seconds to start and pass the probe check.

3. Save the CR.

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift Container Platform 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>

   2. Using the OpenShift Container Platform web console:

      1. Log in to OpenShift Container Platform as a user that has privileges to deploy CRs in the project for the broker deployment.
      2. In the left pane, click menu:Administration[Custom Resource Definitions].
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.
      5. Click the instance for your broker deployment.
      6. Click the YAML tab.

2. To configure a liveness probe, in the deploymentPlan section of the CR, add a livenessProbe section. For example:

   spec:
     deploymentPlan:
       livenessProbe:
         initialDelaySeconds: 5
         periodSeconds: 5
         failureThreshold: 30

   initialDelaySeconds

   The delay, in seconds, before the probe runs after the container starts. The default is 5.

   Note

   If the deployment also has a startup probe configured, you can set the delay to 0 for both a liveness and a readiness probe. Both of these probes run only after the startup probe has passed. If the startup probe has already passed, it confirms that the broker has started successfully, so a delay in running the liveness and readiness probes is not required.

   periodSeconds

   The interval, in seconds, at which the probe runs. The default is 5.

   failureThreshold

   The minimum consecutive failures, including timeouts, of the liveness probe that signify the probe has failed. When the probe fails, it restarts the Pod. The default value is 3.

   If your deployment does not have a startup probe configured, which verifies that the broker application is started before the liveness probe runs, you might need to increase the failure threshold to allow the broker sufficient time to start and pass the liveness probe check. Otherwise, the broker can enter a loop condition whereby the failure threshold is reached repeatedly and the broker Pod is restarted each time by the liveness probe.

   The time required by the broker to start and pass a liveness probe check depends on the resources of the cluster and the size of the broker journal. For example, if you set the failureThreshold to 30 and the probe runs at the default interval of 5 seconds, the broker has 150 seconds to start and pass the liveness probe check.

   Note

   If you do not configure a liveness probe or if the handler is missing from a configured probe, the AMQ Broker Operator creates a default TCP probe that has the following configuration. The default TCP probe attempts to open a socket to the broker container on the specified port.

   spec:
     deploymentPlan:
       livenessProbe:
         tcpSocket:
           port: 8181
         initialDelaySeconds: 30
         timeoutSeconds: 5

3. To configure a readiness probe, in the deploymentPlan section of the CR, add a readinessProbe section. For example:

   spec:
     deploymentPlan:
       readinessProbe:
         initialDelaySeconds: 5
         periodSeconds: 5

   If you don’t configure a readiness probe, a built-in script checks if all acceptors can accept connections.

4. If you want to configure more comprehensive health checks, add the artemis check command-line utility to the liveness or readiness probe configuration.

   1. If you want to configure a health check that creates a full client connection to the broker, in the livenessProbe or readinessProbe section, add an exec section. In the exec section, add a command section. In the command section, add the artemis check node command syntax. For example:

      spec:
        deploymentPlan:
          readinessProbe:
            exec:
              command:
                - bash
                - '-c'
                - /home/jboss/amq-broker/bin/artemis
                - check
                - node
                - '--silent'
                - '--acceptor'
                - <acceptor name>
                - '--user'
                - $AMQ_USER
                - '--password'
                - $AMQ_PASSWORD
            initialDelaySeconds: 30
            timeoutSeconds: 5

      By default, the artemis check node command uses the URI of an acceptor called artemis. If the broker has an acceptor called artemis, you can exclude the --acceptor <acceptor name> option from the command.

      Note

      $AMQ_USER and $AMQ_PASSWORD are environment variables that are configured by the AMQ Operator.

   2. If you want to configure a health check that produces and consumes messages, which also validates the health of the broker’s file system, in the livenessProbe or readinessProbe section, add an exec section. In the exec section, add a command section. In the command section, add the artemis check queue command syntax. For example:

      spec:
        deploymentPlan:
          readinessProbe:
            exec:
              command:
                - bash
                - '-c'
                - /home/jboss/amq-broker/bin/artemis
                - check
                - queue
                - '--name'
                - livenessqueue
                - '--produce'
                - "1"
                - '--consume'
                - "1"
                - '--silent'
                - '--user'
                - $AMQ_USER
                - '--password'
                - $AMQ_PASSWORD
            initialDelaySeconds: 30
            timeoutSeconds: 5

      Note

      The queue name that you specify must be configured on the broker and have a routingType of anycast. For example:

      apiVersion: broker.amq.io/v1beta1
      kind: ActiveMQArtemisAddress
      metadata:
        name: livenessqueue
        namespace: activemq-artemis-operator
      spec:
        addressName: livenessqueue
        queueConfiguration:
          purgeOnNoConsumers: false
          maxConsumers: -1
          durable: true
          enabled: true
        queueName: livenessqueue
        routingType: anycast

5. Save the CR.

1. When a broker pod in the deployment shuts down due to an intentional scale down of the deployment, the Operator automatically deploys a scaledown custom resource to prepare for message migration.

2. To check for Persistent Volumes (PVs) that have been orphaned, the scaledown controller looks at the ordinal on the volume claim. The controller compares the ordinal on the volume claim to that of the broker pods that are still running in the StatefulSet (that is, the broker cluster) in the project.

   If the ordinal on the volume claim is higher than the ordinal on any of the broker Pods still running in the broker cluster, the scaledown controller determines that the broker Pod at that ordinal has been shut down and that messaging data must be migrated to another broker Pod.

3. The scaledown controller starts a drainer pod. The drainer pod connects to one of the other live broker pods in the cluster and migrates messages to that live broker pod.

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift Container Platform 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>

   2. Using the OpenShift Container Platform web console:

      1. Log in to OpenShift Container Platform as a user that has privileges to deploy CRs in the project for the broker deployment.
      2. In the left pane, click menu:Administration[Custom Resource Definitions].
      3. Click the ActiveMQArtemis CRD.
      4. Click the Instances tab.
      5. Click the instance for your broker deployment.

      6. Click the YAML tab.

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

2. In the deploymentPlan section of the CR, add a messageMigration attribute and set to true. If not already configured, add a persistenceEnabled attribute and also set to true. For example:

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

   These settings mean that when you later scale down the size of your clustered broker deployment, the Operator automatically starts a scaledown controller and migrates messages to a broker pod that is still running.

3. Save the CR.

4. (Optional) Complete the following steps to scale down the cluster and view the message migration process.

   1. In your existing broker deployment, verify which pods are running.

      $ oc get pods

      You see output that looks like the following.

      activemq-artemis-operator-8566d9bf58-9g25l   1/1   Running   0   3m38s
      ex-aao-ss-0                                  1/1   Running   0   112s
      ex-aao-ss-1                                  1/1   Running   0   8s

      The preceding output shows that there are three pods running; one for the broker Operator itself, and a separate pod for each broker in the deployment.

   2. Log into each pod and send some messages to each broker.

      1. Supposing that pod ex-aao-ss-0 has a cluster IP address of 172.17.0.6, run the following command:

         $ /opt/amq/bin/artemis producer --url tcp://172.17.0.6:61616 --user admin --password admin

   3. Supposing that pod ex-aao-ss-1 has a cluster IP address of 172.17.0.7, run the following command:

      $ /opt/amq/bin/artemis producer --url tcp://172.17.0.7:61616 --user admin --password admin

      The preceding commands create a queue called TEST on each broker and add 1000 messages to each queue.

   4. Scale the cluster down from two brokers to one.

      1. Open the main broker CR, broker_activemqartemis_cr.yaml.
      2. In the CR, set deploymentPlan.size to 1.

      3. At the command line, apply the change:

         $ oc apply -f deploy/crs/broker_activemqartemis_cr.yaml

         You see that the pod ex-aao-ss-1 starts to shut down. The scaledown controller starts a new drainer pod of the same name. This drainer pod also shuts down after it migrates all messages from broker pod ex-aao-ss-1 to the other broker pod in the cluster, ex-aao-ss-0.

   5. When the drainer pod is shut down, check the message count on the TEST queue of broker ood ex-aao-ss-0. You see that the number of messages in the queue is 2000, indicating that the drainer pod successfully migrated 1000 messages from the broker pod that shut down.

Procedure

1. Create a Custom Resource (CR) instance based on the main broker CRD.

   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>

      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 for the broker deployment.
      2. Start a new CR instance based on the main broker CRD. In the left pane, click menu: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.

2. In the deploymentPlan section of the CR, add a nodeSelector section and add the node label that you want to match to select a node for the pod. For example:

   spec:
       deploymentPlan:
         nodeSelector:
           app: broker1

   In this example, the broker pod is scheduled on a node that has a app: broker1 label.

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>

      3. Create the CR instance.

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

   2. Using the OpenShift web console:

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

Procedure

1. Create a Custom Resource (CR) instance based on the main broker CRD.

   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>

      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 for the broker deployment.
      2. Start a new CR instance based on the main broker CRD. In the left pane, click menu: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.

2. In the deploymentPlan section of the CR, add a tolerations section. In the tolerations section, add a toleration for the node taint that you want to match. For example:

   spec:
        deploymentPlan:
           tolerations:
           - key: "app"
             value: "amq-broker"
             effect: "NoSchedule"

   In this example, the toleration matches a node taint of app=amq-broker:NoSchedule, so the pod can be scheduled on a node that has this taint configured.

   Note

   To ensure that the broker pods are scheduled correctly, do not specify a tolerationsSeconds attribute in the tolerations section of the CR.

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>

      3. Create the CR instance.

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

   2. Using the OpenShift web console:

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

Procedure

1. Configure two ActiveMQArtemis custom resource instances to create separate broker deployments.

   In each custom resource, specify a unique name and ensure that the clustered and persistenceEnabled attributes are set to false. Set the size attribute to 1 to create a single broker in each deployment. For example:

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-a
   spec:
     deploymentPlan:
       size: 1
       clustered: false
       persistenceEnabled: false

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-b
   spec:
     deploymentPlan:
       size: 1
       clustered: false
       persistenceEnabled: false

   Note

   If both broker deployments are on the same OpenShift cluster, ensure that the broker pods are provisioned on separate nodes to avoid an outage of both brokers if a node failure occurs. For more information about controlling the placement of pods on nodes, see Section 4.17, “Controlling placement of broker pods on OpenShift Container Platform nodes”.

2. Add a new liveness probe to each CR.

   If you do not configure a liveness probe, a default probe is enabled to check the health of a broker. The default probe checks that the AMQ Management Console is reachable. In a leader-follower configuration, the AMQ Management Console is not reachable on the broker that is a follower at any given time, which causes the liveness probe to fail on that broker. Each time the liveness probe fails, it restarts the broker, which puts the broker in a persistent restart loop. As a result, the follower broker enters a CrashLoopBackOff state and is not available to become the leader if the current leader fails.

   To prevent the default liveness probe from running, you must configure a new liveness probe that can run successfully when a broker is either a leader or a follower. The following is an example of a liveness probe that meets this requirement. In this example, the liveness probe checks that the command to run the broker was executed, which is indicated by the presence of the cli.lock lock file.

   spec:
     ..
     livenessProbe:
       exec:
         command:
         - test
         - -f
         - /home/jboss/amq-broker/lock/cli.lock
     ..

   For more information about configuring liveness probes, see Section 4.15.2, “Configuring liveness and readiness probes”.

3. In each broker configuration, enable JDBC database persistence by using the brokerProperties attribute. For example:

   spec:
     ..
     brokerProperties:
     - storeConfiguration=DATABASE
     - storeConfiguration.jdbcDriverClassName=<class name>
     - storeConfiguration.jdbcConnectionUrl=jdbc:<Database URL>
     - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     - storeConfiguration.jdbcLockRenewPeriodMillis=2000
     - storeConfiguration.jdbcLockExpirationMillis=6000

   For more information about enabling JDBC database persistence, see Section 4.5.2, “Configuring database persistence”.

4. In each broker configuration, configure the broker to load the JAR file required to connect to the JDBC database.

   • Use the resourceTemplates attribute to customize the StatefulSet resource for each broker. In the customization, use the patch attribute to specify an init container that copies the JAR file from the custom container image you prepared to the broker pod.

   • Use the env attribute to create an ARTEMIS_EXTRA_LIBS environment variable to extend the broker’s Java classpath to include the directory to which the JAR file for the JDBC database is copied. By extending the Java classpath, the broker can load the JAR file from the specified directory on the pod at runtime.

     spec:
       ..
       env:
       - name: ARTEMIS_EXTRA_LIBS
         value: '/amq/init/config/extra-libs'
       resourceTemplates:
       - selector:
           kind: StatefulSet
         patch:
           kind: StatefulSet
           spec:
             template:
               spec:
                 initContainers:
                 - name: jdbc-driver-init
                   image: <custom container image with JAR>
                   volumeMounts:
                   - name: amq-cfg-dir
                     mountPath: /amq/init/config
                   command:
                   - "bash"
                   - "-c"
                   - "mkdir -p /amq/init/config/extra-libs && cp <__JAR file_> /amq/init/config/extra-libs"

     For more information about customizing OpenShift resources created by the Operator, see Section 4.21, “Customizing Openshift resources created by the Operator”.

5. Save each custom resource.

   The following example shows the configuration for leader-follower broker deployments that use an Oracle database.

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-a
   spec:
     deploymentPlan:
       size: 1
       clustered: false
       persistenceEnabled: false
       livenessProbe:
         exec:
           command:
           - test
           - -f
           - /home/jboss/amq-broker/lock/cli.lock
     env:
       - name: ARTEMIS_EXTRA_LIBS
         value: '/amq/init/config/extra-libs'
     brokerProperties:
       - criticalAnalyser=false
       - storeConfiguration=DATABASE
       - storeConfiguration.jdbcDriverClassName=oracle.jdbc.OracleDriver
       - storeConfiguration.jdbcConnectionUrl=jdbc:<Database URL>
       - storeConfiguration.jdbcLockRenewPeriodMillis=2000
       - storeConfiguration.jdbcLockExpirationMillis=6000
       - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     acceptors:
     - name: ext-acceptor
       protocols: CORE
       port: 61626
       expose: true
       sslEnabled: true
       sslSecret: ext-acceptor-ssl-secret
     console:
       expose: true
     resourceTemplates:
     - selector:
         kind: StatefulSet
       patch:
         kind: StatefulSet
         spec:
           template:
             spec:
               initContainers:
               - name: oracle-database-jdbc-driver-init
                 image: <custom container image with JAR>
                 volumeMounts:
                 - name: amq-cfg-dir
                   mountPath: /amq/init/config
                 command:
                 - "bash"
                 - "-c"
                 - "mkdir -p /amq/init/config/extra-libs && cp <JAR file> /amq/init/config/extra-libs"

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-b
   spec:
     deploymentPlan:
       size: 1
       clustered: false
       persistenceEnabled: false
       livenessProbe:
         exec:
           command:
           - test
           - -f
           - /home/jboss/amq-broker/lock/cli.lock
     env:
       - name: ARTEMIS_EXTRA_LIBS
         value: '/amq/init/config/extra-libs'
     brokerProperties:
       - criticalAnalyser=false
       - storeConfiguration=DATABASE
       - storeConfiguration.jdbcDriverClassName=oracle.jdbc.OracleDriver
       - storeConfiguration.jdbcConnectionUrl=jdbc:<Database URL>
       - storeConfiguration.jdbcLockRenewPeriodMillis=2000
       - storeConfiguration.jdbcLockExpirationMillis=6000
       - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     acceptors:
     - name: ext-acceptor
       protocols: CORE
       port: 61626
       expose: true
       sslEnabled: true
       sslSecret: ext-acceptor-ssl-secret
     console:
       expose: true
     resourceTemplates:
     - selector:
         kind: StatefulSet
       patch:
         kind: StatefulSet
         spec:
           template:
             spec:
               initContainers:
               - name: oracle-database-jdbc-driver-init
                 image: <custom container image with JAR>
                 volumeMounts:
                 - name: amq-cfg-dir
                   mountPath: /amq/init/config
                 command:
                 - "bash"
                 - "-c"
                 - "mkdir -p /amq/init/config/extra-libs && cp <JAR file> /amq/init/config/extra-libs"

Procedure

1. Prepare and apply a YAML configuration to create leader-follower broker deployments.

   Ensure that you set the persistenceEnabled attribute to false so the Operator does not create the resources to attach a separate persistent volume to each broker pod. In a leader-follower configuration, both brokers must share the same persistent volume, which must be provisioned before you apply the YAML configuration. The Operator uses the extraVolumes and extraVolumeMount attributes in the YAML to mount that persistent volume on both pods. In addition, the Operator uses the brokerProperties attributes in the YAML to create the journal and other data files on that volume.

   For example:

   oc apply -f - <<EOF
   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-a
   spec:
     deploymentPlan:
       size: 1
       persistenceEnabled: false
       clustered: false
       extraVolumes:
       - name: extra-volume
         persistentVolumeClaim:
           claimName: shared-volume
       extraVolumeMounts:
       - name: extra-volume
         mountPath: /opt/amq-broker/data
       livenessProbe:
         exec:
           command:
           - test
           - -f
           - /home/jboss/amq-broker/lock/cli.lock
     brokerProperties:
     - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     - journalDirectory=/opt/amq-broker/data/journal
     - pagingDirectory=/opt/amq-broker/data/paging,
     - bindingsDirectory=/opt/amq-broker/data/bindings
     - largeMessagesDirectory=/opt/amq-broker/data/largemessages
     acceptors:
     - name: ext-acceptor
       protocols: CORE
       port: 61626
       expose: true
       sslEnabled: true
       sslSecret: ext-acceptor-ssl-secret
   ---
   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: peer-broker-b
   spec:
     deploymentPlan:
       size: 1
       persistenceEnabled: false
       clustered: false
       extraVolumes:
       - name: extra-volume
         persistentVolumeClaim:
           claimName: shared-volume
       extraVolumeMounts:
       - name: extra-volume
         mountPath: /opt/amq-broker/data
       livenessProbe:
         exec:
           command:
           - test
           - -f
           - /home/jboss/amq-broker/lock/cli.lock
     brokerProperties:
     - HAPolicyConfiguration=SHARED_STORE_PRIMARY
     - journalDirectory=/opt/amq-broker/data/journal
     - pagingDirectory=/opt/amq-broker/data/paging,
     - bindingsDirectory=/opt/amq-broker/data/bindings
     - largeMessagesDirectory=/opt/amq-broker/data/largemessages
     acceptors:
     - name: ext-acceptor
       protocols: CORE
       port: 61626
       expose: true
       sslEnabled: true
       sslSecret: ext-acceptor-ssl-secret
   EOF

   Note

   If both broker deployments are on the same OpenShift cluster, ensure that the broker pods are provisioned on separate nodes to avoid an outage of both brokers if a node failure occurs. For more information about controlling the placement of pods on nodes, see Section 4.17, “Controlling placement of broker pods on OpenShift Container Platform nodes”.

   The following table describes the YAML configuration in the example that is specific to a leader-follower deployment.

   Expand

   Table 4.8. Leader-follower configuration

   Attribute	Description
   metadata.name	Specify a unique name for the broker in each deployment.
   size	Specify a value of 1 to create a single broker in each deployment.
   persistenceEnabled	Set to false so the Operator does not create the resources to attach a separate persistent volume to each broker pod. In a leader-follower configuration, both brokers must share the same persistent volume, which must be provisioned before you apply the leader-follower YAML configuration.
   clustered	Set to false to disable clustering.
   extraVolumes	Specify the details of the PVC you created to request a shared persistent volume for the brokers, which is a prerequisite to creating leader-follower deployments. name Use a string value to assign a name to the volume. claimName Ensure that this matches the value of the metadata.name attribute in the PVC you created.
   extraVolumeMounts	Specify the details to mount the shared persistent volume on each broker pod. name Ensure that this matches the extraVolumes.name value. mountPath The path to which the shared volume is mounted on each broker pod.
   livenessProbe	A default liveness probe is enabled to check the health of a broker. The default probe checks that the AMQ Management Console is reachable. In a leader-follower configuration, the AMQ Management Console is not reachable on the broker that is a follower at any given time, which causes the liveness probe to fail on that broker. Each time the liveness probe fails, it restarts the broker, which puts the broker in a persistent restart loop. As a result, the follower broker enters a CrashLoopBackOff state and is not available to become the leader if the current leader fails. Configure a new liveness probe that can run successfully when a broker is either a leader or a follower, as shown in the example. In the example, the liveness probe checks that the command to run the broker was executed, which is indicated by the presence of the cli.lock lock file. For more information about configuring liveness probes, see Section 4.15.2, “Configuring liveness and readiness probes”.
   brokerProperties	Specify the directories on the mounted persistent volume to store the journal and other messaging data files. HAPolicyConfiguration Set to SHARED_STORE_PRIMARY to ensure that the broker uses a file lock to protect the broker from concurrent access by both brokers. journalDirectory File system location to store the message journal. pagingDirectory File system location to store paged messages. bindingsDirectory File system location to store the bindings journal. largeMessagesDirectory File system location to store large messages.

   Show more

2. Use the oc get pods command to identify which broker is the leader and which is the follower. In the following example, peer-broker-a-ss-0 is the leader, which is indicated by the 1/1 entry in the READY column.

   NAME                 READY   STATUS             RESTARTS         AGE
   peer-broker-a-ss-0   1/1     Running            0                72m
   peer-broker-b-ss-0   0/1     Running            0                72m