Chapter 7. Deploying AMQ Broker on OpenShift Container Platform using application templates Important Starting in 7.8, the use of application templates for deploying AMQ Broker on OpenShift Container Platform is a deprecated feature. This feature will be removed in a future release. Red Hat continues to support existing deployments that are based on application templates. However, Red Hat does not recommend using application templates for new deployments. For new deployments, Red Hat recommends using the AMQ Broker Operator. For information on installing and deploying the Operator, see Chapter 3, Deploying AMQ Broker on OpenShift Container Platform using the AMQ Broker Operator . The procedures in this section show: How to install the AMQ Broker image streams and application templates How to prepare a template-based broker deployment An example of using the OpenShift Container Platform web console to deploy a basic broker instance using an application template. For examples of deploying other broker configurations using templates, see template-based broker deployment examples . 7.1. Prerequisites You should have read the comparison of methods for deploying AMQ Broker on OpenShift Container Platform. For new deployments, Red Hat recommends using the AMQ Broker Operator. For more information, see Chapter 2, Planning a deployment of AMQ Broker on OpenShift Container Platform . 7.2. Installing the 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 using application templates and template-based broker deployment examples . 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: 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 the openshift project, you can also add -n openshift as an optional parameter with the oc 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: 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. Note AMQ 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 the oc replace command updates the resources, or creates them if they don't already exist. Run the following command to update the AMQ Broker application templates. 7.3. Preparing a template-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 image streams and application templates . The following procedure assumes that the broker image stream and application templates you installed 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 . Procedure Use the command prompt to create a new project: Create a service account to be used for the AMQ Broker deployment: 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. 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: Export the certificate so that it can be shared with clients: Generate a self-signed certificate for the client keystore: Create a client truststore that imports the broker certificate: Use the broker keystore file to create the AMQ Broker secret: Link the secret to the service account created earlier: 7.4. 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. Note 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 template-based broker deployment examples . Prerequisites You have already prepared the broker deployment. See Preparing a template-based broker deployment . The following procedure assumes that the broker image stream and application templates you installed in Installing the image streams and application templates 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 . Starting in AMQ Broker 7.3, you use a new version of the Red Hat Ecosystem Catalog 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 . 7.4.1. Creating the broker application Procedure Log in to the amq-demo project space, or another, existing project in which you want to deploy a broker. 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. The basic broker application template sets the environment variables shown in the following table. Table 7.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 User name that the client uses to connect to the broker AMQ_PASSWORD AMQ Password password Password that the client uses with the user name to connect to the broker 7.4.2. About sensitive credentials In the AMQ Broker application templates, the values of the following environment variables are stored in a secret: AMQ_USER AMQ_PASSWORD AMQ_CLUSTER_USER (clustered broker deployments) AMQ_CLUSTER_PASSWORD (clustered broker deployments) AMQ_TRUSTSTORE_PASSWORD (SSL-enabled broker deployments) AMQ_KEYSTORE_PASSWORD (SSL-enabled broker deployments) To retrieve and use the values for these environment variables, the AMQ Broker application templates access the secret specified in the AMQ_CREDENTIAL_SECRET environment variable. By default, the secret name specified in this environment variable is amq-credential-secret . Even if you specify a custom value for any of these variables when deploying a template, OpenShift Container Platform uses the value currently stored in the named secret. Furthermore, the application templates always use the default values stored in amq-credential-secret unless you edit the secret to change the values, or create and specify a new secret with new values. You can edit a secret using the OpenShift command-line interface, as shown in this example: Values in the amq-credential-secret use base64 encoding. To decode a value in the secret, use a command that looks like this: 7.4.3. Deploying and starting 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 . Note If 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 DeploymentConfigs . 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 or ImagePullBackOff , 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 DeploymentConfigs broker-amq . Click Actions Edit DeploymentConfigs . In the deployment config .yaml file, set the value of the replicas attribute to 0 . Click Save . The pod restarts, with zero broker instances running. Install the latest broker container image. In your web browser, navigate to the Red Hat Container Catalog . In the search box, enter AMQ Broker . Click Search . Choose an image repository based on the information in the following table. Platform (Architecture) Container image name Repository name OpenShift Container Platform (amd64) AMQ Broker or AMQ Broker for RHEL 8 amq7/amq-broker or amq7/amq-broker-rhel8 OpenShift Container Platform on IBM Z (s390x) AMQ Broker for RHEL 8 on OpenJDK 11 amq7/amq-broker-openjdk-11-rhel8 OpenShift Container Platform on IBM Power Systems (ppc64le) AMQ Broker for RHEL 8 on OpenJDK 11 amq7/amq-broker-openjdk-11-rhel8 For example, for the OpenShift Container Platform broker container image, click AMQ Broker . The amq7/amq-broker repository opens, with the most recent image version automatically selected. If you want to change to an earlier image version, click the Tags tab and choose another version tag. 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 add references to the broker 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 image and pull secret in the broker-amq deployment configuration in the amq-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:7.8' .. imagePullSecrets: - name: {PULL-SECRET-NAME} Click Save . Import the latest broker image version to your project namespace. For example: Edit the broker-amq deployment config again, as previously described. Set the value of the replicas 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. 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 USD oc get pods -o wide // Access a broker Pod by name USD oc rsh <broker-pod-name> 7.5. Connecting external clients to template-based broker deployments This section describes how to configure SSL to enable connections from clients outside OpenShift Container Platform to brokers deployed using application templates. 7.5.1. 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. For a more complete example of deploying a broker instance that supports SSL, see Deploying a basic broker with SSL . Procedure Generate a self-signed certificate for the broker keystore: Export the certificate so that it can be shared with clients: Generate a self-signed certificate for the client keystore: Create a client truststore that imports the broker certificate: Export the client's certificate from the keystore: Import the client's exported certificate into a broker SERVER truststore: 7.5.2. 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 At the command line, run the following commands: 7.5.3. Creating an SSL Route To enable client applications outside your OpenShift cluster to connnect to a broker, you need to create an SSL Route for the broker Pod. You can expose only SSL-enabled Routes to external clients because the OpenShift router requires Server Name Indication (SNI) to send traffic to the correct Service. When you use an application template to deploy a broker on OpenShift Container Platform, you use the AMQ_PROTOCOL template parameter to specify the messaging protocols that the broker uses, in a comma-separated list. Available options are amqp , mqtt , openwire , stomp , and hornetq . If you do not specify any protocols, all protocols are made available. For each messaging protocol that the broker uses, OpenShift exposes a dedicated port on the broker Pod. In addition, OpenShift automatically creates a multiplexed, all protocols port. Client applications outside OpenShift always use the multiplexed, all protocols port to connect to the broker, regardless of which of the supported protocols they are using. Connections to the all protocols port are via a Service that OpenShift automatically creates, and an SSL Route that you create. A headless service within the broker Pod provides access to the other protocol-specific ports, which do not have their own Services and Routes that clients can access directly. The ports that OpenShift exposes for the various AMQ Broker transport protocols are shown in the following table. Brokers listen on the non-SSL ports for traffic within the OpenShift cluster. Brokers listen on the SSL-enabled ports for traffic from clients outside OpenShift, if you created your deployment using an SSL-based (that is, *-ssl.yaml ) template. Table 7.2. Default ports for AMQ Broker transport protocols AMQ Broker transport protocol Default port All protocols (OpenWire, AMQP, STOMP, MQTT, and HornetQ) 61616 All protocols -SSL (OpenWire AMQP, STOMP, MQTT, and HornetQ) 61617 AMQP 5672 AMQP (SSL) 5671 MQTT 1883 MQTT (SSL) 8883 STOMP 61613 STOMP (SSL) 61612 Below are some other things to note when creating an SSL Route on your broker Pod: When you create a Route, setting TLS Termination to Passthrough relays all communication to AMQ Broker without the OpenShift router decrypting and resending it. Note Regular HTTP traffic does not require a TLS passthrough Route because the OpenShift router uses HAProxy , which is an HTTP proxy. External broker clients must specify the OpenShift router port (443, by default) when setting the broker URL for SSL connections. When a client connection specifies the OpenShift router port, the router determines the appropriate port on the broker Pod to which the client traffic should be directed. Note By default, the OpenShift router uses port 443. However, the router might be configured to use a different port number, based on the value specified for the ROUTER_SERVICE_HTTPS_PORT environment variable. For more information, see OpenShift Container Platform Routes . Including the failover protocol in the broker URL preserves the client connection in case the Pod is restarted or upgraded, or a disruption occurs on the router. Both of the settings are shown in the example below. Additional resources For a complete example of deploying a broker that supports SSL and of creating an SSL Route to enable external client access, see Deploying a basic broker with SSL . For an example of creating Routes for clustered brokers to connect to their own instances of the AMQ Broker management console, see Creating routes for the AMQ Broker management console .

