Deploying AMQ Broker on OpenShift

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   $ mkdir ~/broker/operator
   $ mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   $ cd ~/broker/operator
   $ unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Switch to the directory that was created when you extracted the archive. For example:

   $ cd amq-broker-operator-7.8.5-ocp-install-examples

7. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

8. Specify the project in which you want to install the Operator. You can create a new project or switch to an existing one.

   1. Create a new project:

      $ oc new-project <project-name>

   2. Or, switch to an existing project:

      $ oc project <project-name>

9. Specify a service account to use with the Operator.

   1. In the deploy directory of the Operator archive that you extracted, open the service_account.yaml file.
   2. Ensure that the kind element is set to ServiceAccount.
   3. In the metadata section, assign a custom name to the service account, or use the default name. The default name is amq-broker-operator.

   4. Create the service account in your project.

      $ oc create -f deploy/service_account.yaml

10. Specify a role name for the Operator.

    1. Open the role.yaml file. This file specifies the resources that the Operator can use and modify.
    2. Ensure that the kind element is set to Role.
    3. In the metadata section, assign a custom name to the role, or use the default name. The default name is amq-broker-operator.

    4. Create the role in your project.

       $ oc create -f deploy/role.yaml

11. Specify a role binding for the Operator. The role binding binds the previously-created service account to the Operator role, based on the names you specified.

    1. Open the role_binding.yaml file. Ensure that the name values for ServiceAccount and Role match those specified in the service_account.yaml and role.yaml files. For example:

       metadata:
           name: amq-broker-operator
       subjects:
           kind: ServiceAccount
           name: amq-broker-operator
       roleRef:
           kind: Role
           name: amq-broker-operator

    2. Create the role binding in your project.

       $ oc create -f deploy/role_binding.yaml

Procedure

1. In the OpenShift command-line interface (CLI), log in to OpenShift as a cluster administrator. For example:

   $ oc login -u system:admin

2. Switch to the project that you previously prepared for the Operator deployment. For example:

   $ oc project <project_name>

3. Switch to the directory that was created when you previously extracted the Operator installation archive. For example:

   $ cd ~/broker/operator/amq-broker-operator-7.8.5-ocp-install-examples

4. Deploy the CRDs that are included with the Operator. You must install the CRDs in your OpenShift cluster before deploying and starting the Operator.

   1. Deploy the main broker CRD.

      $ oc create -f deploy/crds/broker_activemqartemis_crd.yaml

   2. Deploy the address CRD.

      $ oc create -f deploy/crds/broker_activemqartemisaddress_crd.yaml

   3. Deploy the scaledown controller CRD.

      $ oc create -f deploy/crds/broker_activemqartemisscaledown_crd.yaml

5. Link the pull secret associated with the account used for authentication in the Red Hat Ecosystem Catalog with the default, deployer, and builder service accounts for your OpenShift project.

   $ oc secrets link --for=pull default <secret_name>
   $ oc secrets link --for=pull deployer <secret_name>
   $ oc secrets link --for=pull builder <secret_name>

6. In the deploy directory of the Operator archive that you downloaded and extracted, open the operator.yaml file.

   Note

   In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

7. Deploy the Operator.

   $ oc create -f deploy/operator.yaml

   In your OpenShift project, the Operator starts in a new Pod.

   In the OpenShift Container Platform web console, the information on the Events tab of the Operator Pod confirms that OpenShift has deployed the Operator image that you specified, has assigned a new container to a node in your OpenShift cluster, and has started the new container.

   In addition, if you click the Logs tab within the Pod, the output should include lines resembling the following:

   ...
   {"level":"info","ts":1553619035.8302743,"logger":"kubebuilder.controller","msg":"Starting Controller","controller":"activemqartemisaddress-controller"}
   {"level":"info","ts":1553619035.830541,"logger":"kubebuilder.controller","msg":"Starting Controller","controller":"activemqartemis-controller"}
   {"level":"info","ts":1553619035.9306898,"logger":"kubebuilder.controller","msg":"Starting workers","controller":"activemqartemisaddress-controller","worker count":1}
   {"level":"info","ts":1553619035.9311671,"logger":"kubebuilder.controller","msg":"Starting workers","controller":"activemqartemis-controller","worker count":1}

   The preceding output confirms that the newly-deployed Operator is communicating with Kubernetes, that the controllers for the broker and addressing are running, and that these controllers have started some workers.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 releases.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Releases tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Switch to the directory for the Operator archive that you extracted. For example:

   cd amq-broker-operator-7.8.5-ocp-install-examples

7. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

8. Install the Operator in OperatorHub.

   $ oc create -f deploy/catalog_resources/activemq-artemis-operatorsource.yaml

   After a few minutes, the Operator for AMQ Broker 7.8 is available in the OperatorHub section of the OpenShift Container Platform web console. The name of the Operator is Red Hat Integration - AMQ Broker.

Procedure

1. Log in to the OpenShift Container Platform web console as a cluster administrator.
2. In left navigation menu, click Operators → OperatorHub.
3. On the Project drop-down menu at the top of the OperatorHub page, select the project in which you want to deploy the Operator.

4. On the OperatorHub page, use the Filter by keyword…​ box to find the Red Hat Integration - AMQ Broker Operator.

   Note

   In OperatorHub, you might find more than one Operator than includes AMQ Broker in its name. Ensure that you click the Red Hat Integration - AMQ Broker Operator. When you click this Operator, review the information pane that opens. For AMQ Broker 7.8, the latest minor version tag of this Operator is 7.8.5-opr-2.

   The Operator for RHEL 8 that provides RHEL 8 images is named Red Hat Integration - AMQ Broker for RHEL 8 and has the version 7.8.5-opr-2.

   To determine which Operator to choose, see the Red Hat Enterprise Linux Container Compatibility Matrix.

5. Click the Red Hat Integration - AMQ Broker Operator. On the dialog box that appears, click Install.

