Skip to main content
Top
Review meshIQ Products (G2.com)

XRay on OpenShift Quick Start Guide

Use this guide to get started with XRay and Red Hat OpenShift.

Jump ahead:

Step 1: Prerequisites

In order to run XRay, you must be running AMQ Streams which provides the Kafka service. The AMQ Streams operator must first be installed on the same namespace where XRay will be installed.

Installation

Make the following changes when installing the AMQ Streams operator:

  1. Select Update channel: amq-streams-1.6.x
  2. Select Installation Mode: A specific namespace on the cluster
  3. For Installed Namespace select your preferred namespace
  4. Leave Approval Strategy as Automatic
  5. Click Install

Create the Kafka cluster

After the operator is installed, create an instance of Kafka API:

  1. Under the Installed operators section select Red Hat Integration - AMQ Streams
  2. Click Create instance for Kafka API under Provided APIs
  3. Configure Kafka cluster staying in the Form View (already selected)
  4. Enter a name for your cluster, e.g. xray-cluster (default is my-cluster)
  5. Expand the Kafka section, then expand the Storage section:
    1. Change Kafka storage to persistent-claim
    2. Set Size to 2Gi
    3. Set class to ibmc-block-gold (or any other applicable class for your OpenShift cluster)
  6. Expand the Zookeeper section, then expand the Storage section:
    1. Change Zookeeper storage to persistent-claim
    2. Set class to ibmc-block-gold (or any other applicable class for your OpenShift cluster)
    3. Set Size to 2Gi
  7. For additional configuration details, see Using AMQ Streams On OpenShift
  8. Click Create at the bottom of the form
  9. Go to Workloads > Pods and wait until 3x zookeeper, 3x kafka and entity-operator pods get Running status.

Now you can install the XRay operator.

Step 2: Operator installation from Red Hat Marketplace

  1. For information on registering your cluster and creating a namespace, see Red Hat Marketplace Docs. This must be done prior to installing the operator.
  2. Purchase XRay or start a free trial.
  3. On the main menu, click Workspace > My Software > product > Install Operator.
  4. On the Update Channel section, select an alpha.
  5. On the Approval Strategy section, select either Automatic or Manual. The approval strategy corresponds to how you want to process operator upgrades.
  6. On the Target Cluster section:
    1. Click the checkbox next to the clusters where you want to install the operator.
    2. For each cluster you selected, under Namespace Scope, on the Select Scope list, select an option.
      mceclip0.png
  7. Click Install. It may take several minutes for installation to complete.
  8. Once installation is complete, the status will change from installing to Up to date.
  9. For further information, see the Red Hat Marketplace Operator documentation.

Step 3: Verification of operator installation

  1. Once status changes to Up to date, click the vertical ellipses and select Cluster Console.
  2. Open the cluster where you installed the product.
  3. Go to Operators > Installed Operators
  4. Select the namespace or project you installed on.
  5. Verify status for product is Succeeded.
    mceclip2.png
  6. Click the product name to open details.
    mceclip3.png

Step 4: Application installation

To install XRay, click Create Instance under Nastel XRay components. The operator does not provide complete Form view at this time, so you must switch to YAML view to configure the XRay setup.

The following parameters need to be updated in the yaml:

  • Under the global section change:
    • subDomain to your cluster subdomain
    • kafkaHost to match the AMQ Streams Kafka service name ending in -kafka-bootstrap. If you set the cluster name as xray-cluster, then no need to update.
      mceclip4.png
  • If your cluster does not provide preferred storage classes ibmc-block-gold and ibmc-file-silver-gid, change all occurrences of it to a class your cluster provides.
  • All remaining attributes can be left as they are.

Click the Create button.

mceclip5.png

Navigate to Workloads > Pods. 12+ pods will initialize and start.

When starting XRay for the first time, it may take around 2 hours to initialize and start the xray-cep pod. During this time, the Kafka topics and Solr database get set up and initialized.

xray pod should start up last. After it gets started, you can proceed to using XRay.

Optional:  Install XRay realtime processing components

After XRay core components are up and running, you can install the optional XRay realtime processing components which are used to process subscriptions and triggers of XRay at runtime. For this reason, it heavily utilizes CPU usage, which may be a reason to increase your cloud subscription cost. If you intend to use XRay only as index storage, then you can skip installing the realtime processing components and continue to the next section, using XRay.

To install the XRay realtime processor, click Create Instance under Nastel XRay realtime processing components. The operator does not provide complete Form view at this time, so you must switch to YAML view to configure XRay setup.

The following parameters under the Global section need to be updated in the yaml:

  • subDomain to your cluster subdomain.
  • kafkaCluster to match AMQ Streams Kafka cluster name. If you set the cluster name to something other than xray-cluster when installing AQM Streams, then you need to change this property value (they should match).
  • kafkaHost to match the AMQ Streams Kafka service name ending in -kafka-bootstrap. If you set the cluster name to something other than xray-cluster when installing AQM Streams, then you need to change this property value (they should match).
    mceclip0.png
  • If you cluster does not provide the preferred storage classes ibmc-block-gold and ibmc-file-silver-gid, change all occurrences of it to a class your cluster provides.
  • All remaining attributes can be left as they are.

Click the Create button.

mceclip1.png

Navigate to Workloads > Pods. 7 additional pods should be added to the XRay Core components pods set. Wait until all of them initialize and start.

xray-storm-topologies pod should start up last. After it starts, XRay runtime processors will be running.

Step 5: Using XRay

Using routes:

    • Navigate to Networking > Routes, find route link ending with /xray (name starts xray-ingres-). Click on this link.
      mceclip6.png

Using service properties:

    • Navigate to Networking > Services > xray
      mceclip7.png
    • Compose this url: <External load balancer IP>:<Node Port>/xray. According to the provided screenshot it would be: 46.99.155:32017/xray. Paste it to your browser URL navigation field.

The XRay login screen displays in a new browser tab. Enter Admin/admin2 and click Login.
mceclip14.png

You can now use XRay.
mceclip15.png

See the XRay User’s Guide for more information on how to use XRay.