Deploying AMQ Broker on OpenShift

Procedure

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

3. Next to the latest AMQ Broker 7.12.3 Operator Installation and Example Files, click Download.

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

4. Move the archive to your chosen directory. The following example moves the archive to a directory called ~/broker/operator.

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

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

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

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

   $ cd amq-broker-operator-7.12.3-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. If you want to change the default service account name, in the metadata section, replace amq-broker-controller-manager with a custom name.

   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. If you want to change the default role name, in the metadata section, replace amq-broker-operator-role with a custom name.

    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.

    2. 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-rolebinding
       subjects:
           kind: ServiceAccount
           name: amq-broker-controller-manager
       roleRef:
           kind: Role
           name: amq-broker-operator-role

    3. Create the role binding in your project.

       $ oc create -f deploy/role_binding.yaml

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

    1. Create a leader election role for the Operator.

       $ oc create -f deploy/election_role.yaml

    2. Create the leader election role binding in your project.

       $ oc create -f deploy/election_role_binding.yaml

13. (Optional) If you want the Operator to watch multiple namespaces, complete the following steps:

    Note

    If the OpenShift Container Platform cluster already contains installed Operators for AMQ Broker, you must ensure the new Operator does not watch any of the same namespaces as existing Operators. For information on how to identify the namespaces that are watched by existing Operators, see, Identifying namespaces watched by existing Operators.

    1. In the deploy directory of the Operator archive that you downloaded and extracted, open the operator_yaml file.

    2. If you want the Operator to watch all namespaces in the cluster, in the WATCH_NAMESPACE section, add a value attribute and set the value to an asterisk. Comment out the existing attributes in the WATCH_NAMESPACE section. For example:

       - name: WATCH_NAMESPACE
         value: "*"
       # valueFrom:
       #   fieldRef:
       #     fieldPath: metadata.namespace

       Note

       To avoid conflicts, ensure that multiple Operators do not watch the same namespace. For example, if you deploy an Operator to watch all namespaces on the cluster, you cannot deploy another Operator to watch individual namespaces. If Operators are already deployed on the cluster, you can specify a list of namespaces that the new Operator watches, as described in the following step.

    3. If you want the Operator to watch multiple, but not all, namespaces on the cluster, in the WATCH_NAMESPACE section, specify a list of namespaces. Ensure that you exclude any namespaces that are watched by existing Operators. For example:

       - name: WATCH_NAMESPACE
         value: "namespace1, namespace2"`.

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

    5. In the Subjects section, specify a namespace that corresponds to the OpenShift Container Platform project to which you are deploying the Operator. For example:

       Subjects:
       - kind: ServiceAccount
         name: amq-broker-controller-manager
         namespace: operator-project

       Note

       If you previously deployed brokers using an earlier version of the Operator, and you want to deploy the Operator to watch multiple namespaces, see Before you upgrade.

    6. Create a cluster role in your project.

       $ oc create -f deploy/cluster_role.yaml

    7. Create a cluster role binding in your project.

       $ oc create -f deploy/cluster_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.12.3-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

   4. Deploy the security CRD:

      $ oc create -f deploy/crds/broker_activemqartemissecurity_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. Ensure that the value of the spec.containers.image property corresponds to version 7.12.3-opr-1 of the Operator, as shown below.

   spec:
       template:
           spec:
               containers:
                   #image: registry.redhat.io/amq7/amq-broker-rhel8-operator:7.10
                   image: registry.redhat.io/amq7/amq-broker-rhel8-operator@sha256:1fd01079ad519e1a47b886893a0635491759ace2f73eda7615a9c8c2f454ba89

   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. 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 for RHEL 8 (Multiarch) 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 for RHEL 8 (Multiarch) Operator. When you click this Operator, review the information pane that opens. For AMQ Broker 7.12, the latest minor version tag of this Operator is 7.12.3-opr-1.

5. Click the Red Hat Integration - AMQ Broker for RHEL 8 (Multiarch) Operator. On the dialog box that appears, click Install.

6. On the Install Operator page:

   1. Under Update Channel, select the 7.11.x channel to receive updates for version 7.11 only. The 7.11.x channel is a Long Term Support (LTS) channel.

      Depending on when your OpenShift Container Platform cluster was installed, you may also see channels for older versions of AMQ Broker. The only other supported channel is 7.10.x, which is also an LTS channel.

   2. Under Installation Mode, choose which namespaces the Operator watches:

      • A specific namespace on the cluster - The Operator is installed in that namespace and only monitors that namespace for CR changes.
      • All namespaces - The Operator monitors all namespaces for CR changes.
      Note

      If you previously deployed brokers using an earlier version of the Operator, and you want deploy the Operator to watch many namespaces, see Before you upgrade.

7. From the Installed Namespace drop-down menu, select the project in which you want to install the Operator.
8. 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.
9. 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.

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

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

   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. 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.
      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/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
   spec:
     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. Edit the ActiveMQArtemis CR instance for your broker deployment.

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

   spec:
     ...
     brokerProperties:
     ...

3. Configure an address in the format:

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

   For example:

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

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

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

   Important

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

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

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

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

   For example:

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

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

Procedure

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

   1. Using the OpenShift command-line interface:

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

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

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

   2. Using the OpenShift Container Platform web console:

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

      5. Click Create ActiveMQArtemisAddress.

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

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

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

   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 finish configuring the CR, click Create.

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

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

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

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

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

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

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

     For example:

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

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

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

     In the preceding example, the following addresses are matched:

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

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

     Note

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

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

Procedure

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

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

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

7. Click the YAML tab.

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

   Note

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

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

      spec:
        ...
        addressSettings:
          addressSetting:

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

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

      match

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

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

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

      deadLetterAddress

      Address to which the broker sends undelivered messages.

      maxDeliveryAttempts

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

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

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

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

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

      Note

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

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

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

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

      merge_all

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

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

      merge_replace

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

      replace_all

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

      Note

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

   6. Save the CR instance.

Procedure

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

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

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

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

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

4. Save the CR.

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

Procedure

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

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

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

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

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

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

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

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

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

Procedure

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

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

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

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

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

     Note

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

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

   new-users.properties

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

   new-roles.properties

   admin=ruben, rick
   group1=bob
   group2=anne

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

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

   Note

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

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

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

   1. Using the OpenShift command-line interface:

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

      2. Edit the CR for your deployment.

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

   2. Using the OpenShift Container Platform web console:

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

      6. Click the YAML tab.

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

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

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

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

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

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

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

      Note

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

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

7. Save the CR.

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

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

   1. Using the OpenShift command-line interface:

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

         $ oc get activemqartemis -o yaml

   2. Using the OpenShift web console:

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

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

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

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

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

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

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

Procedure

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

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

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

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

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

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

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

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

4. Save the CR.

Procedure

1. Edit the ActiveMQArtemis CR for your broker deployment.

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

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

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

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

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

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

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

5. Save the CR.

Procedure

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

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

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

3. Save the CR.

Procedure

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

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

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

   storeConfiguration

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

   storeConfiguration.jdbcDriverClassName

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

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

   storeConfiguration.jdbcConnectionUrl

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

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

   In the example, the database name is postgres.

   HAPolicyConfiguration

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

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

   storeConfiguration.jdbcNetworkTimeout

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

   storeConfiguration.jdbcLockRenewPeriod

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

   storeConfiguration.jdbcLockExpiration

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

   storeConfiguration.jdbcJournalSyncPeriod

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

   storeConfiguration.jdbcMaxPageSizeBytes

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

4. Save the CR.

Procedure

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

   1. Using the OpenShift command-line interface:

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

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

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

   2. Using the OpenShift Container Platform web console:

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

      5. Click Create ActiveMQArtemis.

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

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

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

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

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

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

   storage.size

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

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

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

   storage.storageClassName

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

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

   Note

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

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

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

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

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

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

   limits.cpu

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

   limits.memory

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

   requests.cpu

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

   requests.memory

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

   Note

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

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

   Important

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

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

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

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

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

   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 attribute. Specify a comma-separated list of protocols. For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        Note

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Procedure

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

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

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

      2. Edit the CR for your deployment.

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

   2. Using the OpenShift Container Platform web console:

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

      6. Click the YAML tab.

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

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

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

   command

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

   initialDelaySeconds

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

   periodSeconds

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

   timeoutSeconds

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

   failureThreshold

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

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

3. Save the CR.

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

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

      2. Edit the CR for your deployment.

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

   2. Using the OpenShift Container Platform web console:

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

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

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

   initialDelaySeconds

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

   Note

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

   periodSeconds

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

   failureThreshold

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

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

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

   Note

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

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

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

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

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

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

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

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

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

      Note

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

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

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

      Note

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

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

5. Save the CR.

1. When a broker Pod in the deployment shuts down due to an intentional scaledown of the deployment, the Operator automatically deploys a scaledown Custom Resource to prepare for message migration.

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

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

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

Procedure

1. Edit the CR instance for the broker deployment.

   1. Using the OpenShift command-line interface:

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

      2. Edit the CR for your deployment.

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

   2. Using the OpenShift Container Platform web console:

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

      6. Click the YAML tab.

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

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

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

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

3. Save the CR.

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

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

      $ oc get pods

      You see output that looks like the following.

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

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

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

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

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

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

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

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

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

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

      3. At the command line, apply the change:

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

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

   5. When the drainer Pod is shut down, check the message count on the TEST queue of broker 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. Create a Custom Resource (CR) instance based on the main broker CRD.

   1. Using the OpenShift command-line interface:

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

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

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

   2. Using the OpenShift Container Platform web console:

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

      5. Click Create ActiveMQArtemis.

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

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

   spec:
       deploymentPlan:
         nodeSelector:
           app: broker1

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

3. Deploy the CR instance.

   1. Using the OpenShift command-line interface:

      1. Save the CR file.

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

         $ oc project <project_name>

      3. Create the CR instance.

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

   2. Using the OpenShift web console:

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

Procedure

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

   1. Using the OpenShift command-line interface:

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

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

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

   2. Using the OpenShift Container Platform web console:

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

      5. Click Create ActiveMQArtemis.

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

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

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

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

1. Deploy the CR instance.

   1. Using the OpenShift command-line interface:

      1. Save the CR file.

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

         $ oc project <project_name>

      3. Create the CR instance.

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

   2. Using the OpenShift web console:

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

Procedure

1. Create a file in Java properties format that contains the brokerProperties configuration that you want to apply to the broker. Add each property in a separate line in the properties file. For example:

   securityRoles.address1.group2.send=true
   securityRoles.address2.group1.consume=true
   securityRoles.address2.group2.createAddress=true

2. Save the file with a .properties extension, for example, securityRoles.properties.

3. Create a secret that contains the .properties file you created.

   oc create secret generic address-settings-bp --from-file=securityRoles.properties

   Note

   The secret name must have a suffix of -bp. When a secret has a -bp suffix, the Operator configures the broker to search for properties files in the directory where the secret is mounted on the broker pod.

4. Add a reference to the secret in the extraMounts attribute so the Operator mounts the properties files that are in the secret on each broker pod:

   deploymentPlan:
     ...
     extraMounts:
       secrets:
       - "address-settings-bp"
     ...

   The Operator mounts the .properties files that are in the secret in a /amq/extra/secrets/<secret name> directory on each broker pod.

   At startup, the broker searches each mounted directory for files that have a .properties extension, sorts the files alphabetically, and applies the configuration in the files one after another. Within a properties file, the broker applies the properties in the order in which they are listed.

Procedure

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

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

   Download of the amq-broker-operator-7.12.3-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.12.3-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-operator-7.12.3-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. In the new operator.yaml file, the Operator is named amq-broker-controller-manager by default. If the name of the Operator in your previous deployment is not amq-broker-controller-manager, replace all instances of amq-broker-controller-manager with the previous Operator name. For example:

    spec:
      ...
      selector
        matchLabels
          name: amq-broker-operator
      ...

11. In the new operator.yaml file, the service account for the Operator is named amq-broker-controller-manager. In previous versions, the service account for the Operator was named amq-broker-operator.

    1. If you want to use the service account name in your previous deployment, replace the name of the service account in the new operator.yaml file with the name used in the previous deployment. For example:

       spec:
         ...
         serviceAccountName: amq-broker-operator
         ...

    2. If you want to use the new service account name, amq-broker-controller-manager for the Operator, update the service account, role, and role binding in your project.

       $ oc apply -f deploy/service_account.yaml

       $ oc apply -f deploy/role.yaml

       $ oc apply -f deploy/role_binding.yaml

12. Update the CRDs that are included with the Operator.

    1. Update the main broker CRD.

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

    2. Update the address CRD.

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

    3. Update the scaledown controller CRD.

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

    4. Update the security CRD.

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

13. If you are upgrading from AMQ Broker Operator 7.10.0 only, delete the Operator and the StatefulSet.

    By default, the new Operator deletes the StatefulSet to remove custom and Operator metering labels, which were incorrectly added to the StatefulSet selector by the Operator in 7.10.0. When the Operator deletes the StatefulSet, it also deletes the existing broker pods, which causes a temporary broker outage. If you want to avoid an outage, complete the following steps to delete the Operator and the StatefulSet without deleting the broker pods.

    1. Delete the Operator.

       $ oc delete -f deploy/operator.yaml

    2. Delete the StatefulSet with the --cascade=orphan option to orphan the broker pods. The orphaned broker pods continue to run after the StatefulSet is deleted.

       $ oc delete statefulset <statefulset-name> --cascade=orphan

14. If you are upgrading from AMQ Broker Operator 7.10.0 or 7.10.1, check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

    These labels are reserved for the Operator to assign labels to pods and are not permitted as custom labels after 7.10.1. If these custom labels were configured in the main broker CR, the Operator-assigned labels on the pods were overwritten by the custom labels. If either of these custom labels are configured in the main broker CR, complete the following steps to restore the correct labels on the pods and remove the labels from the CR.

    1. If you are upgrading from 7.10.0, you deleted the Operator in the previous step. If you are upgrading from 7.10.1, delete the Operator.

       $ oc delete -f deploy/operator.yaml

    2. Run the following command to restore the correct pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

       $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*'); do oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

    3. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

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

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

       2. Open the sample CR file called broker_activemqartemis_cr.yaml that was included in the deploy/crs directory of the Operator installation archive that you downloaded and extracted.
       3. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
       4. Save the CR file.

       5. Deploy the CR instance.

          1. Switch to the project for the broker deployment.

             $ oc project <project_name>

          2. Apply the CR.

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

    4. If you deleted the previous Operator, deploy the new Operator.

        $ oc create -f deploy/operator.yaml

15. Apply the updated Operator configuration.

    $ oc apply -f deploy/operator.yaml

16. The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding images when the Operator starts. For more information, see Section 6.4, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

    Note

    If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

17. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

Procedure

1. Log in to the OpenShift Container Platform web console as a cluster administrator.
2. Uninstall the existing AMQ Broker Operator from your project.
3. In the left navigation menu, click Operators → Installed Operators.
4. From the Project drop-down menu at the top of the page, select the project in which you want to uninstall the Operator.
5. Locate the Red Hat Integration - AMQ Broker instance that you want to uninstall.
6. For your Operator instance, click the More Options icon (three vertical dots) on the right-hand side. Select Uninstall Operator.
7. On the confirmation dialog box, click Uninstall.

8. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.12. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding container images when the Operator starts. For more information, see Section 6.4, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

Procedure

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

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

3. When you upgrade a 7.10.0 Operator, the new Operator deletes the StatefulSet to remove custom and Operator metering labels, which were incorrectly added to the StatefulSet selector by the Operator in 7.10.0. When the Operator deletes the StatefulSet, it also deletes the existing broker pods, which causes a temporary broker outage. If you want to avoid the outage, complete the following steps to delete the StatefulSet and orphan the broker pods so that they continue to run.

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

      $ oc login -u <user>

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

      $ oc project <project-name>

   3. Delete the StatefulSet with the --cascade=orphan option to orphan the broker pods. The orphaned broker pods continue to run after the StatefulSet is deleted.

      $ oc delete statefulset <statefulset-name> --cascade=orphan

4. Check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

   In 7.10.0, it was possible to configure these custom labels in the CR. These labels are reserved for the Operator to assign labels to pods and cannot be added as custom labels after 7.10.0. If these custom labels were configured in the main broker CR in 7.10.0, the Operator-assigned labels on the pods were overwritten by the custom labels. If the CR has either of these labels, complete the following steps to restore the correct labels on the pods and remove the labels from the CR.

   1. In the OpenShift command-line interface (CLI), run the following command to restore the correct pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

      $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*'); do oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

   2. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

      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. Edit the CR for your deployment.

            oc edit ActiveMQArtemis <statefulset name> -n <namespace>

         3. In the deploymentPlan.labels element in the CR, delete any custom labels called application or ActiveMQArtemis.
         4. Save the CR.

      2. Using the OpenShift Container Platform web console:

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

         6. Click the YAML tab.

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

         7. In the deploymentPlan.labels element in the CR, delete any custom labels called application or ActiveMQArtemis.
         8. Click Save.

5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.12. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding images when the Operator starts. For more information, see Section 6.4, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

6. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

Procedure

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

2. Check if your main broker CR has labels called application or ActiveMQArtemis configured in the deploymentPlan.labels attribute.

   These labels are reserved for the Operator to assign labels to pods and cannot be used after 7.10.1. If these custom labels were configured in the main broker CR, the Operator-assigned labels on the pods were overwritten by the custom labels.

3. If these custom labels are not configured in the main broker CR, use OperatorHub to install the latest version of the Operator for AMQ Broker 7.12. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

4. If either of these custom labels are configured in the main broker CR, complete the following steps to uninstall the existing Operator, restore the correct pod labels and remove the labels from the CR, before you install the new Operator.

   Note

   By uninstalling the Operator, you can remove the custom labels without the Operator deleting the StatefulSet, which also deletes the existing broker pods and causes a temporary broker outage.

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

   2. In the OpenShift command-line interface (CLI), run the following command to restore the correct pod labels. In the following example, 'ex-aao' is the name of the StatefulSet deployed.

      $ for pod in $(oc get pods | grep -o '^ex-aao[^ ]*'); do oc label --overwrite pods $pod ActiveMQArtemis=ex-aao application=ex-aao-app; done

   3. Delete the application and ActiveMQArtemis labels from the deploymentPlan.labels attribute in the CR.

      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. Edit the CR for your deployment.

            oc edit ActiveMQArtemis <statefulset name> -n <namespace>

         3. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
         4. Save the CR file.

      2. Using the OpenShift Container Platform web console:

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

         6. Click the YAML tab.

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

         7. In the deploymentPlan.labels attribute in the CR, delete any custom labels called application or ActiveMQArtemis.
         8. Click Save.

5. Use OperatorHub to install the latest version of the Operator for AMQ Broker 7.12. For more information, see Section 3.3.2, “Deploying the Operator from OperatorHub”.

   The new Operator can recognize and manage your previous broker deployments. If you set values in the image or version field in the CR, the Operator’s reconciliation process upgrades the broker pods to the corresponding images when the Operator starts. For more information, see Section 6.4, “Restricting automatic upgrades of broker container images”. Otherwise, the Operator upgrades each broker pod to the latest container image.

   Note

   If the reconciliation process does not start, you can start the process by scaling the deployment. For more information, see Section 3.4.1, “Deploying a basic broker instance”.

6. Add attributes to the CR for the new features that are available in the upgraded broker, as required.

Procedure

1. Edit the main broker 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 edit and deploy CRs in the project for the broker deployment.

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

      2. Edit the CR.

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

   2. Using the OpenShift Container Platform web console:

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

      6. Click the YAML tab.

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

         Note

         In the status section of the CR, the .status.version.brokerVersion field shows the version of AMQ Broker that is currently deployed.

2. In the spec.version attribute, specify the version to which the Operator can upgrade the broker and init container images in your deployment. The following are examples of values that you can specify.

   Examples

   In the following example, the Operator upgrades the current container images in your deployment to 7.12.0.

   spec:
      version: '7.12.0'
       ...

   In the following example, the Operator upgrades the current container images in your deployment to the latest available 7.11.x images. For example, if your deployment is using 7.11.1 container images, the Operator automatically upgrades the images to 7.11.6 but not to 7.12.3.

   spec:
       version: '7.11'
       ...

   In the following example, the Operator upgrades the current container images in your deployment to the latest 7.x.x images. For example, if your deployment is using 7.11.6 images, the Operator automatically upgrades the images to 7.12.3.

   spec:
       version: '7'
       ...

   Note

   To upgrade between minor versions of the container images, for example, from 7.11.x to 7.12.x, you require an Operator that has the same minor version as that of the new container images. For example, to upgrade from 7.11.6 to 7.12.3, a 7.12.x Operator must be installed.

3. Save the CR.

Procedure

1. Obtain the URLs of the broker and init container images to which the Operator can upgrade the current images.

   1. In the Red Hat Catalog, open the broker container component page: AMQ Broker for RHEL 8 (Multiarch).
   2. In the Architecture drop-down, select your architecture.
   3. In the Tag drop-down, select the tag that corresponds to the image you want to install. Tags are displayed in chronological order based on the release date. A tag consists of the release version and an assigned tag.
   4. Open the Get this image tab.
   5. In the Manifest field, click the Copy icon.
   6. Paste the URL into a text file.
   7. In the Red Hat Catalog, open the init container component page: AMQ Broker Init for RHEL 8 (Multiarch)
   8. To obtain the URL of the init container image, repeat the steps that you followed to obtain the URL of the broker container image.

2. Edit the main broker 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 edit and deploy CRs in the project for the broker deployment.

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

      2. Edit the CR.

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

   2. Using the OpenShift Container Platform web console:

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

      6. Click the YAML tab.

         Within the console, a YAML editor opens, which enables you to configure the CR instance

   3. Copy the URLs of the broker and init container images that you recorded in the text file and insert them in the spec.deploymentPlan.image and spec.deploymentPlan.initImage fields in the CR. For example:

      spec:
        ...
        deploymentPlan:
          image: registry.redhat.io/amq7/amq-broker-rhel8@55ae4e28b100534d63c34ab86f69230d274c999d46d1493f26fe3e75ba7a0cec
          initImage: registry.redhat.io/amq7/amq-broker-init-rhel8@442339c33549f2be9fe3b5c71184a753a3cf10b000b2ecc5bc9a062dd91c8def
        ...

3. Save the CR.

   When you save the CR, the Operator upgrades the brokers to use the new images and uses these images until you update the values of the spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes again.

4. If you want to prevent future Operator upgrades from restarting the brokers in your deployment, edit the CR and and specify the version number of the brokers that are deployed in the spec.version attribute.

   If the spec.version attribute is not configured in the CR, subsequent upgrades of the Operator cause the broker pods to restart. The pod restart is required because the new Operator adds the latest supported broker version to a label in the StatefulSet unless a version number is explicitly set in the spec.version attribute.

   You can find the version number value to specify for the spec.version attribute in the status section of the CR after the brokers start. For more information, see Viewing status information for your broker deployment.

Procedure

1. Open the CR instance that you use for your broker deployment. For example, the CR for a basic deployment might resemble the following:

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
   spec:
     deploymentPlan:
       size: 4
       image: registry.redhat.io/amq7/amq-broker-rhel8:7.12
     ...

2. In the deploymentPlan section, add the enableMetricsPlugin property and set the value to true, as shown below.

   apiVersion: broker.amq.io/v1beta1
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
   spec:
     deploymentPlan:
       size: 4
       image: registry.redhat.io/amq7/amq-broker-rhel8:7.12
       ...
       enableMetricsPlugin: true

   enableMetricsPlugin

   Specifies whether the Prometheus plugin is enabled for the brokers in the deployment.

3. Save the CR instance.

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

   $ oc project <project_name>

5. At the command line, apply the change.

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

   The metrics plugin starts to gather broker runtime metrics in Prometheus format.

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. Choose the project that contains your broker deployment.
3. To see the StatefulSets or DeploymentConfigs in your project, click Workloads → StatefulSets or Workloads → DeploymentConfigs.
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.

   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