Chapter 3. Deploying AMQ Broker on OpenShift Container Platform using the AMQ Broker Operator

Procedure

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

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

   Download of the amq-broker-operator-7.12.5-ocp-install-examples-rhel8.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.5-ocp-install-examples-rhel8.zip ~/broker/operator

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

   $ oc login -u system:admin

   Copy to Clipboard Toggle word wrap

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>

      Copy to Clipboard Toggle word wrap

   2. Or, switch to an existing project:

      $ oc project <project_name>

      Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

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

       Copy to Clipboard Toggle word wrap

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

       Copy to Clipboard Toggle word wrap

    3. Create the role binding in your project.

       $ oc create -f deploy/role_binding.yaml

       Copy to Clipboard Toggle word wrap

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

       Copy to Clipboard Toggle word wrap

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

       $ oc create -f deploy/election_role_binding.yaml

       Copy to Clipboard Toggle word wrap

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

       Copy to Clipboard Toggle word wrap
       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"`.

       Copy to Clipboard Toggle word wrap
    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

       Copy to Clipboard Toggle word wrap
       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

       Copy to Clipboard Toggle word wrap

    7. Create a cluster role binding in your project.

       $ oc create -f deploy/cluster_role_binding.yaml

       Copy to Clipboard Toggle word wrap

Procedure

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

   $ oc login -u system:admin

   Copy to Clipboard Toggle word wrap

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

   $ oc project <project_name>

   Copy to Clipboard Toggle word wrap

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.5-ocp-install-examples

   Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

   2. Deploy the address CRD.

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

      Copy to Clipboard Toggle word wrap

   3. Deploy the scaledown controller CRD.

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

      Copy to Clipboard Toggle word wrap

   4. Deploy the security CRD:

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

      Copy to Clipboard Toggle word wrap

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>

   Copy to Clipboard Toggle word wrap

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.5-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:16f1e024a05d6664858ef513d1e6558125e2144c3de2bb1980a6c6a3b8df7437

   Copy to Clipboard Toggle word wrap
   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

   Copy to Clipboard Toggle word wrap

   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}

   Copy to Clipboard Toggle word wrap

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

   Note

   The approval strategy applies only to updates between micro versions of the Operator. Automatic updates between minor Operator versions are not supported. For example, if the current Operator is version 7.11.7, an automatic update to version 7.12.x is not possible. To update between minor versions of the Operator, you must manually uninstall the current Operator and install the new Operator from the channel where Operators for that minor version are made available. For more information, see Section 6.3, “Manually upgrading the Operator using OperatorHub”.

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>

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

   2. Using the OpenShift Container Platform web console:

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

      5. Click Create ActiveMQArtemis.

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

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

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

   Copy to Clipboard Toggle word wrap

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

   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>

         Copy to Clipboard Toggle word wrap

      3. Create the CR instance.

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

         Copy to Clipboard Toggle word wrap

   2. Using the OpenShift web console:

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

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

         Copy to Clipboard Toggle word wrap

      2. Access the shell for the broker Pod.

         $ oc rsh ex-aao-ss-0

         Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
   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>

   Copy to Clipboard Toggle word wrap

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

   $ oc project <project_name>

   Copy to Clipboard Toggle word wrap

6. At the command line, apply the change:

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap