红帽全球峰会此内容没有您所选择的语言版本。
Deploying AMQ Broker on OpenShift Container Platform
For Use with AMQ Broker 7.1
Abstract
Preface
AMQ Broker 7.1 on OpenShift Container Platform 3.9 is a Technology Preview release only. Technology Preview releases are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information see Red Hat Technology Preview Features Support Scope.
Chapter 1. Introduction
Red Hat AMQ Broker 7.1 is available as a containerized image that is designed for use with OpenShift Container Platform 3.9. Developers can quickly deploy an AMQ message broker in a hybrid cloud environment.
AMQ Broker, based on Apache ActiveMQ Artemis, is a full-featured, message-oriented middleware broker. It offers specialized queueing behaviors, message persistence, and manageability. Core messaging is provided by Apache ActiveMQ with support for different messaging styles such as publish-subscribe, point-to-point, and store-and-forward. It supports multiple protocols and client languages, so you can use many of your application assets. Lastly, AMQ Broker is supported to work with Red Hat JBoss Enterprise Application Platform.
The Technology Preview release of AMQ Broker on OpenShift Container Platform has the following limitations:
- Scaling down and message migration is not available.
- High Availability (HA): Shared store is supported only if the containers have access to a distributed file system.
External clients do not support HA.
-
Because external Core Protocol JMS clients do not support HA or any type of failover, the connection factories must be configured with
useTopologyForLoadBalancing=false. - AMQP clients do not support failover lists.
-
Because external Core Protocol JMS clients do not support HA or any type of failover, the connection factories must be configured with
- The AMQ Core Protocol JMS Client cannot be configured to use an haproxy with TLS passthrough, which requires SNI. This issue occurs because the SNI information is not passed by the Core Client, even when sniHost is set correctly on the URI. To work around this issue, use another method to enable external client access to AMQ Broker on OpenShift Container Platform, such as NodePort.
Scaling up and persistent storage partitioning is available for the Technology Preview release but is not currently documented.
1.2. Version compatibility and support
For details about OpenShift Container Platform 3.9 image version compatibility, see the OpenShift and Atomic Platform Tested Integrations page.
The AMQ Broker on OpenShift Container Platform image is not available in the service catalog, so you must manually install the image.
Procedure
Log in to OpenShift as a cluster administrator (or as a user that has project administrator access to the global openshift project), for example:
$ oc login -u system:adminAt the command line, run the following commands to update the core AMQ Broker on OpenShift Container Platform image stream in the openshift project:
$ oc create -n openshift -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/71-1.0.TP/amq-broker-7-image-streams.yaml $ oc replace -n openshift --force -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/71-1.0.TP/amq-broker-7-image-streams.yaml $ oc -n openshift import-image amq-broker-71-openshift:1.0NoteYou might receive error messages indicating some image streams already exist after invoking the
createcommand. A single command to create and replace is not available.Run the following command to update the AMQ Broker templates:
$ for template in amq-broker-71-basic.yaml \ amq-broker-71-ssl.yaml \ amq-broker-71-persistence.yaml \ amq-broker-71-persistence-ssl.yaml \ amq-broker-71-statefulset-clustered.yaml; do oc create -n openshift -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/71-1.0.TP/templates/${template} oc replace -n openshift -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/71-1.0.TP/templates/${template} doneNoteYou might receive "already exists" error messages after invoking the
createcommand.
The AMQ Broker on OpenShift Container Platform image requires a service account for deployments. Service accounts are API objects that exist within each project. Three service accounts are created automatically in every project:
-
builder: This service account is used by build pods. It contains thesystem:image-builderrole from which you can push images to any image stream in the project using the internal Docker registry. -
deployer: This service account is used by deployment pods. It contains thesystem:deployerrole from which you can view and modify replication controllers and pods in the project. -
default: This service account is used to run all other pods unless you specify a different service account.
Service accounts can be created or deleted like any other API object. For multiple-node deployments, the service account must have the view role enabled so that it can discover and manage the various pods in the cluster. In addition, you must configure SSL to enable connections to AMQ Broker from outside of the OpenShift Container Platform instance; for more information about how to configure SSL see Configuring SSL. The type of discovery protocol that is used for discovering of AMQ Broker mesh endpoints is JGroups with OpenShift.dns ping protocol.
Procedure
-
Add the
viewrole to the service account:
$ oc policy add-role-to-user view -z default2.3. Configuring SSL
For a minimal SSL configuration to allow connections outside of OpenShift Container Platform, AMQ Broker requires a broker keystore, a client keystore, and a client truststore that includes the broker keystore. The broker keystore is also used to create a secret for the AMQ Broker on OpenShift Container Platform image, which is added to the service account.
The following example commands use Java KeyTool, a package included with the Java Development Kit, to generate the necessary certificates and stores.
Procedure
Generate a self-signed certificate for the broker keystore:
$ keytool -genkey -alias broker -keyalg RSA -keystore broker.ksExport the certificate so that it can be shared with clients:
$ keytool -export -alias broker -keystore broker.ks -file broker_certGenerate a self-signed certificate for the client keystore:
$ keytool -genkey -alias client -keyalg RSA -keystore client.ksCreate a client truststore that imports the broker certificate:
$ keytool -import -alias broker -keystore client.ts -file broker_certExport the client’s certificate from the keystore:
$ keytool -export -alias client -keystore client.ks -file client_certImport the client’s exported certificate into a broker SERVER truststore:
$ keytool -import -alias client -keystore broker.ts -file client_cert
2.4. Generating the AMQ Broker secret
The broker keystore can be used to generate a secret for the namespace, which is also added to the service account so that the applications can be authorized.
Procedure
In a command line, run the following command:
$ oc create secret generic <secret-name> --from-file=<broker-keystore> --from-file=<broker-truststore> $ oc secrets add sa/<service-account-name> secret/<secret-name>
2.5. Creating an SSL route
After the AMQ Broker on OpenShift Container Platform image has been deployed, an SSL route needs to be created for the AMQ Broker transport protocol port to allow connections to AMQ Broker outside of OpenShift.
In addition, selecting Passthrough for TLS Termination relays all communication to AMQ Broker without the OpenShift router decrypting and resending it. Only SSL routes can be exposed because the OpenShift router requires SNI to send traffic to the correct service. For more information see Secured Routes.
The default ports for the various AMQ Broker transport protocols are:
| AMQ Broker transport protocol | Default port |
|---|---|
| All protocols | 61616 |
| All protocols (SSL) | 61617 |
| AMQP | 5672 |
| AMQP (SSL) | 5671 |
| MQTT | 1883 |
| MQTT (SSL) | 8883 |
| STOMP | 61613 |
| STOMP (SSL) | 61612 |
If you are using a template from an alternate repository, AMQ Broker configuration files such as artemis-users.properties can be included. When the image is downloaded for deployment, these files are copied from <amq-home>/conf/ to the <broker-instance-dir>/etc/ directory on AMQ Broker, which is committed to the container and pushed to the OpenShift registry.
If using this method, ensure that the placeholders in the configuration files (such as AUTHENTICATION) are not removed, as these placeholders are necessary for building the AMQ Broker on OpenShift Container Platform image.
2.7. Configuring client connections
Clients for the AMQ Broker on OpenShift Container Platform image must specify the OpenShift router port (443) when setting the broker URL for SSL connections. Otherwise, AMQ Broker attempts to use the default SSL port (61617). Including the failover protocol in the URL preserves the client connection in case the pod is restarted or upgraded, or a disruption occurs on the router.
...
factory.setBrokerURL("failover://ssl://<route-to-broker-pod>:443");
...External clients do not support HA.
Chapter 3. Tutorials
These tutorials follow on from and assume an OpenShift Container Platform 3.9 instance similar to that created in OpenShift Container Platform 3.9 Getting Started.
In this tutorial you prepare and deploy a multiple-node AMQ Broker instance with persistent storage.
3.1. Preparing the AMQ Broker deployment
Procedure
At a command prompt, create a new project:
$ oc new-project amq-demoCreate 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 mesh endpoints.
$ oc policy add-role-to-user view system:serviceaccount:amq-demo:amq-service-accountAMQ 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.ksExport the certificate so that it can be shared with clients:
$ keytool -export -alias broker -keystore broker.ks -file broker_certGenerate a self-signed certificate for the client keystore:
$ keytool -genkey -alias client -keyalg RSA -keystore client.ksCreate a client truststore that imports the broker certificate:
$ keytool -import -alias broker -keystore client.ts -file broker_certUse the broker keystore file to create the AMQ Broker secret:
$ oc secrets new amq-app-secret broker.ksAdd the secret to the service account created earlier:
$ oc secrets add sa/amq-service-account secret/amq-app-secret
3.2. Deploying the image and template
Procedure
-
Navigate to the OpenShift web console and log in, selecting the
amq-demoproject space. - Click Add to Project > Browse catalog to list all of the default image streams and templates.
-
Use the Filter search bar to limit the list to those that match
amq. You might need to click See all to show the desired application template. Select a template. This example uses the
amq-broker-71-persistence-ssl.yamltemplate to allow for persistent storage and SSL.Expand Table 3.1. Example template Environment variable Value APPLICATION_NAME
broker
AMQ_TRANSPORTS
openwire
AMQ_USER
amq-demo-user
AMQ_PASSWORD
password
VOLUME_CAPACITY
512Mi
AMQ_KEYSTORE_TRUSTSTORE_DIR
/etc/amq-secret-volume
AMQ_TRUSTSTORE
broker.ts
AMQ_TRUSTSTORE_PASSWORD
password
AMQ_KEYSTORE
broker.ks
AMQ_KEYSTORE_PASSWORD
password
IMAGE_STREAM_NAMESPACE
openshift
3.3. Post-deployment
3.3.1. Creating a route
You must create a route for the broker so that clients outside of OpenShift Container Platform can connect using SSL. By default, the OpenWire protocol uses the 61617/TCP port.
Only one broker can be scaled up. You cannot scale up multiple brokers.
Procedure
- Click Create a Route and from the Service drop-down menu, click broker-amq-tcp-ssl.
- Select the Secure route check box to display the TLS parameters.
- From the TLS Termination drop-down menu, click Passthrough. This selection relays all communication to AMQ Broker without the OpenShift router decrypting and resending it.
Clients can now connect to the broker by specifying the following in their configuration:
factory.setBrokerURL("failover://ssl://broker-amq-demo.example.com:443");
3.3.1.1. Monitoring AMQ Broker
This tutorial demonstrates how to monitor AMQ Broker.
Prerequisite
You must have created a project and a service account, and added the view role to the service account for AMQ Broker deployment. For more information see Preparing the AMQ Broker deployment.
Procedure
At the command line, go to your project:
$ oc project monitoramqDeploy a new broker instance to the
monitoramqproject, using theamq-broker-71-basictemplate from theopenshiftnamespace:$ oc process openshift//amq-broker-71-basic -p APPLICATION_NAME=broker -p AMQ_USER=admin -p AMQ_PASSWORD=admin -p AMQ_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" createdGet the list of running pods:
$ oc get pods NAME READY STATUS RESTARTS AGE broker-amq-1-ftqmk 1/1 Running 0 14dRun the
oc logscommand:oc logs -f broker-amq-1-ftqmk Running /amq-broker-71-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.Run your query to monitor your broker for
MaxConsumers:$ curl -k -u admin:admin http://console-broker.monitoramq.apps.example.com/console/jolokia/read/org.apache.activemq.artemis:broker=%22broker%22,component=addresses,address=%22TESTQUEUE%22,subcomponent=queues,routing-type=%22anycast%22,queue=%22TESTQUEUE%22/MaxConsumers {"request":{"mbean":"org.apache.activemq.artemis:address=\"TESTQUEUE\",broker=\"broker\",component=addresses,queue=\"TESTQUEUE\",routing-type=\"anycast\",subcomponent=queues","attribute":"MaxConsumers","type":"read"},"value":-1,"timestamp":1528297825,"status":200}
Chapter 4. Reference
4.1. Application template parameters
Configuration of the AMQ Broker on OpenShift Container Platform image is performed by specifying values of application template parameters. The following parameters can be configured:
| Parameter | Description |
|---|---|
|
| Specifies the addresses available by default on the broker on its startup, in a comma-separated list. |
|
| Specifies the password used for authentication to the broker. If no value is specified, a random password is generated. |
|
| Specifies the user name used as an administrator authentication to the broker. If no value is specified, a random user name is generated. |
|
|
If not specified, or set to |
|
| Enables clustering. |
|
| Specifies the password to use for clustering. If no value is specified, a random password is generated. |
|
| Specifies the cluster user to use for clustering. If no value is specified, a random user name is generated. |
|
| Specifies the directory for the data. Used in stateful sets. |
|
|
Specifies additional arguments to pass to |
|
| Specifies the SSL keystore file name. If no value is specified, a random password is generated but SSL will not be configured. |
|
| (Optional) Specifies the password used to decrypt the SSL keystore. |
|
|
Specifies the directory where the secrets are mounted. The default value is |
|
| For SSL only, specifies the maximum number of connections that an acceptor will accept. |
|
| Specifies the name of the broker instance. |
|
| Specifies the password used for authentication to the broker. If no value is specified, a random password is generated. |
|
| Specifies the queues available by default on the broker on its startup, in a comma-separated list. |
|
|
If set to |
|
|
If set to |
|
|
Specifies the name for the role created. The default value is |
|
| If replication is enabled, sets the pod to be a slave. |
|
|
Specifies the messaging protocols used by the broker in a comma-separated list. Available options are |
|
| Specifies the SSL truststore file name. If no value is specified, a random password is generated but SSL will not be configured. |
|
| (Optional) Specifies the password used to decrypt the SSL truststore. |
|
| Specifies the user name used for authentication to the broker. If no value is specified, a random user name is generated. |
|
| Specifies the name of the application used internally within OpenShift. It is used in names of services, pods, and other objects within the application. |
|
| Specifies the maximum amount of memory that message data can consume. If no value is specified, half of the system’s memory is allocated. |
|
|
Specifies the image. Used in the |
|
|
Specifies the image stream name space. Used in the |
|
|
Specifies the AMQ release version, which determines which AMQ image is used as a basis for the application, for example, |
|
| Specifies the port number for the OpenShift DNS ping. |
|
| Specifies the size of the persistent storage for database volumes. |
4.2. Security
Only SSL connections can connect from outside of the OpenShift instance. The non-SSL version of the protocols can only be used inside the OpenShift instance.
For security reasons, using the default keystore and truststore generated by the system is discouraged. Generate your own keystore and truststore and supply them to the image by using the OpenShift secrets mechanism.
4.3. Logging
In addition to viewing the OpenShift logs, you can troubleshoot a running AMQ Broker on OpenShift Container Platform image by viewing the AMQ logs that are outputted to the container’s console.
Procedure
- At the command line, run the following command:
$ oc logs -f <pass:quotes[<pod-name>]> <pass:quotes[<container-name>]>Revised on 2018-06-14 10:46:43 EDT
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}