6. On the Install Operator page:

   1. Under Update Channel, specify the channel used to track and receive updates for the Operator by selecting one of the following radio buttons:

      • 7.x - This channel will update to 7.9 when available.
      • 7.8.x - This is the Long Term Support (LTS) channel.
   2. Under Installation Mode, ensure that the radio button entitled A specific namespace on the cluster is selected.
   3. From the Installed Namespace drop-down menu, select the project in which you want to install the Operator.
   4. Under Approval Strategy, ensure that the radio button entitled Automatic is selected. This option specifies that updates to the Operator do not require manual approval for installation to take place.
   5. Click Install.

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>

      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. This configuration is the default content of the broker_activemqartemis_cr.yaml sample CR file.

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

   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.4, “How the Operator chooses container images”.

   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.

   Note

   The broker_activemqartemis_cr.yaml sample CR uses a naming convention of ex-aao. This naming convention denotes that the CR is an example resource for the AMQ Broker Operator. AMQ Broker is based on the ActiveMQ Artemis project. When you deploy this sample CR, the resulting StatefulSet uses the name ex-aao-ss. Furthermore, broker Pods in the deployment are directly based on the StatefulSet name, for example, ex-aao-ss-0, ex-aao-ss-1, and so on. The application name in the CR appears in the deployment as a label on the StatefulSet. You might use this label in a Pod selector, for example.

2. The size property specifies the number of brokers to deploy. A value of 2 or greater specifies a clustered broker deployment. However, to deploy a single broker instance, ensure that the value is set to 1.

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.

4. In the OpenShift Container Platform web console, click Workloads → StatefulSets (OpenShift Container Platform 4.5 or later) or Applications → StatefulSets (OpenShift Container Platform 3.11). You see a new StatefulSet called ex-aao-ss.

   1. Click the ex-aao-ss StatefulSet. You see that there is one Pod, corresponding to the single broker that you defined in the CR.
   2. Within the StatefulSet, click the Pods tab. Click the ex-aao-ss Pod. On the Events tab of the running Pod, you see that the broker container has started. The Logs tab shows that the broker itself is running.

5. To test that the broker is running normally, access a shell on the broker Pod to send some test messages.

   1. Using the OpenShift Container Platform web console:

      1. Click Workloads → Pods (OpenShift Container Platform 4.5 or later) or Applications → Pods (OpenShift Container Platform 3.11).
      2. Click the ex-aao-ss Pod.
      3. Click the Terminal tab.

   2. Using the OpenShift command-line interface:

      1. Get the Pod names and internal IP addresses for your project.

         $ oc get pods -o wide
         
         NAME                          STATUS   IP
         amq-broker-operator-54d996c   Running  10.129.2.14
         ex-aao-ss-0                   Running  10.129.2.15

      2. Access the shell for the broker Pod.

         $ oc rsh ex-aao-ss-0

6. From the shell, use the artemis command to send some test messages. Specify the internal IP address of the broker Pod in the URL. For example:

   sh-4.2$ ./amq-broker/bin/artemis producer --url tcp://10.129.2.15:61616 --destination queue://demoQueue

   The preceding command automatically creates a queue called demoQueue on the broker and sends a default quantity of 1000 messages to the queue.

   You should see output that resembles the following:

   Connection brokerURL = tcp://10.129.2.15:61616
   Producer ActiveMQQueue[demoQueue], thread=0 Started to calculate elapsed time ...
   
   Producer ActiveMQQueue[demoQueue], thread=0 Produced: 1000 messages
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in second : 3 s
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in milli second : 3492 milli seconds

Procedure

1. Open the CR file that you used for your basic broker deployment.

2. For a clustered deployment, ensure that the value of deploymentPlan.size is 2 or greater. For example:

   apiVersion: broker.amq.io/v2alpha4
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
     application: ex-aao-app
   spec:
       version: 7.8.5
       deploymentPlan:
           size: 4
           image: placeholder
           ...

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

4. Log in to OpenShift as a user that has privileges to deploy CRs in the project in which you previously created your basic broker deployment.

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

5. Switch to the project in which you previously created your basic broker deployment.

   $ oc project <project_name>

6. At the command line, apply the change:

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

   In the OpenShift Container Platform web console, additional broker Pods starts in your project, according to the number specified in your CR. By default, the brokers running in the project are clustered.

