Chapter 5. Tutorials

5.1. Example Deployment Workflow

This tutorial prepares and deploys a multi-node A-MQ instance with persistent storage. Before we get started, you must create a persistent volume in OpenShift and it should be have the available status.

5.1.1. Preparing A-MQ Deployment

  1. Log in as a cluster administrator or user that has project administrator access to the openshift project. 

    $ oc login -u system:admin

  2. Run the following commands to update the core A-MQ OpenShift image stream in the openshift project. 

    $ oc create -n openshift -f \
 https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.15/amq/amq63-image-stream.json

$ oc replace -n openshift -f \
 https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.15/amq/amq63-image-stream.json

$ oc -n openshift import-image jboss-amq-63:1.4

    It is possible to see some error messages saying some image streams already exist.

  3. Update the A-MQ templates. 

    $ for template in amq63-persistent-ssl.json \
amq63-basic.json \
amq63-ssl.json \
amq63-persistent.json;
do
oc replace -n openshift -f \
https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.4.15/amq/${template}
done

  4. Create a new amq-demo project: 

    $ oc new-project amq-demo

  5. Create a service account to be used for the A-MQ deployment: 

    $ echo '{"kind": "ServiceAccount", "apiVersion": "v1", "metadata": {"name": "amq-service-account"}}' | oc create -f -

  6. Add the view role to the service account. This enables the service account to view all the resources in the amq-demo namespace, which is necessary for managing the cluster when using the Kubernetes REST API agent for discovering the mesh endpoints. 

    $ oc policy add-role-to-user view system:serviceaccount:amq-demo:amq-service-account

  7. Edit the deployment configuration to run the AMQ pod with newly created service account. 

    $ oc edit dc/<deployment_config>

    Add the serviceAccount and serviceAccountName parameters to the spec field, and specify the service account you want to use. 

    spec:
      securityContext: {}
      serviceAccount: serviceaccount
      serviceAccountName: amq-service-account

  8. A-MQ requires a broker keyStore, a client keyStore, and a client trustStore that includes the broker keyStore.
    This example uses ‘keytool’, a package included with the Java Development Kit, to generate dummy credentials for use with the A-MQ installation.

    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 trust store that imports the broker certificate: 

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

  9. Use the broker keyStore file to create the A-MQ secret: 

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

  10. Add the secret to the service account created earlier: 

    $ oc secrets add sa/amq-service-account secret/amq-app-secret

5.1.2. Deployment

  1. Log in to the OpenShift web console and select the amq-demo project space.
  2. Click Add to Project to list all of the default image streams and templates.
  3. Use the Filter by keyword search bar to limit the list to those that match amq. You may need to click See all to show the desired application template.
  4. Select the template. This example uses the amq63-persistent-ssl template to allow for persistent storage.

Example Template:
APPLICATION_NAME
broker
MQ_PROTOCOL
openwire
MQ_USERNAME
amq-demo-user
MQ_PASSWORD
password
VOLUME_CAPACITY
512Mi
AMQ_SECRET
amq-app-secret
AMQ_TRUSTSTORE
broker.ks
AMQ_TRUSTSTORE_PASSWORD
password
AMQ_KEYSTORE
broker.ks
AMQ_KEYSTORE_PASSWORD
password
AMQ_MESH_DISCOVERY_TYPE
kube
AMQ_MESH_SERVICE_NAME
broker
AMQ_MESH_SERVICE_NAMESPACE
amq-demo
AMQ_STORAGE_USAGE_LIMIT
1 gb
AMQ_SPLIT
true
IMAGE_STREAM_NAMESPACE
openshift

Run get pods command to get the list of running pods: 

$ oc get pods
NAME                    READY     STATUS    RESTARTS   AGE
amq63-amq-2-m8fdh       1/1       Running   0          2m
amq63-drainer-1-3rpgx   1/1       Running   0          8m

5.1.3. Post-Deployment

Creating a route
Create a route for the broker so that clients outside of OpenShift can connect using SSL. By default, the OpenWire protocol uses the 61617/TCP port.

  1. Click Create a Route and click Show options for secured routes to display all parameters.
  2. Use the Target Port drop-down menu to select 61617/TCP
  3. Use the TLS Termination drop-down menu to select Passthrough. This will relay all communication to the A-MQ broker without the OpenShift router decrypting and resending it.

  4. Clients can now connect to the broker by specifying the following in their configuration:

    factory.setBrokerURL("failover://ssl://broker-amq-demo.example.com:443");

Scaling up
Scale up by clicking the Scale up arrow in the amq-demo project Overview in the web console. Or, using the OpenShift command line:

$ oc scale dc amq-demo --replicas=3

