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.7.0 patches.
2. Ensure that the value of the Version drop-down list is set to 7.7.0 and the Patches tab is selected.

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

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

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

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

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

   $ oc login -u system:admin

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

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

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

   4. Create the service account in your project.

      $ oc create -f deploy/service_account.yaml

9. Specify a role name for the Operator.

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

   4. Create the role in your project.

      $ oc create -f deploy/role.yaml

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

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

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

    2. Create the role binding in your project.

       $ oc create -f deploy/role_binding.yaml

Procedure

1. In the OpenShift Container Platform web console, open the project in which you want your broker deployment.

   If you created a new project, it is currently empty. Observe that there are no Deployments, StatefulSets, Pods, Services, or Routes.

2. If you deployed an earlier version of the AMQ Broker Operator in the project, remove the main broker Custom Resource (CR) that you used to create your broker deployment. Deleting the main CR removes the existing broker deployment in the project. For example:

   oc delete -f deploy/crs/broker_v1alpha1_activemqartemis_cr.yaml.

3. If you deployed an earlier version of the AMQ Broker Operator in the project, delete this Operator instance. For example:

   $ oc delete -f deploy/operator.yaml

4. If you deployed Custom Resource Definitions (CRDs) in your OpenShift cluster for an earlier version of the AMQ Broker Operator, remove these CRDs from the cluster. For example:

   oc delete -f deploy/crds/broker_v1alpha1_activemqartemis_crd.yaml
   oc delete -f deploy/crds/broker_v1alpha1_activemqartemisaddress_crd.yaml
   oc delete -f deploy/crds/broker_v1alpha1_activemqartemisscaledown_crd.yaml

5. Deploy the CRDs that are included in the deploy/crds directory of the Operator archive that you downloaded and extracted. You must install the latest 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

6. Link the pull secret associated with the account used for authentication in the Red Hat Container Registry 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>

   Note

   In OpenShift Container Platform 4.1 or later, you can also use the web console to associate a pull secret with a project in which you want to deploy container images such as the AMQ Broker Operator. To do this, click Administration → Service Accounts. Specify the pull secret associated with the account that you use for authentication in the Red Hat Container Registry.

7. 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 is set to the latest Operator image for AMQ Broker 7.7, as shown below.

   spec:
       template:
           spec:
               containers:
                   image: registry.redhat.io/amq7/amq-broker-rhel7-operator:0.17

8. Deploy the Operator.

   $ oc create -f deploy/operator.yaml

   In your OpenShift project, the amq-broker-operator image that you deployed starts in a new Pod.

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

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

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

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

Procedure

1. In your web browser, navigate to the AMQ Broker Software Downloads page.
2. In the Version drop-down box, ensure the value is set to the latest AMQ Broker version, 7.7.0.
3. Click the Patches tab.

4. Next to AMQ Broker 7.7.0 Operator Installation and Example Files, click Download.

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

5. 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.7.0-ocp-install-examples.zip ~/broker/operator

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

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

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

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

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

   $ oc login -u system:admin

9. Install the Operator in OperatorHub.

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

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

Procedure

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

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

   Note

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

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

6. On the Install Operator page:

   1. Under Update Channel, ensure that the radio button entitled current is selected. This option specifies the channel used to track and receive updates for the Operator. The current value specifies that the AMQ Broker 7.7 channel is used.
   2. Under Installation Mode, ensure that the radio button entitled A specific namespace on the cluster is selected.
   3. From the Installed Namespace drop-down menu, select the project in which you want to install the Operator.
   4. Under Approval Strategy, ensure that the radio button entitled Automatic is selected. This option specifies that updates to the Operator do not require manual approval for installation to take place.
   5. Click Install.

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

   1. Using the OpenShift command-line interface:

      1. Log in to OpenShift with administrator privileges for 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 with administrator privileges for 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, the configuration might resemble that shown below. This configuration is the default content of the broker_activemqartemis_cr.yaml sample CR.

   apiVersion: broker.amq.io/v2alpha3
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
     application: ex-aao-app
   spec:
       version: 7.7.0
       deploymentPlan:
           size: 2
           image: registry.redhat.io/amq7/amq-broker:7.7
           ...

   Note

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

2. The size value specifies the number of brokers to deploy. The default value of 2 specifies a clustered broker deployment of two brokers. However, to deploy a single broker instance, change the value to 1.

3. The image value specifies the container image to use to launch the broker. Ensure that this value specifies the latest version of the AMQ Broker 7.7 broker container image in the Red Hat Container Registry, as shown below.

   image: registry.redhat.io/amq7/amq-broker:7.7

   Note

   In the preceding step, the image attribute specifies a floating image tag (that is, 7.7) rather than a full image tag (for example, 7.7-2). When you specify this floating tag, your deployment uses the latest image available in the 7.7 image stream. In addition, when you specify a floating tag such as this, if the imagePullPolicy attribute in your Stateful Set is set to Always, your deployment automatically pulls and uses new micro image versions (for example, 7.7-3, 7-7-4, and so on) when they become available in the Red Hat Container Registry.

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.

         $ oc create -f <path/to/custom-resource-instance>.yaml

   2. Using the OpenShift Container Platform web console:

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

5. In the OpenShift Container Platform web console, click Workloads → Stateful Sets (OpenShift Container Platform 4.1 or later) or Applications → Stateful Sets (OpenShift Container Platform 3.11). You see a new Stateful Set called ex-aao-ss.

   Expand the ex-aao-ss Stateful Set section. You see that there is one Pod, corresponding to the single broker that you defined in the CR.

   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.

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/v2alpha3
   kind: ActiveMQArtemis
   metadata:
     name: ex-aao
     application: ex-aao-app
   spec:
       version: 7.7.0
       deploymentPlan:
           size: 4
           image: registry.redhat.io/amq7/amq-broker:7.7
           ...

   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 with administrator privileges for 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