Chapter 2. Deploying AMQ Broker on OpenShift Container Platform using an Operator

Procedure

1. In your web browser, navigate to the AMQ Broker 7.5.0 Software Downloads page.

2. Click Download next to the Operator archive file that you want to install. Choose an archive file based on the information in the following table.

   Platform	Download title	Compressed archive file name
   OpenShift Container Platform	AMQ Broker 7.5 Operator Installation Files	amq-broker-operator-7.5.0-ocp-install-examples.zip
   OpenShift Container Platform on IBM Z	AMQ Broker 7.5 Operator Installation Files for IBM zSeries	amq-broker-operator-7.5.0-Z-ocp-install-examples.zip

3. When the download is complete, move the archive to your chosen installation directory.

   This example moves the OpenShift Container Platform Operator archive to a directory called ~/broker/operator.

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

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

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

5. Log in to OpenShift Container Platform as a cluster administrator.

   $ oc login -u system:admin

6. Create or log in to the project in which you want to install the Operator.

   $ oc new-project <project_name>

   or

   $ oc project <project_name>

7. 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. Set the kind element to ServiceAccount.
   3. In the metadata section, assign a name to the service account. The default name is amq-broker-operator.

8. 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. Set the kind element to Role.
   3. In the metadata section, assign a name to the role. The default name is amq-broker-operator.

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

   Open the role_binding.yaml file. Add lines that look like the following:

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

Procedure

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

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

2. Prepare the project to receive the operator.

   1. Create the service account.

      $ oc create -f deploy/service_account.yaml

   2. Create the role.

      $ oc create -f deploy/role.yaml

   3. Create the role binding.

      $ oc create -f deploy/role_binding.yaml

   4. Deploy the broker CRD to the OpenShift cluster.

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

      Note

      You must install the CRDs before deploying and starting the Operator. If not, the Operator logs will show messages instructing you to do so.

   5. Deploy the addressing CRD.

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

   6. Deploy the scaledown CRD.

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

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

4. In the deploy directory of the Operator archive that you downloaded and extracted, open the operator.yaml file. Update spec.containers.image with the full path to the latest Operator image for AMQ Broker 7.5 in the Red Hat Container Registry.

   Specify the Operator image name for your platform, based on the information in the following table.

   Platform	Repository name	Latest version tag
   OpenShift Container Platform	amq7/amq-broker-rhel7-operator	0.9
   OpenShift Container Platform on IBM Z	amq7/amq-broker-rhel8-operator	0.10

   For example, to deploy the Operator for OpenShift Container Platform, specify the latest version tag for the Operator container image in the amq7/amq-broker-rhel7-operator repository, as shown below.

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

5. 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 includes line like 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 the deploy/crs directory of the Operator archive that you downloaded and extracted, open the broker_v2alpha1_activemqartemis_cr.yaml Custom Resource file.
2. For a minimally-sized clustered deployment, ensure that the value of deploymentPlan.size is 2.

3. At the command line, apply the change:

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

   In the OpenShift Container Platform web console, a second Pod starts in your project, for the additional broker that you specified in your CR. By default, the two brokers running in your project are clustered.

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

Procedure

1. Deploy the addressing CRD.

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

2. An example CR file, broker_v2alpha1_activemqartemisaddress_cr.yaml, was included in the Operator archive that you downloaded and extracted. The example Custom Resource includes the following:

   spec:
     # Add fields here
     spec:
       addressName: myAddress0
       queueName: myQueue0
       routingType: anycast

   With your broker cluster already already deployed and running via the Operator, use the example Custom Resource to create an address on every running broker in your cluster.

   $ oc create -f deploy/crs/broker_v2alpha1_activemqartemisaddress_cr.yaml

   Deploying the example CR creates an address myAddress0 with a queue named myQueue0 that has an anycast routing type. This address is created on every running broker.

   Note

   To create multiple addresses and/or queues in your broker cluster, you need to create separate CR files and deploy them individually, specifying new address and/or queue names in each case.

   Note

   If you add brokers to your cluster after deploying the addressing CR, the new brokers will not have the address you previously created. In this case, you need to delete the addresses and redeploy the addressing CR.

3. To delete queues created from the example CR, use the following command:

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

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 Broker version, 7.5.0.

3. Next to AMQ Broker 7.5 Operator Installation Files, click Download.

   Download of the amq-broker-operator-7.5.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.

   sudo mv amq-broker-operator-7.5.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.5.0-ocp-install-examples.zip

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

   $ oc login -u system:admin

7. Deploy the AMQ Broker Operator source bundle from the deploy directory of the Operator archive that you downloaded and extracted.

   $ oc create -f deploy/catalog_resources/courier/amq-broker-operatorsource.yaml

   After a few minutes, the AMQ Broker Operator is available in the OperatorHub section of the OpenShift Container Platform web console. You can then use the OperatorHub graphical interface to create various types of broker deployments.