Chapter 3. Deploying AMQ Broker on OpenShift Container Platform using Application Templates
The procedures in this section show how to prepare a broker deployment and an example of using the OpenShift Container Platform web console to deploy a basic broker instance. For examples of deploying other broker configurations, see Tutorials.
The following procedures assume that the broker image and application templates you installed in Installing AMQ Broker on OpenShift Container Platform are available in the global openshift
project. If you installed the image and application templates in a specific project namespace, then continue to use that project instead of creating a new project such as amq-demo
.
3.1. Installing the AMQ Broker image streams and application templates
The AMQ Broker on OpenShift Container Platform image streams and application templates are not available in OpenShift Container Platform by default. You must manually install them using the procedure in this section. When you have completed the manual installation, you can then instantiate a template that enables you to deploy a chosen broker configuration on your OpenShift cluster. For examples of creating various broker configurations in this way, see Deploying AMQ Broker on OpenShift Container Platform and Tutorials.
Procedure
At the command line, log in to OpenShift as a cluster administrator (or as a user that has namespace-specific administrator access for the global
openshift
project namespace), for example:$ oc login -u system:admin $ oc project openshift
Using the
openshift
project makes the image stream and application templates that you install later in this procedure globally available to all projects in your OpenShift cluster. If you want to explicitly specify that image streams and application templates are imported to theopenshift
project, you can also add-n openshift
as an optional parameter with theoc replace
commands that you use later in the procedure.As an alternative to using the
openshift
project (e.g., if a cluster administrator is unavailable), you can log in to a specific OpenShift project to which you have administrator access and in which you want to create a broker deployment, for example:$ oc login -u <USERNAME> $ oc project <PROJECT_NAME>
Logging into a specific project makes the image stream and templates that you install later in this procedure available only in that project’s namespace.
NoteAMQ Broker on OpenShift Container Platform uses StatefulSet resources with all
*-persistence*.yaml
templates. For templates that are not*-persistence*.yaml
, AMQ Broker uses Deployments resources. Both types of resources are Kubernetes-native resources that can consume image streams only from the same project namespace in which the template will be instantiated.At the command line, run the following commands to import the broker image streams to your project namespace. Using the
--force
option with theoc replace
command updates the resources, or creates them if they don’t already exist.$ oc replace --force -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/74-7.4.6.GA/amq-broker-7-image-streams.yaml
Run the following command to update the AMQ Broker application templates.
$ for template in amq-broker-74-basic.yaml \ amq-broker-74-ssl.yaml \ amq-broker-74-custom.yaml \ amq-broker-74-persistence.yaml \ amq-broker-74-persistence-ssl.yaml \ amq-broker-74-persistence-clustered.yaml \ amq-broker-74-persistence-clustered-ssl.yaml; do oc replace --force -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/74-7.4.6.GA/templates/${template} done
3.2. Preparing a templates-based broker deployment
Prerequisites
- Before deploying a broker instance on OpenShift Container Platform, you must have installed the AMQ Broker image streams and application templates. For more information, see Installing the AMQ Broker image streams and application templates.
Procedure
Use the command prompt to create a new project:
$ oc new-project amq-demo
Create a service account to be used for the AMQ Broker deployment:
$ echo '{"kind": "ServiceAccount", "apiVersion": "v1", "metadata": {"name": "amq-service-account"}}' | oc create -f -
Add the view role to the service account. The view role enables the service account to view all the resources in the amq-demo namespace, which is necessary for managing the cluster when using the OpenShift dns-ping protocol for discovering the broker cluster endpoints.
$ oc policy add-role-to-user view system:serviceaccount:amq-demo:amq-service-account
AMQ Broker requires a broker keystore, a client keystore, and a client truststore that includes the broker keystore. This example uses Java Keytool, a package included with the Java Development Kit, to generate dummy credentials for use with the AMQ Broker installation.
Generate a self-signed certificate for the broker keystore:
$ keytool -genkey -alias broker -keyalg RSA -keystore broker.ks
Export the certificate so that it can be shared with clients:
$ keytool -export -alias broker -keystore broker.ks -file broker_cert
Generate a self-signed certificate for the client keystore:
$ keytool -genkey -alias client -keyalg RSA -keystore client.ks
Create a client truststore that imports the broker certificate:
$ keytool -import -alias broker -keystore client.ts -file broker_cert
Use the broker keystore file to create the AMQ Broker secret:
$ oc create secret generic amq-app-secret --from-file=broker.ks
Add the secret to the service account created earlier:
$ oc secrets add sa/amq-service-account secret/amq-app-secret
3.3. Deploying a basic broker
The procedure in this section shows you how to deploy a basic broker that is ephemeral and does not support SSL.
This broker does not support SSL and is not accessible to external clients. Only clients running internally on the OpenShift cluster can connect to the broker. For examples of creating broker configurations that support SSL, see Tutorials.
Prerequisites
- You have already prepared the broker deployment. See Preparing an AMQ Broker deployment.
- Starting in AMQ Broker 7.3, you use a new version of the Red Hat Container Registry to access container images. This new version of the registry requires you to become an authenticated user before you can access images and pull them into an OpenShift project. Before following the procedure in this section, you must first complete the steps described in Red Hat Container Registry Authentication.
- AMQ Broker 7.4 has been designated as a Long Term Support (LTS) release version. Bug fixes and security advisories will be made available for AMQ Broker 7.4 in a series of micro releases (7.4.1, 7.4.2, 7.4.3, and so on) for a period of at least 12 months. This means that you will be able to get recent bug fixes and security advisories for AMQ Broker without having to upgrade to a new minor release.
- To remain in a supported configuration, you must install the latest micro release in the LTS release stream. This means that you must use the latest broker container image from the LTS stream in your broker deployments. This section shows how to specify the latest broker container image for a broker deployment based on application templates.
3.3.1. Create the broker application
Procedure
Log in to the
amq-demo
project space, or another, existing project in which you want to deploy a broker.$ oc login -u <USER_NAME> $ oc project <PROJECT_NAME>
Create a new broker application, based on the template for a basic broker. The broker created by this template is ephemeral and does not support SSL.
$ oc new-app --template=amq-broker-74-basic \ -p AMQ_PROTOCOL=openwire,amqp,stomp,mqtt,hornetq \ -p AMQ_QUEUES=demoQueue \ -p AMQ_ADDRESSES=demoTopic \ -p AMQ_USER=amq-demo-user \ -p AMQ_PASSWORD=password \
The basic broker application template sets the environment variables shown in the following table.
Table 3.1. Basic broker application template Environment variable Display Name Value Description AMQ_PROTOCOL
AMQ Protocols
openwire,amqp,stomp,mqtt,hornetq
The protocols to be accepted by the broker
AMQ_QUEUES
Queues
demoQueue
Creates an anycast queue called demoQueue
AMQ_ADDRESSES
Addresses
demoTopic
Creates an address (or topic) called demoTopic. By default, this address has no assigned routing type.
AMQ_USER
AMQ Username
amq-demo-user
The username the client uses
AMQ_PASSWORD
AMQ Password
password
The password the client uses with the username
3.3.2. Deploy and start the broker application
After the broker application is created, you need to deploy it. Deploying the application creates a Pod for the broker to run in.
Procedure
- Click Deployments in the OpenShift Container Platform web console.
- Click the broker-amq application.
Click Deploy.
NoteIf the application does not deploy, you can check the configuration by clicking the Events tab. If something is incorrect, edit the deployment configuration by clicking the Actions button.
After you deploy the broker application, inspect the current state of the broker Pod.
- Click Deployment Configs.
Click the broker-amq Pod and then click the Logs tab to verify the state of the broker. You should see the queue previously created via the application template.
If the logs show that:
- The broker is running, skip to step 9 of this procedure.
-
The broker logs have not loaded, and the Pod status shows
ErrImagePull
orImagePullBackOff
, your deployment configuration was not able to directly pull the specified broker image from the Red Hat Container Registry. In this case, continue to step 5 of this procedure.
To prepare the Pod for installation of the broker container image, scale the number of running brokers to
0
.-
Click
. -
Click
. -
In the deployment config
.yaml
file, set the value of thereplicas
attribute to0
. -
Click
Save
. - The pod restarts, with zero broker instances running.
-
Click
Install the latest broker container image.
- In your web browser, navigate to the Red Hat Container Catalog.
-
In the search box, enter
AMQ Broker LTS
. Click Search. -
In the search results, click AMQ Broker LTS. The
amq7/amq-broker-lts-rhel7
repository opens, with thelatest
image tag automatically selected. - Click the Get this image tab.
Under Authentication with registry tokens, review the on-page instructions in the Using OpenShift secrets section. The instructions describe how to specify the broker container image and the image pull secret name associated with the account used for authentication in the Red Hat Container Registry to your Pod deployment configuration file.
For example, to reference the broker container image and pull secret in the
broker-amq
deployment configuration in theamq-demo
project namespace, include lines that look like the following:apiVersion: apps.openshift.io/v1 kind: DeploymentConfig .. metadata: name: broker-amq namespace: amq-demo .. spec: containers: name: broker-amq image: 'registry.redhat.io/amq7/amq-broker-lts-rhel7:7.4' .. imagePullSecrets: - name: {PULL-SECRET-NAME}
- Click Save.
Import the latest broker image version to your project namespace. For example:
$ oc import-image amq7/amq-broker-lts-rhel7:7.4 --from=registry.redhat.io/amq7/amq-broker-lts-rhel7 --confirm
Edit the
broker-amq
deployment config again, as previously described. Set the value of thereplicas
attribute back to its original value.The broker Pod restarts, with all running brokers referencing the new broker image.
Click the Terminal tab to access a shell where you can start the broker and use the CLI to test sending and consuming messages.
sh-4.2$ ./broker/bin/artemis run sh-4.2$ ./broker/bin/artemis producer --destination queue://demoQueue 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 : 4 s Producer ActiveMQQueue[demoQueue], thread=0 Elapsed time in milli second : 4584 milli seconds sh-4.2$ ./broker/bin/artemis consumer --destination queue://demoQueue Consumer:: filter = null Consumer ActiveMQQueue[demoQueue], thread=0 wait until 1000 messages are consumed Received 1000 Consumer ActiveMQQueue[demoQueue], thread=0 Consumed: 1000 messages Consumer ActiveMQQueue[demoQueue], thread=0 Consumer thread finished
Alternatively, use the OpenShift client to access the shell using the Pod name, as shown in the following example.
// Get the Pod names and internal IP Addresses $ oc get pods -o wide // Access a broker Pod by name $ oc rsh <broker-pod-name>