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

Procedure

1. In your web browser, navigate to the AMQ Broker Software Downloads page.
2. In the Version drop-down box, ensure that the value is set to the latest Broker version, 7.6.0.

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

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

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

   cd /broker/operator
   sudo unzip amq-broker-operator-7.6.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) from the project. 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 addressing 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. Update spec.containers.image with the full path to the latest Operator image for AMQ Broker 7.6 in the Red Hat Container Registry.

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

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

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

   Download of the amq-broker-operator-7.6.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.6.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.6.0-ocp-install-examples.zip

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

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

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

   $ oc login -u system:admin

8. Install the Operator in OperatorHub.

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

Procedure

1. From the Projects drop-down menu in the OpenShift Container Platform web console, select the project in which you want to install the AMQ Broker Operator.
2. In the web console, click Operators → OperatorHub.

3. In OperatorHub, click the AMQ Broker Operator.

   If more than one instance of the AMQ Broker Operator is installed in OperatorHub, click each instance and review the information pane that opens. The major version of the latest Operator for AMQ Broker 7.6 is 0.13.

4. To install the Operator, click Install.

5. On the Operator Subscription page:

   1. Under Installation Mode, ensure that the radio button entitled A specific namespace on the cluster is selected. From the drop-down menu, select the project in which you want to install the AMQ Broker Operator.
   2. Under Update Channel, ensure that the radio button entitled current-76 is selected. This option specifies the channel used to track and receive updates for the Operator. The current-76 value specifies that the AMQ Broker 7.6 channel is used.
   3. 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.
   4. Click Subscribe.

Procedure

1. In the deploy/crs directory of the Operator archive that you downloaded and extracted during your initial installation, open the broker_activemqartemis_cr.yaml Custom Resource (CR).

2. In the acceptors element, add a named acceptor. Typically, you also specify a minimal set of attributes such as the protocols to be used by the acceptor and the port on the broker Pod to expose for those protocols. An example is shown below.

   spec:
   ...
     acceptors:
     - name: amqp_acceptor
       protocols: amqp
       port: 5672
       sslEnabled: false
   ...

   The preceding example shows configuration of a simple AMQP acceptor. The acceptor exposes port 5672 to AMQP clients.

Procedure

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

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

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

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

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

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

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

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

5. Use the broker keystore file to create a secret to store the SSL credentials, as shown in the example below.

   $ oc secrets new amq-app-secret broker.ks client.ts

6. Add the secret to the service account that you created when installing the Operator, as shown in the example below.

   $ oc secrets add sa/amq-broker-operator secret/amq-app-secret

Procedure

1. In the deploy/crs directory of the Operator archive that you downloaded and extracted, open the broker_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_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_activemqartemisaddress_crd.yaml

2. An example CR file, broker_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_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_activemqartemisaddress_cr.yaml