7. Open the Logs tab of each Pod. The logs show that OpenShift has established a cluster connection bridge on each broker. Specifically, the log output includes a line like the following:

   targetConnector=ServerLocatorImpl (identity=(Cluster-connection-bridge::ClusterConnectionBridge@6f13fb88

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

      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/v2alpha2
   kind: ActiveMQArtemisAddress
   metadata:
       name: myAddressDeployment0
       namespace: myProject
   spec:
       ...
       addressName: myAddress0
       queueName: myQueue0
       routingType: anycast
       ...

   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>

      3. Create the CR instance.

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

   2. Using the OpenShift web console:

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

4. (Optional) To delete an address and queue previously added to your deployment using a CR instance, use the following command:

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

Procedure

1. Start configuring a CR instance to add a dead letter address and queue to receive undelivered messages for each broker in the 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>

      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 specify a dead letter address and queue to receive undelivered messages. For example:

   apiVersion: broker.amq.io/v2alpha2
   kind: ActiveMQArtemisAddress
   metadata:
       name: ex-aaoaddress
   spec:
       ...
       addressName: myDeadLetterAddress
       queueName: myDeadLetterQueue
       routingType: anycast
       ...

   The preceding configuration defines a dead letter address named myDeadLetterAddress with a dead letter queue named myDeadLetterQueue 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 address 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>

      3. Create the address CR.

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

   2. Using the OpenShift web console:

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

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

   1. From a sample CR file:

      1. 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. Start a new CR instance based on the main broker CRD. In the left pane, click Administration → Custom Resource Definitions.
      2. Click the ActiveMQArtemis CRD.
      3. Click the Instances tab.

      4. 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. This configuration is the default content of the broker_activemqartemis_cr.yaml sample CR file.

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

   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.4, “How the Operator chooses container images”.

   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.

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

   spec:
       version: 7.8.5
       deploymentPlan:
           size: 1
           image: placeholder
           requireLogin: false
           persistenceEnabled: true
           journalType: nio
           messageMigration: true
           addressSettings:
               addressSetting:

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

   spec:
       version: 7.8.5
       deploymentPlan:
           size: 1
           image: placeholder
           requireLogin: false
           persistenceEnabled: true
           journalType: nio
           messageMigration: true
           addressSettings:
               addressSetting:
                -  match: myAddress

   match

   Specifies the address, or set of address 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.

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

   spec:
       version: 7.8.5
       deploymentPlan:
           size: 1
           image: placeholder
           requireLogin: false
           persistenceEnabled: true
           journalType: nio
           messageMigration: true
           addressSettings:
               addressSetting:
                -  match: myAddress
                   deadLetterAddress: myDeadLetterAddress
                   maxDeliveryAttempts: 5

   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.

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

   spec:
       version: 7.8.5
       deploymentPlan:
           size: 1
           image: placeholder
           requireLogin: false
           persistenceEnabled: true
           journalType: nio
           messageMigration: true
           addressSettings:
               addressSetting:
                -  match: myAddress
                   deadLetterAddress: myDeadLetterAddress
                   maxDeliveryAttempts: 5
                -  match: 'myOtherAddresses*'
                   deadLetterAddress: myDeadLetterAddress
                   maxDeliveryAttempts: 3

   In this example, the value of the second match property includes an asterisk 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*'.

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

   spec:
       version: 7.8.5
       deploymentPlan:
           size: 1
           image: placeholder
           requireLogin: false
           persistenceEnabled: true
           journalType: nio
           messageMigration: true
           addressSettings:
               applyRule: merge_all
               addressSetting:
                -  match: myAddress
                   deadLetterAddress: myDeadLetterAddress
                   maxDeliveryAttempts: 5
                -  match: 'myOtherAddresses*'
                   deadLetterAddress: myDeadLetterAddress
                   maxDeliveryAttempts: 3

   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.

10. Deploy the broker CR instance.

    1. Using the OpenShift command-line interface:

       1. Save the CR file.

       2. Create the CR instance.

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

    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>

      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. This configuration is the default content of the broker_activemqartemis_cr.yaml sample CR file.

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

   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.4, “How the Operator chooses container images”.

   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.

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

   spec:
       version: 7.8.5
       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. Supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi).

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

      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. This configuration is the default content of the broker_activemqartemis_cr.yaml sample CR file.

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

   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.4, “How the Operator chooses container images”.

   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.

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:
       version: 7.8.5
       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.

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. In the deploy/crs directory of the Operator archive that you downloaded and extracted during your initial installation, open the broker_activemqartemis_cr.yaml Custom Resource (CR) file.

2. In the acceptors element, add a named acceptor. Add the protocols and port parameters. 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 parameter is shown in the table.

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

   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 parameter. 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 parameter 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, add the expose parameter and set the value to true.

   In addition, to enable secure connections to the acceptor from clients outside OpenShift, add the sslEnabled parameter and set the value 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. For more information on generating this secret, see Section 4.6.2, “Securing broker-client connections”.
   • 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 parameter.
   • Whether the acceptor uses two-way TLS, also known as mutual authentication, between the broker and the client. You specify this by setting the value of the needClientAuth parameter to true.

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

1. When a broker Pod in the deployment shuts down due to failure or intentional scaledown of the deployment, the Operator automatically starts a scaledown controller to prepare for message migration. The scaledown controller runs in the same OpenShift project name as the broker cluster.
2. The scaledown controller registers itself and listens for Kubernetes events that are related to Persistent Volume Claims (PVCs) in the project.

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

4. The scaledown controller starts a drainer Pod. The drainer Pod runs the broker and executes the message migration. Then, the drainer Pod identifies an alternative broker Pod to which the orphaned messages can be migrated.

   Note

   There must be at least one broker Pod still running in your deployment for message migration to occur.

Procedure

1. In the deploy/crs directory of the Operator repository that you originally downloaded and extracted, open the main broker CR, broker_activemqartemis_cr.yaml.

2. In the main broker CR set messageMigration and persistenceEnabled to 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. 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.

4. 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-broker/bin/artemis producer --url tcp://172.17.0.6:61616 --user admin --password admin

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

      $ /opt/amq-broker/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.

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

6. When the drainer Pod is shut down, check the message count on the TEST queue of broker Pod 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. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as an administrator for the project that contains your existing Operator deployment.

   $ oc login -u <user>

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

   Note

   In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

9. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.
10. If you have made any updates to the new operator.yaml file, save the file.

11. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

12. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as an administrator for the project that contains your existing Operator deployment.

   $ oc login -u <user>

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

   Note

   In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

9. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.

   Note

   The operator.yaml file for version 0.18 of the Operator includes environment variables whose names begin with BROKER_IMAGE. Do not replicate these environment variables in your new configuration. The latest version of the Operator for AMQ Broker 7.8 no longer uses these environment variables.

10. If you have made any updates to the new operator.yaml file, save the file.

11. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

12. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. Delete the main broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. For example:

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

9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version.

   $ oc apply -f deploy/crds/broker_activemqartemis_crd.yaml

   Note

   You do not need to update your cluster with the latest versions of the CRDs for addressing or the scaledown controller. These CRDs are fully compatible with the ones included with the previous Operator version.

10. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

    Note

    In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

11. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.

    Note

    The operator.yaml file for version 0.17 of the Operator includes environment variables whose names begin with BROKER_IMAGE. Do not replicate these environment variables in your new configuration. The latest version of the Operator for AMQ Broker 7.8 no longer uses these environment variables.

12. If you have made any updates to the new operator.yaml file, save the file.

13. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

14. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. Delete the main broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. For example:

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

9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version.

   $ oc apply -f deploy/crds/broker_activemqartemis_crd.yaml

   Note

   You do not need to update your cluster with the latest versions of the CRDs for addressing or the scaledown controller. These CRDs are fully compatible with the ones included with the previous Operator version.

10. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

    Note

    In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

11. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.

    Note

    The operator.yaml file for version 0.15 of the Operator includes environment variables whose names begin with BROKER_IMAGE. Do not replicate these environment variables in your new configuration. The latest version of the Operator for AMQ Broker 7.8 no longer uses these environment variables.

12. If you have made any updates to the new operator.yaml file, save the file.

13. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

14. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. Delete the main broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. For example:

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

9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version.

   $ oc apply -f deploy/crds/broker_activemqartemis_crd.yaml

10. Update the address CRD in your OpenShift cluster to the latest version included with AMQ Broker 7.8.

    $ oc apply -f deploy/crds/broker_activemqartemisaddress_crd.yaml

    Note

    You do not need to update your cluster with the latest version of the CRD for the scaledown controller. In AMQ Broker 7.8, this CRD is fully compatible with the one that was included with the Operator for AMQ Broker 7.6.

11. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

    Note

    In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

12. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.
13. If you have made any updates to the new operator.yaml file, save the file.

14. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

Procedure

1. In your web browser, navigate to the Software Downloads page for AMQ Broker 7.8.5 patches.
2. Ensure that the value of the Version drop-down list is set to 7.8.5 and the Patches tab is selected.

3. Next to AMQ Broker 7.8.5 .3 Operator Installation and Example Files, click Download.

   Download of the amq-broker-operator-7.8.5-ocp-install-examples.zip compressed archive automatically begins.

4. When the download has completed, move the archive to your chosen installation directory. The following example moves the archive to a directory called ~/broker/operator.

   mkdir ~/broker/operator
   mv amq-broker-operator-7.8.5-ocp-install-examples.zip ~/broker/operator

5. In your chosen installation directory, extract the contents of the archive. For example:

   cd ~/broker/operator
   unzip amq-broker-operator-7.8.5-ocp-install-examples.zip

6. Log in to OpenShift Container Platform as a cluster administrator. For example:

   $ oc login -u system:admin

7. Switch to the OpenShift project in which you want to upgrade your Operator version.

   $ oc project <project-name>

8. Delete the main broker Custom Resource (CR) instance in your project. This also deletes the broker deployment. For example:

   $ oc delete -f deploy/crs/broker_v2alpha1_activemqartemis_cr.yaml

9. Update the main broker Custom Resource Definition (CRD) in your OpenShift cluster to the latest version included with AMQ Broker 7.8.

   $ oc apply -f deploy/crds/broker_activemqartemis_crd.yaml

10. Update the address CRD in your OpenShift cluster to the latest version included with AMQ Broker 7.8.

    $ oc apply -f deploy/crds/broker_activemqartemisaddress_crd.yaml

    Note

    You do not need to update your cluster with the latest version of the CRD for the scaledown controller. In AMQ Broker 7.8, this CRD is fully compatible with the one included with the previous Operator version.

11. In the deploy directory of the latest Operator archive that you downloaded and extracted, open the operator.yaml file.

    Note

    In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

12. Open the operator.yaml file for your previous Operator deployment. Check that any non-default values that you specified in your previous configuration are replicated in the new operator.yaml configuration file.
13. If you have made any updates to the new operator.yaml file, save the file.

14. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

    OpenShift updates your project to use the latest Operator version.

15. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. Log in to the OpenShift Container Platform web console as a cluster administrator.

2. Delete the main Custom Resource (CR) instance for the broker deployment in your project. This action deletes the broker deployment.

   1. In the left navigation menu, click Administration → Custom Resource Definitions.
   2. On the Custom Resource Definitions page, click the ActiveMQArtemis CRD.
   3. Click the Instances tab.
   4. Locate the CR instance that corresponds to your project namespace.
   5. For your CR instance, click the More Options icon (three vertical dots) on the right-hand side. Select Delete ActiveMQArtemis.

3. Uninstall the existing AMQ Broker Operator from your project.

   1. In the left navigation menu, click Operators → Installed Operators.
   2. From the Project drop-down menu at the top of the page, select the project in which you want to uninstall the Operator.
   3. Locate the Red Hat Integration - AMQ Broker instance that you want to uninstall.
   4. For your Operator instance, click the More Options icon (three vertical dots) on the right-hand side. Select Uninstall Operator.
   5. On the confirmation dialog box, click Uninstall.
4. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.8. For more information, see Section 3.3.3, “Deploying the Operator from OperatorHub”.
5. To recreate your previous broker deployment, create a new CR yaml file to match the purpose of your original CR and apply it. Section 3.4.1, “Deploying a basic broker instance”. describes how to apply the deploy/crs/broker_activemqartemis_cr.yaml file in the Operator installation archive, you can use that file as a basis for your new CR yaml file.

Procedure

1. Log in to the amq-demo project space, or another, existing project in which you want to deploy a broker.

   $ oc login -u <USER_NAME>
   $ oc project <PROJECT_NAME>

2. Create a new broker application, based on the template for a basic broker. The broker created by this template is ephemeral and does not support SSL.

   $ oc new-app --template=amq-broker-78-basic \
      -p AMQ_PROTOCOL=openwire,amqp,stomp,mqtt,hornetq \
      -p AMQ_QUEUES=demoQueue \
      -p AMQ_ADDRESSES=demoTopic \
      -p AMQ_USER=amq-demo-user \
      -p AMQ_PASSWORD=password \

   The basic broker application template sets the environment variables shown in the following table.

   Table 7.1. Basic broker application template

   Environment variable	Display Name	Value	Description
   AMQ_PROTOCOL	AMQ Protocols	openwire,amqp,stomp,mqtt,hornetq	The protocols to be accepted by the broker
   AMQ_QUEUES	Queues	demoQueue	Creates an anycast queue called demoQueue
   AMQ_ADDRESSES	Addresses	demoTopic	Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
   AMQ_USER	AMQ Username	amq-demo-user	User name that the client uses to connect to the broker
   AMQ_PASSWORD	AMQ Password	password	Password that the client uses with the user name to connect to the broker

Procedure

1. Click Deployments in the OpenShift Container Platform web console.
2. Click the broker-amq application.

3. Click Deploy.

   Note

   If the application does not deploy, you can check the configuration by clicking the Events tab. If something is incorrect, edit the deployment configuration by clicking the Actions button.

4. After you deploy the broker application, inspect the current state of the broker Pod.

   1. Click DeploymentConfigs.

   2. Click the broker-amq Pod and then click the Logs tab to verify the state of the broker. You should see the queue previously created via the application template.

      If the logs show that:

      • The broker is running, skip to step 9 of this procedure.
      • The broker logs have not loaded, and the Pod status shows ErrImagePull or ImagePullBackOff, your deployment configuration was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, continue to step 5 of this procedure.

5. To prepare the Pod for installation of the broker container image, scale the number of running brokers to 0.

   1. Click DeploymentConfigs → broker-amq.
   2. Click Actions → Edit DeploymentConfigs.
   3. In the deployment config .yaml file, set the value of the replicas attribute to 0.
   4. Click Save.
   5. The pod restarts, with zero broker instances running.

6. Install the latest broker container image.

   1. In your web browser, navigate to the Red Hat Container Catalog.
   2. In the search box, enter AMQ Broker. Click Search.

   3. Choose an image repository based on the information in the following table.

      Platform (Architecture)	Container image name	Repository name
      OpenShift Container Platform (amd64)	AMQ Broker or AMQ Broker for RHEL 8	amq7/amq-broker or amq7/amq-broker-rhel8
      OpenShift Container Platform on IBM Z (s390x)	AMQ Broker for RHEL 8 on OpenJDK 11	amq7/amq-broker-openjdk-11-rhel8
      OpenShift Container Platform on IBM Power Systems (ppc64le)	AMQ Broker for RHEL 8 on OpenJDK 11	amq7/amq-broker-openjdk-11-rhel8

      For example, for the OpenShift Container Platform broker container image, click AMQ Broker. The amq7/amq-broker repository opens, with the most recent image version automatically selected. If you want to change to an earlier image version, click the Tags tab and choose another version tag.

   4. Click the Get This Image tab.

   5. Under Authentication with registry tokens, review the on-page instructions in the Using OpenShift secrets section. The instructions describe how to add references to the broker image and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry to your Pod deployment configuration file.

      For example, to reference the broker image and pull secret in the broker-amq deployment configuration in the amq-demo project namespace, include lines that look like the following:

      apiVersion: apps.openshift.io/v1
      kind: DeploymentConfig
      ..
      metadata:
        name: broker-amq
        namespace: amq-demo
      ..
        spec:
          containers:
              name: broker-amq
              image: 'registry.redhat.io/amq7/amq-broker:7.8'
          ..
          imagePullSecrets:
            - name: {PULL-SECRET-NAME}

   6. Click Save.

7. Import the latest broker image version to your project namespace. For example:

   $ oc import-image amq7/amq-broker:7.8 --from=registry.redhat.io/amq7/amq-broker --confirm

8. Edit the broker-amq deployment config again, as previously described. Set the value of the replicas attribute back to its original value.

   The broker Pod restarts, with all running brokers referencing the new broker image.

9. Click the Terminal tab to access a shell where you can start the broker and use the CLI to test sending and consuming messages.

   sh-4.2$ ./broker/bin/artemis run
   sh-4.2$ ./broker/bin/artemis producer --destination queue://demoQueue
   Producer ActiveMQQueue[demoQueue], thread=0 Started to calculate elapsed time ...
   
   Producer ActiveMQQueue[demoQueue], thread=0 Produced: 1000 messages
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in second : 4 s
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in milli second : 4584 milli seconds
   sh-4.2$ ./broker/bin/artemis consumer --destination queue://demoQueue
   Consumer:: filter = null
   Consumer ActiveMQQueue[demoQueue], thread=0 wait until 1000 messages are consumed
   Received 1000
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumed: 1000 messages
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumer thread finished

   Alternatively, use the OpenShift client to access the shell using the Pod name, as shown in the following example.

   // Get the Pod names and internal IP Addresses
   $ oc get pods -o wide
   
   // Access a broker Pod by name
   $ oc rsh <broker-pod-name>

Procedure

1. Generate a self-signed certificate for the broker keystore:

   $ keytool -genkey -alias broker -keyalg RSA -keystore broker.ks

2. Export the certificate so that it can be shared with clients:

   $ keytool -export -alias broker -keystore broker.ks -file broker_cert

3. Generate a self-signed certificate for the client keystore:

   $ keytool -genkey -alias client -keyalg RSA -keystore client.ks

4. Create a client truststore that imports the broker certificate:

   $ keytool -import -alias broker -keystore client.ts -file broker_cert

5. Export the client’s certificate from the keystore:

   $ keytool -export -alias client -keystore client.ks -file client_cert

6. Import the client’s exported certificate into a broker SERVER truststore:

   $ keytool -import -alias client -keystore broker.ts -file client_cert

Procedure

1. Navigate to the OpenShift web console and log in.
2. Select the amq-demo project space.
3. Click Add to Project > Browse Catalog to list all of the default image streams and templates.
4. Use the Filter search bar to limit the list to those that match amq. You might need to click See all to show the desired application template.
5. Select the amq-broker-78-ssl template which is labeled Red Hat AMQ Broker 7.8 (Ephemeral, with SSL).

6. Set the following values in the configuration and click Create.

   Table 8.1. Example template

   Environment variable	Display Name	Value	Description
   AMQ_PROTOCOL	AMQ Protocols	openwire,amqp,stomp,mqtt,hornetq	The protocols to be accepted by the broker
   AMQ_QUEUES	Queues	demoQueue	Creates an anycast queue called demoQueue
   AMQ_ADDRESSES	Addresses	demoTopic	Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
   AMQ_USER	AMQ Username	amq-demo-user	The username the client uses
   AMQ_PASSWORD	AMQ Password	password	The password the client uses with the username
   AMQ_TRUSTSTORE	Trust Store Filename	broker.ts	The SSL truststore file name
   AMQ_TRUSTSTORE_PASSWORD	Truststore Password	password	The password used when creating the Truststore
   AMQ_KEYSTORE	AMQ Keystore Filename	broker.ks	The SSL keystore file name
   AMQ_KEYSTORE_PASSWORD	AMQ Keystore Password	password	The password used when creating the Keystore

Procedure

1. Click Deployments in the OpenShift Container Platform web console.
2. Click the broker-amq deployment.
3. Click Deploy to deploy the application.

4. Click the broker Pod and then click the Logs tab to verify the state of the broker.

   If the broker logs have not loaded, and the Pod status shows ErrImagePull or ImagePullBackOff, your deployment configuration was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, edit your deployment configuration to reference the correct broker image name and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry. Then, you can import the broker image and start the broker. To do this, complete steps similar to those in Deploying and starting the broker application.

Procedure

1. Click Services → broker-amq-tcp-ssl.
2. Click Actions → Create a route.
3. To display the TLS parameters, select the Secure route check box.
4. From the TLS Termination drop-down menu, choose Passthrough. This selection relays all communication to AMQ Broker without the OpenShift router decrypting and resending it.

5. To view the Route, click Routes. For example:

   https://broker-amq-tcp-amq-demo.router.default.svc.cluster.local

Procedure

1. Navigate to the OpenShift web console and log in.
2. Select the amq-demo project space.
3. Click Add to Project → Browse catalog to list all of the default image streams and templates.
4. Use the Filter search bar to limit the list to those that match amq. You might need to click See all to show the desired application template.
5. Select the amq-broker-78-persistence-ssl template, which is labelled Red Hat AMQ Broker 7.8 (Persistence, with SSL).

6. Set the following values in the configuration and click create.

   Table 8.2. Example template

   Environment variable	Display Name	Value	Description
   AMQ_PROTOCOL	AMQ Protocols	openwire,amqp,stomp,mqtt,hornetq	The protocols to be accepted by the broker
   AMQ_QUEUES	Queues	demoQueue	Creates an anycast queue called demoQueue
   AMQ_ADDRESSES	Addresses	demoTopic	Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
   VOLUME_CAPACITY	AMQ Volume Size	1Gi	The persistent volume size created for the journal
   AMQ_USER	AMQ Username	amq-demo-user	The username the client uses
   AMQ_PASSWORD	AMQ Password	password	The password the client uses with the username
   AMQ_TRUSTSTORE	Trust Store Filename	broker.ts	The SSL truststore file name
   AMQ_TRUSTSTORE_PASSWORD	Truststore Password	password	The password used when creating the Truststore
   AMQ_KEYSTORE	AMQ Keystore Filename	broker.ks	The SSL keystore file name
   AMQ_KEYSTORE_PASSWORD	AMQ Keystore Password	password	The password used when creating the Keystore

Procedure

1. Click StatefulSets in the OpenShift Container Platform web console.
2. Click the broker-amq deployment.
3. Click Deploy to deploy the application.

4. Click the broker Pod and then click the Logs tab to verify the state of the broker. You should see the queue created via the template.

   If the broker logs have not loaded, and the Pod status shows ErrImagePull or ImagePullBackOff, your configuration was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, edit your deployment configuration to reference the correct broker image name and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry. Then, you can import the broker image and start the broker. To do this, complete steps similar to those in Deploying and starting the broker application.

5. Click the Terminal tab to access a shell where you can use the CLI to send some messages.

   sh-4.2$ ./broker/bin/artemis producer --destination queue://demoQueue
   Producer ActiveMQQueue[demoQueue], thread=0 Started to calculate elapsed time ...
   
   Producer ActiveMQQueue[demoQueue], thread=0 Produced: 1000 messages
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in second : 4 s
   Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in milli second : 4584 milli seconds
   
   sh-4.2$ ./broker/bin/artemis consumer  --destination queue://demoQueue
   Consumer:: filter = null
   Consumer ActiveMQQueue[demoQueue], thread=0 wait until 1000 messages are consumed
   Received 1000
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumed: 1000 messages
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumer thread finished

   Alternatively, use the OpenShift client to access the shell using the Pod name, as shown in the following example.

   // Get the Pod names and internal IP Addresses
   oc get pods -o wide
   
   // Access a broker Pod by name
   oc rsh <broker-pod-name>

6. Now scale down the broker using the oc command.

   $ oc scale statefulset broker-amq --replicas=0
   statefulset "broker-amq" scaled

   You can use the console to check that the Pod count is 0

7. Now scale the broker back up to 1.

   $ oc scale statefulset broker-amq --replicas=1
   statefulset "broker-amq" scaled

8. Consume the messages again by using the terminal. For example:

   sh-4.2$ broker/bin/artemis consumer --destination queue://demoQueue
   Consumer:: filter = null
   Consumer ActiveMQQueue[demoQueue], thread=0 wait until 1000 messages are consumed
   Received 1000
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumed: 1000 messages
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumer thread finished

Procedure

1. Click Services → broker-amq-tcp-ssl.
2. Click Actions → Create a route.
3. To display the TLS parameters, select the Secure route check box.
4. From the TLS Termination drop-down menu, choose Passthrough. This selection relays all communication to AMQ Broker without the OpenShift router decrypting and resending it.

5. To view the Route, click Routes. For example:

   https://broker-amq-tcp-amq-demo.router.default.svc.cluster.local

Procedure

1. Navigate to the OpenShift web console and log in.
2. Select the amq-demo project space.
3. Click Add to Project > Browse catalog to list all of the default image streams and templates
4. Use the Filter search bar to limit the list to those that match amq. Click See all to show the desired application template.
5. Select the amq-broker-78-persistence-clustered template which is labeled Red Hat AMQ Broker 7.8 (no SSL, clustered).

6. Set the following values in the configuration and click create.

   Table 8.3. Example template

   Environment variable	Display Name	Value	Description
   AMQ_PROTOCOL	AMQ Protocols	openwire,amqp,stomp,mqtt,hornetq	The protocols to be accepted by the broker
   AMQ_QUEUES	Queues	demoQueue	Creates an anycast queue called demoQueue
   AMQ_ADDRESSES	Addresses	demoTopic	Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
   VOLUME_CAPACITY	AMQ Volume Size	1Gi	The persistent volume size created for the journal
   AMQ_CLUSTERED	Clustered	true	This needs to be true to ensure the brokers cluster
   AMQ_CLUSTER_USER	cluster user	generated	The username the brokers use to connect with each other
   AMQ_CLUSTER_PASSWORD	cluster password	generated	The password the brokers use to connect with each other
   AMQ_USER	AMQ Username	amq-demo-user	The username the client uses
   AMQ_PASSWORD	AMQ Password	password	The password the client uses with the username

Procedure

1. Click StatefulSets in the OpenShift Container Platform web console.
2. Click the broker-amq deployment.

3. Click Deploy to deploy the application.

   Note

   The default number of replicas for a clustered template is 0. You should not see any Pods.

4. Scale up the Pods to three to create a cluster of brokers.

   $ oc scale statefulset broker-amq --replicas=3
   statefulset "broker-amq" scaled

5. Check that there are three Pods running.

   $ oc get pods
   NAME           READY     STATUS    RESTARTS   AGE
   broker-amq-0   1/1       Running   0          33m
   broker-amq-1   1/1       Running   0          33m
   broker-amq-2   1/1       Running   0          29m

6. If the Pod status shows ErrImagePull or ImagePullBackOff, your deployment was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, edit your StatefulSet to reference the correct broker image name and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry. Then, you can import the broker image and start the brokers. To do this, complete steps similar to those in Deploying and starting the broker application.

7. Verify that the brokers have clustered with the new Pod by checking the logs.

   $ oc logs broker-amq-2

   This shows the logs of the new broker and an entry for a clustered bridge created between the brokers:

   2018-08-29 07:43:55,779 INFO  [org.apache.activemq.artemis.core.server] AMQ221027: Bridge ClusterConnectionBridge@1b0e9e9d [name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, queue=QueueImpl[name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, postOffice=PostOfficeImpl [server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c], temp=false]@5e0c0398 targetConnector=ServerLocatorImpl (identity=(Cluster-connection-bridge::ClusterConnectionBridge@1b0e9e9d [name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, queue=QueueImpl[name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, postOffice=PostOfficeImpl [server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c], temp=false]@5e0c0398 targetConnector=ServerLocatorImpl [initialConnectors=[TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-110], discoveryGroupConfiguration=null]]::ClusterConnectionImpl@806813022[nodeUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c, connector=TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-108, address=, server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c])) [initialConnectors=[TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-110], discoveryGroupConfiguration=null]] is connected

Procedure

1. Create a regular Service for each Pod in the cluster, using a StatefulSet selector to select between Pods. To do this, deploy a Service template, in .yaml format, that looks like the following:

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       description: 'Service for the management console of broker pod XXXX'
     labels:
       app: application2
       application: application2
       template: amq-broker-78-persistence-clustered
     name: amq2-amq-console-XXXX
     namespace: amq75-p-c-ssl-2
   spec:
     ports:
       - name: console-jolokia
         port: 8161
         protocol: TCP
         targetPort: 8161
     selector:
       deploymentConfig: application2-amq
       statefulset.kubernetes.io/pod-name: application2-amq-XXXX
     type: ClusterIP

   In the preceding template, replace XXXX with the ordinal value of the broker Pod you want to associate with the Service. For example, to associate the Service with the first Pod in the cluster, set XXXX to 0. To associate the Service with the second Pod, set XXXX to 1, and so on.

   Save and deploy an instance of the template for each broker Pod in your cluster.

   Note

   In the example template shown above, the selector uses the Kubernetes-defined Pod name.

2. Create a Route for each broker Pod, so that the AMQ Broker management console can connect to the Pod.

   Click Routes → Create Route.

   The Edit Route page opens.

   1. In the Services drop-down menu, select the previously created broker Service that you want to associate the Route with, for example, amq2-amq-console-0.
   2. Set Target Port to 8161, to enable access for the AMQ Broker management console.

   3. To display the TLS parameters, select the Secure route check box.

      1. From the TLS Termination drop-down menu, choose Passthrough.

         This selection relays all communication to AMQ Broker without the OpenShift router decrypting and resending it.

   4. Click Create.

      When you create a Route associated with one of broker Pods, the resulting .yaml file includes lines that look like the following:

      spec:
        host: amq2-amq-console-0-amq75-p-c-2.apps-ocp311.example.com
        port:
          targetPort: console-jolokia
        tls:
          termination: passthrough
        to:
          kind: Service
          name: amq2-amq-console-0
          weight: 100
        wildcardPolicy: None

3. To access the management console for a specific broker instance, copy the host URL shown above to a web browser.

Procedure

1. Navigate to the OpenShift web console and log in.
2. Select the amq-demo project space.
3. Click Add to Project > Browse catalog to list all of the default image streams and templates.
4. Use the Filter search bar to limit the list to those that match amq. Click See all to show the desired application template.
5. Select the amq-broker-78-persistence-clustered-ssl template which is labeled Red Hat AMQ Broker 7.8 (SSL, clustered).

6. Set the following values in the configuration and click create.

   Table 8.4. Example template

   Environment variable	Display Name	Value	Description
   AMQ_PROTOCOL	AMQ Protocols	openwire,amqp,stomp,mqtt,hornetq	The protocols to be accepted by the broker
   AMQ_QUEUES	Queues	demoQueue	Creates an anycast queue called demoQueue
   AMQ_ADDRESSES	Addresses	demoTopic	Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
   VOLUME_CAPACITY	AMQ Volume Size	1Gi	The persistent volume size created for the journal
   AMQ_CLUSTERED	Clustered	true	This needs to be true to ensure the brokers cluster
   AMQ_CLUSTER_USER	cluster user	generated	The username the brokers use to connect with each other
   AMQ_CLUSTER_PASSWORD	cluster password	generated	The password the brokers use to connect with each other
   AMQ_USER	AMQ Username	amq-demo-user	The username the client uses
   AMQ_PASSWORD	AMQ Password	password	The password the client uses with the username
   AMQ_TRUSTSTORE	Trust Store Filename	broker.ts	The SSL truststore file name
   AMQ_TRUSTSTORE_PASSWORD	Truststore Password	password	The password used when creating the Truststore
   AMQ_KEYSTORE	AMQ Keystore Filename	broker.ks	The SSL keystore file name
   AMQ_KEYSTORE_PASSWORD	AMQ Keystore Password	password	The password used when creating the Keystore

Procedure

1. Click StatefulSets in the OpenShift Container Platform web console.
2. Click the broker-amq deployment.

3. Click Deploy to deploy the application.

   Note

   The default number of replicas for a clustered template is 0, so you will not see any Pods.

4. Scale up the Pods to three to create a cluster of brokers.

   $ oc scale statefulset broker-amq --replicas=3
   statefulset "broker-amq" scaled

5. Check that there are three Pods running.

   $ oc get pods
   NAME           READY     STATUS    RESTARTS   AGE
   broker-amq-0   1/1       Running   0          33m
   broker-amq-1   1/1       Running   0          33m
   broker-amq-2   1/1       Running   0          29m

6. If the Pod status shows ErrImagePull or ImagePullBackOff, your deployment was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, edit your StatefulSet to reference the correct broker image name and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry. Then, you can import the broker image and start the brokers. To do this, complete steps similar to those in Deploy and start the broker application.

7. Verify the brokers have clustered with the new Pod by checking the logs.

   $ oc logs broker-amq-2

   This shows all the logs of the new broker and an entry for a clustered bridge created between the brokers, for example:

   2018-08-29 07:43:55,779 INFO  [org.apache.activemq.artemis.core.server] AMQ221027: Bridge ClusterConnectionBridge@1b0e9e9d [name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, queue=QueueImpl[name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, postOffice=PostOfficeImpl [server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c], temp=false]@5e0c0398 targetConnector=ServerLocatorImpl (identity=(Cluster-connection-bridge::ClusterConnectionBridge@1b0e9e9d [name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, queue=QueueImpl[name=$.artemis.internal.sf.my-cluster.4333c830-ab5f-11e8-afb8-0a580a82006e, postOffice=PostOfficeImpl [server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c], temp=false]@5e0c0398 targetConnector=ServerLocatorImpl [initialConnectors=[TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-110], discoveryGroupConfiguration=null]]::ClusterConnectionImpl@806813022[nodeUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c, connector=TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-108, address=, server=ActiveMQServerImpl::serverUUID=9cedb69d-ab5e-11e8-87a4-0a580a82006c])) [initialConnectors=[TransportConfiguration(name=artemis, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?port=61616&host=10-130-0-110], discoveryGroupConfiguration=null]] is connected

Procedure

1. Navigate to the OpenShift web console and log in.
2. Select the amq-demo project space.
3. Click Add to Project > Browse catalog to list all of the default image streams and templates.
4. Use the Filter search bar to limit results to those that match amq. Click See all to show the desired application template.
5. Select the amq-broker-78-custom template which is labeled Red Hat AMQ Broker 7.8(Ephemeral, no SSL).

6. In the configuration, update broker.xml with the custom configuration you would like to use. Click Create.

   Note

   Use a text editor to create the broker’s XML configuration. Then, cut and paste confguration details into the broker.xml field.

   Note

   OpenShift Container Platform does not use a ConfigMap object to store the custom configuration that you specify in the broker.xml field, as is common for many applications deployed on this platform. Instead, OpenShift temporarily stores the specified configuration in an environment variable, before transferring the configuration to a standalone file when the broker container starts.

Procedure

1. Click Deployments in the OpenShift Container Platform web console.
2. Click the broker-amq deployment
3. Click Deploy to deploy the application.

Procedure

1. Add an entry into your /etc/hosts file to map the route name onto the IP address of the OpenShift cluster:

   10.0.0.1 broker-amq-tcp-amq-demo.router.default.svc.cluster.local

2. Update the jndi.properties configuration file to use the route, truststore and keystore created previously, for example:

   connectionfactory.myFactoryLookup = amqps://broker-amq-tcp-amq-demo.router.default.svc.cluster.local:8443?transport.keyStoreLocation=<keystore-path>client.ks&transport.keyStorePassword=password&transport.trustStoreLocation=<truststore-path>/client.ts&transport.trustStorePassword=password&transport.verifyHost=false

3. Update the jndi.properties configuration file to use the queue created earlier.

   queue.myDestinationLookup = demoQueue

4. Execute the sender client to send a text message.

5. Execute the receiver client to receive the text message. You should see:

   Received message: Message Text!

Procedure

1. Choose import YAML/JSON from Add to Project drop down

2. Enter the following and click create.

   apiVersion: v1
   kind: Route
   metadata:
     labels:
       app: broker-amq
       application: broker-amq
     name: tcp-ssl
   spec:
     port:
       targetPort: ow-multi-ssl
     tls:
       termination: passthrough
     to:
       kind: Service
       name: broker-amq-headless
       weight: 100
     wildcardPolicy: Subdomain
     host: star.broker-ssl-amq-headless.amq-demo.svc

   Note

   The important configuration here is the wildcard policy of Subdomain. This allows each broker to be accessible through its own hostname.

Procedure

1. Add entries into the /etc/hosts file to map the route name onto the actual IP addresses of the brokers:

   10.0.0.1 broker-amq-0.broker-ssl-amq-headless.amq-demo.svc broker-amq-1.broker-ssl-amq-headless.amq-demo.svc broker-amq-2.broker-ssl-amq-headless.amq-demo.svc

2. Update the jndi.properties configuration file to use the route, truststore, and keystore created previously, for example:

   connectionfactory.myFactoryLookup = amqps://broker-amq-0.broker-ssl-amq-headless.amq-demo.svc:443?transport.keyStoreLocation=/home/ataylor/projects/jboss-amq-7-broker-openshift-image/client.ks&transport.keyStorePassword=password&transport.trustStoreLocation=/home/ataylor/projects/jboss-amq-7-broker-openshift-image/client.ts&transport.trustStorePassword=password&transport.verifyHost=false

3. Update the jndi.properties configuration file to use the queue created earlier.

   queue.myDestinationLookup = demoQueue

4. Execute the sender client code to send a text message.

5. Execute the receiver client code to receive the text message. You should see:

   Received message: Message Text!

Procedure

1. Choose import YAML/JSON from Add to Project drop down.

2. Enter the following and click create.

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       description: The broker's OpenWire port.
       service.alpha.openshift.io/dependencies: >-
         [{"name": "broker-amq-amqp", "kind": "Service"},{"name":
         "broker-amq-mqtt", "kind": "Service"},{"name": "broker-amq-stomp", "kind":
         "Service"}]
     creationTimestamp: '2018-08-29T14:46:33Z'
     labels:
       application: broker
       template: amq-broker-78-statefulset-clustered
     name: broker-external-tcp
     namespace: amq-demo
     resourceVersion: '2450312'
     selfLink: /api/v1/namespaces/amq-demo/services/broker-amq-tcp
     uid: 52631fa0-ab9a-11e8-9380-c280f77be0d0
   spec:
     externalTrafficPolicy: Cluster
     ports:
      -  nodePort: 30001
         port: 61616
         protocol: TCP
         targetPort: 61616
     selector:
       deploymentConfig: broker-amq
     sessionAffinity: None
     type: NodePort
   status:
     loadBalancer: {}

   Note

   The NodePort configuration is important. The NodePort is the port in which the client will access the brokers and the type is NodePort.

Procedure

1. In a terminal create a consumer and attach it to the IP address where OpenShift is running.

   artemis consumer --url tcp://<IP_ADDRESS>:30001 --message-count 100 --destination queue://demoQueue

2. Repeat step 1 twice to start another two consumers.

   Note

   You should now have three consumers load balanced across the three brokers.

3. Create a producer to send messages.

   artemis producer --url tcp://<IP_ADDRESS>:30001 --message-count 300 --destination queue://demoQueue

4. Verify each consumer receives messages.

   Consumer:: filter = null
   Consumer ActiveMQQueue[demoQueue], thread=0 wait until 100 messages are consumed
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumed: 100 messages
   Consumer ActiveMQQueue[demoQueue], thread=0 Consumer thread finished

Procedure

1. Log in to the OpenShift Container Platform web console with administrator privileges for the project that contains your broker deployment.
2. In the web console, click Home → Projects (OpenShift Container Platform 4.5 or later) or the drop-down list in the top-left corner (OpenShift Container Platform 3.11). Choose the project that contains your broker deployment.

3. To see the StatefulSets or DeploymentConfigs in your project, click:

   1. Workloads → StatefulSets or Workloads → DeploymentConfigs (OpenShift Container Platform 4.5 or later).
   2. Applications → StatefulSets or Applications → Deployments (OpenShift Container Platform 3.11).
4. Click the StatefulSet or DeploymentConfig that corresponds to your broker deployment.
5. To access the environment variables for your broker deployment, click the Environment tab.

6. Add a new environment variable, AMQ_ENABLE_METRICS_PLUGIN. Set the value of the variable to true.

   When you set the AMQ_ENABLE_METRICS_PLUGIN environment variable, OpenShift restarts each broker Pod in the StatefulSet or DeploymentConfig. When there are multiple Pods in the deployment, OpenShift restarts each Pod in turn. When each broker Pod restarts, the Prometheus plugin for that broker starts to gather broker runtime metrics.

Procedure

1. For the broker Pod whose metrics you want to access, you need to identify the Route you previously created to connect the Pod to the AMQ Broker management console. The Route name forms part of the URL needed to access the metrics.

   1. Click Networking → Routes (OpenShift Container Platform 4.5 or later) or Applications → Routes (OpenShift Container Platform 3.11).

   2. For your chosen broker Pod, identify the Route created to connect the Pod to the AMQ Broker management console. Under Hostname, note the complete URL that is shown. For example:

      http://rte-console-access-pod1.openshiftdomain

2. To access Prometheus metrics, in a web browser, enter the previously noted Route name appended with “/metrics”. For example:

   http://rte-console-access-pod1.openshiftdomain/metrics