このコンテンツは選択した言語では利用できません。
Chapter 3. Deploying AMQ Broker on OpenShift Container Platform using Application Templates
The procedures in this section show:
- How to install the AMQ Broker image streams and application templates
- How to prepare a templates-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 Templates-based broker deployment examples.
3.1. 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 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/75-7.5.0.GA/amq-broker-7-image-streams.yaml
Run the following command to update the AMQ Broker application templates.
$ for template in amq-broker-75-basic.yaml \ amq-broker-75-ssl.yaml \ amq-broker-75-custom.yaml \ amq-broker-75-persistence.yaml \ amq-broker-75-persistence-ssl.yaml \ amq-broker-75-persistence-clustered.yaml \ amq-broker-75-persistence-clustered-ssl.yaml; do oc replace --force -f \ https://raw.githubusercontent.com/jboss-container-images/jboss-amq-7-broker-openshift-image/75-7.5.0.GA/templates/${template} done
3.2. Preparing an AMQ 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.
-
The following procedure assumes that the broker image stream 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 asamq-demo
.
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.
-
The following procedure assumes that the broker image stream 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 asamq-demo
. - 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.
3.3.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.$ 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-75-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
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
3.3.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:
$ oc edit secrets amq-credential-secret
Values in the amq-credential-secret
use base64 encoding. To decode a value in the secret, use a command that looks like this:
$ echo 'dXNlcl9uYW1l' | base64 --decode user_name
3.3.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.
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
. Click Search. Choose an image repository based on the information in the following table.
Platform Container image name Repository name OpenShift Container Platform
AMQ Broker
amq7/amq-broker
OpenShift Container Platform on IBM Z
AMQ Broker on OpenJ9 11
amq7/amq-broker-openj9-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 pull the latest version of the OpenShift Container Platform broker container image for a deployment configuration called
broker-amq
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:7.5' .. imagePullSecrets: - name: {PULL-SECRET-NAME}
NoteTo use the latest version of the broker container image for OpenShift Container Platform on IBM Z, specify the image attribute as
registry.redhat.io/amq7/amq-broker-openj9-11-rhel8:7.5
.- Click Save.
Import the latest broker image version to your project namespace. For example:
$ oc import-image amq7/amq-broker:7.5 --from=registry.redhat.io/amq7/amq-broker --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>