検索

このコンテンツは選択した言語では利用できません。

Chapter 3. Deploying AMQ Broker on OpenShift Container Platform using Application Templates

download PDF

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

  1. 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 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:

    $ 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.

    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.

  2. 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.

    $ 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
  3. 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 as amq-demo.

Procedure

  1. Use the command prompt to create a new project:

    $ oc new-project amq-demo
  2. 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 -
  3. 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
  4. 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.

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

      $ keytool -import -alias broker -keystore client.ts -file broker_cert
    5. Use the broker keystore file to create the AMQ Broker secret:

      $ oc create secret generic amq-app-secret --from-file=broker.ks
    6. 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.

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 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 as amq-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

  1. 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>
  2. 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 variableDisplay NameValueDescription

    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

  1. Click Deployments in the OpenShift Container Platform web console.
  2. Click the broker-amq application.
  3. 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.

  4. After you deploy the broker application, inspect the current state of the broker Pod.

    1. Click Deployment Configs.
    2. 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.
  5. To prepare the Pod for installation of the broker container image, scale the number of running brokers to 0.

    1. Click Deployment Configs broker-amq.
    2. Click Actions Edit Deployment Configs.
    3. In the deployment config .yaml file, set the value of the replicas attribute to 0.
    4. Click Save.
    5. The pod restarts, with zero broker instances running.
  6. Install the latest broker container image.

    1. In your web browser, navigate to the Red Hat Container Catalog.
    2. In the search box, enter AMQ Broker. Click Search.
    3. Choose an image repository based on the information in the following table.

      PlatformContainer image nameRepository 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.

    4. Click the Get This Image tab.
    5. 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 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.5'
          ..
          imagePullSecrets:
            - name: {PULL-SECRET-NAME}
      Note

      To 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.

    6. Click Save.
  7. 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
  8. 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.

  9. 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>
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.