Connecting to the A-MQ Console
To connect to the A-MQ console from the OpenShift web console, navigate to the broker pod and click the Connect button located in the Template information.

For OpenShift Container Platform, click the Open Java Console button. === Example How to Monitor A-MQ This tutorial demonstrates how to monitor A-MQ.

5.1.4. Prerequisite

Make sure you have created a project, service account, and added the view role to the service account for A-MQ deployment, as mentioned in the section Example Deployment Workflow.

5.1.5. Monitoring A-MQ

  1. Go to your project: 

    $ oc project monitoramq

  2. Deploy a new broker instance to the monitoramq project, using the amq63-basic template from the openshift namespace: 

    $ oc process openshift//amq63-basic -v APPLICATION_NAME=broker,MQ_USERNAME=admin,MQ_PASSWORD=admin,MQ_QUEUES=TESTQUEUE -n monitoramq | oc create -f 	-

services "broker-amq-amqp" created
services "broker-amq-mqtt" created
services "broker-amq-stomp" created
services "broker-amq-tcp" created
deploymentconfigs "broker-amq" created

  3. Get the list of running pods: 

    $ oc get pods

NAME                 READY     STATUS    RESTARTS   AGE
broker-amq-1-ftqmk   1/1       Running   0          14d

  4. Run the command oc logs: 

    oc logs -f broker-amq-1-ftqmk

Running jboss-amq-6/amq63-openshift image, version 1.3-5
INFO: Loading '/opt/amq/bin/env'
INFO: Using java '/usr/lib/jvm/java-1.8.0/bin/java'
INFO: Starting in foreground, this is just for debugging purposes (stop process by pressing CTRL+C)
...
INFO | Listening for connections at: tcp://broker-amq-1-ftqmk:61616?maximumConnections=1000&wireFormat.maxFrameSize=104857600
INFO | Connector openwire started
INFO | Starting OpenShift discovery agent for service broker-amq-tcp transport type tcp
INFO | Network Connector DiscoveryNetworkConnector:NC:BrokerService[broker-amq-1-ftqmk] started
INFO | Apache ActiveMQ 5.11.0.redhat-621084 (broker-amq-1-ftqmk, ID:broker-amq-1-ftqmk-41433-1491445582960-0:1) started
INFO | For help or more information please see: http://activemq.apache.org
WARN | Store limit is 102400 mb (current store usage is 0 mb). The data directory: /opt/amq/data/kahadb only has 9684 mb of usable space - resetting to maximum available disk space: 9684 mb
WARN | Temporary Store limit is 51200 mb, whilst the temporary data directory: /opt/amq/data/broker-amq-1-ftqmk/tmp_storage only has 9684 mb of usable space - resetting to maximum available 9684 mb.

  5. Run your query to monitor your broker for ServiceHealth: 

    $ curl -k -H "Authorization: Bearer $(oc whoami -t)" https://10.1.2.2:8443/api/v1/namespaces/monitoramq/pods/https:broker-amq-1-ftqmk:8778/proxy/jolokia/read/org.apache.activemq:type=Broker,brokerName=*,service=Health/CurrentStatus

{"request":{"mbean":"org.apache.activemq:brokerName=*,service=Health,type=Broker","attribute":"CurrentStatus","type":"read"},"value":{"org.apache.activemq:brokerName=broker-amq-1-ftqmk,service=Health,type=Broker":{"CurrentStatus":"Good"}},"timestamp":1491451600,"status":200}

    where,

    • 10.1.2.2 is the master host.
    • monitoramq is the name of your namespace or project.
    • broker-amq-1-ftqmk is the name of your running pod (got from oc get pods in previous step-4).
    • 8778 Jolokia exposed port for AMQ xPaaS image.

  6. Run your query to monitor your broker’s memoryLimit for a queue: 

    $ curl -k -H "Authorization: Bearer $(oc whoami -t)" https://10.1.2.2:8443/api/v1/namespaces/monitoramqlatest/pods/https:broker-amq-1-ftqmk:8778/proxy/jolokia/read/org.apache.activemq:type=Broker,brokerName=*,destinationType=Queue,destinationName=ABEL/MemoryLimit

{"request":{"mbean":"org.apache.activemq:brokerName=*,destinationName=ABEL,destinationType=Queue,type=Broker","attribute":"MemoryLimit","type":"read"},"value":{"org.apache.activemq:brokerName=broker-amq-1-ftqmk,destinationName=ABEL,destinationType=Queue,type=Broker":{"MemoryLimit":1048576}},"timestamp":1491451792,"status":200}
  7. Go to your Openshift Web Console, select your project, go to the running pod, and click Open Java Console.
  8. You will be redirected to Openshift Container Platform Console, where you can see the listed queues under your broker.