Commands:
oc login -u system:admin oc project openshift
oc login -u <USERNAME> oc project <PROJECT_NAME>
oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/78-7.8.5.GA/amq-broker-7-image-streams.yaml
for template in amq-broker-78-basic.yaml amq-broker-78-ssl.yaml amq-broker-78-custom.yaml amq-broker-78-persistence.yaml amq-broker-78-persistence-ssl.yaml amq-broker-78-persistence-clustered.yaml amq-broker-78-persistence-clustered-ssl.yaml; do oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/78-7.8.5.GA/templates/USD{template} done
oc new-project amq-demo
echo '{"kind": "ServiceAccount", "apiVersion": "v1", "metadata": {"name": "amq-service-account"}}' | oc create -f -
oc policy add-role-to-user view system:serviceaccount:amq-demo:amq-service-account
keytool -genkey -alias broker -keyalg RSA -keystore broker.ks
keytool -export -alias broker -keystore broker.ks -file broker_cert
keytool -genkey -alias client -keyalg RSA -keystore client.ks
keytool -import -alias broker -keystore client.ts -file broker_cert
oc create secret generic amq-app-secret --from-file=broker.ks
oc secrets link sa/amq-service-account secret/amq-app-secret
oc login -u <USER_NAME> oc project <PROJECT_NAME>
oc new-app --template=amq-broker-78-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 \
oc edit secrets amq-credential-secret
echo 'dXNlcl9uYW1l' | base64 --decode user_name
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:7.8' .. imagePullSecrets: - name: {PULL-SECRET-NAME}
oc import-image amq7/amq-broker:7.8 --from=registry.redhat.io/amq7/amq-broker --confirm
sh-4.2USD ./broker/bin/artemis run sh-4.2USD ./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.2USD ./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
// Get the Pod names and internal IP Addresses oc get pods -o wide // Access a broker Pod by name oc rsh <broker-pod-name>
keytool -genkey -alias broker -keyalg RSA -keystore broker.ks
keytool -export -alias broker -keystore broker.ks -file broker_cert
keytool -genkey -alias client -keyalg RSA -keystore client.ks
keytool -import -alias broker -keystore client.ts -file broker_cert
keytool -export -alias client -keystore client.ks -file client_cert
keytool -import -alias client -keystore broker.ts -file client_cert
oc create secret generic <secret-name> --from-file=<broker-keystore> --from-file=<broker-truststore> oc secrets link sa/<service-account-name> secret/<secret-name>
factory.setBrokerURL("failover://ssl://<broker-pod-route-name>:443");