Chapter 3. Jaeger installation

3.1. Installing Jaeger

You can install Jaeger on OpenShift Container Platform in either of two ways:

  • You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation. To install Jaeger as part of a service mesh, follow the Red Hat Service Mesh Installation instructions.
  • If you do not want to install a service mesh, you can use the Jaeger Operator to install the Red Hat build of Jaeger by itself. To install Jaeger without a service mesh, use the following instructions.

3.1.1. Prerequisites

Before you can install OpenShift Jaeger, review the installation activities, and ensure that you meet the prerequisites:

3.1.2. Jaeger installation overview

The steps for installing OpenShift Jaeger are as follows:

  • Review the documentation and determine your deployment strategy.
  • If your deployment strategy requires persistent storage, install the Elasticsearch Operator via the OperatorHub.
  • Install the Jaeger Operator via the OperatorHub.
  • Modify the Jaeger YAML file to support your deployment strategy.
  • Deploy one or more instances of Jaeger to your OpenShift Container Platform environment.

3.1.3. Installing the Elasticsearch Operator

The default Jaeger deployment uses in-memory storage because it is designed to be installed quickly for those evaluating Jaeger, giving demonstrations, or using Jaeger in a test environment. If you plan to use Jaeger in production, you must install a persistent storage option, in this case, Elasticsearch.

Prerequisites

  • Access to the OpenShift Container Platform web console.
  • An account with the cluster-admin role.
Warning

Do not install Community versions of the Operators. Community Operators are not supported.

Note

If you have already installed the Elasticsearch Operator as part of OpenShift cluster logging, you do not need to install the Elasticsearch Operator again. The Jaeger Operator will create the Elasticsearch instance using the installed Elasticsearch Operator.

Procedure

  1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  2. Navigate to OperatorsOperatorHub.
  3. Type Elasticsearch into the filter box to locate the Elasticsearch Operator.
  4. Click the Elasticsearch Operator provided by Red Hat to display information about the Operator.
  5. Click Install.
  6. On the Install Operator page, select the A specific namespace on the cluster option and then select openshift-operators-redhat from the menu.

    Note

    The Elasticsearch installation guide says you must specify the openshift-operators-redhat namespace for the Elasticsearch operator for OpenShift Jaeger.

  7. Select the Update Channel that matches your OpenShift Container Platform installation. For example, if you are installing on OpenShift Container Platform version 4.6, select the 4.6 update channel.
  8. Select the Automatic Approval Strategy.

    Note

    The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  9. Click Subscribe.
  10. On the Installed Operators page, select the openshift-operators-redhat project. Wait until you see that the Elasticsearch Operator shows a status of "InstallSucceeded" before continuing.

3.1.4. Installing the Jaeger Operator

To install Jaeger you use the OperatorHub to install the Jaeger Operator.

By default the Operator is installed in the openshift-operators project.

Prerequisites

  • Access to the OpenShift Container Platform web console.
  • An account with the cluster-admin role.
  • If you require persistent storage, you must also install the Elasticsearch Operator before installing the Jaeger Operator.
Warning

Do not install Community versions of the Operators. Community Operators are not supported.

Procedure

  1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  2. Navigate to OperatorsOperatorHub.
  3. Type Jaeger into the filter to locate the Jaeger Operator.
  4. Click the Jaeger Operator provided by Red Hat to display information about the Operator.
  5. Click Install.
  6. On the Create Operator Subscription page, select All namespaces on the cluster (default). This installs the Operator in the default openshift-operators project and makes the Operator available to all projects in the cluster.
  7. Select the stable Update Channel. This will automatically update Jaeger as new versions are released. If you select a maintenance channel, for example, 1.17-stable, you will receive bug fixes and security patches for the length of the support cycle for that version.

    • Select an Approval Strategy. You can select Automatic or Manual updates. If you choose Automatic updates for an installed Operator, when a new version of that Operator is available, the Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. If you select Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.

      Note

      The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process.

  8. Click Subscribe.
  9. On the Subscription Overview page, select the openshift-operators project. Wait until you see that the Jaeger Operator shows a status of "InstallSucceeded" before continuing.

3.2. Configuring and Deploying Jaeger

The Jaeger Operator includes a custom resource definition (CRD) file that defines the architecture and configuration settings for the Jaeger resources. You can either install the default configuration or modify the file to better suit your business requirements.

Jaeger has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a Jaeger instance the Operator uses this configuration file to create the objects necessary for the deployment.

Jaeger custom resource file showing deployment strategy

apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
  name: simple-prod
spec:
  strategy: production 1

1
The Jaeger Operator currently supports the following deployment strategies:
  • allInOne (Default) - This strategy is intended for development, testing, and demo purposes. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage.

    Note

    In-memory storage is not persistent, which means that if the Jaeger instance shuts down, restarts, or is replaced, that your trace data will be lost. And in-memory storage cannot be scaled, since each pod has its own memory. For persistent storage, you must use the production or streaming strategies, which use Elasticsearch as the default storage.

  • production - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately. The Agent can be injected as a sidecar on the instrumented application or as a daemonset. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes.
  • streaming - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the backend storage (Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (AMQ Streams/ Kafka).

    Note

    The streaming strategy requires an additional Red Hat subscription for AMQ Streams.

Note

There are two ways to install Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you must configure and deploy Jaeger as part of the ServiceMeshControlPlane.

3.2.1. Deploying the default Jaeger strategy from the web console

The custom resource definition (CRD) defines the configuration used when you deploy an instance of Jaeger. The default CR for Jaeger is named jaeger-all-in-one-inmemory and it is configured with minimal resources to ensure that you can successfully install it on a default OpenShift Container Platform installation. You can use this default configuration to create a Jaeger instance that uses the AllInOne deployment strategy, or you can define your own custom resource file.

Note

In-memory storage is not persistent, which means that if the Jaeger pod shuts down, restarts, or is replaced, that your trace data will be lost. For persistent storage, you must use the production or streaming strategies, which use Elasticsearch as the default storage.

Prerequisites

  • The Jaeger Operator must be installed.
  • Review the instructions for how to customize the Jaeger installation.
  • An account with the cluster-admin role.

Procedure

  1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  2. Create a new project, for example jaeger-system.

    1. Navigate to HomeProjects.
    2. Click Create Project.
    3. Enter jaeger-system in the Name field.
    4. Click Create.
  3. Navigate to OperatorsInstalled Operators.
  4. If necessary, select jaeger-system from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project.
  5. Click the OpenShift Jaeger Operator. On the Overview tab, under Provided APIs, the Operator provides a single link.
  6. Under Jaeger click Create Instance.
  7. On the Create Jaeger page, to install using the defaults, click Create to create the Jaeger instance.
  8. On the Jaegers page, click the name of the Jaeger instance, for example, jaeger-all-in-one-inmemory.
  9. On the Jaeger Details page, click the Resources tab. Wait until the Pod has a status of "Running" before continuing.

3.2.1.1. Deploying default Jaeger from the CLI

Follow this procedure to create an instance of Jaeger from the command line.

Prerequisites

  • An installed, verified OpenShift Jaeger Operator.
  • Access to the OpenShift CLI (oc) that matches your OpenShift Container Platform version.
  • An account with the cluster-admin role.

Procedure

  1. Log in to the OpenShift Container Platform CLI as a user with the cluster-admin role.

    $ oc login https://{HOSTNAME}:8443
  2. Create a new project named jaeger-system.

    $ oc new-project jaeger-system
  3. Create a custom resource file named jaeger.yaml that contains the following text:

    Example jaeger-all-in-one.yaml

    apiVersion: jaegertracing.io/v1
    kind: Jaeger
    metadata:
      name: jaeger-all-in-one-inmemory

  4. Run the following command to deploy Jaeger:

    $ oc create -n jaeger-system -f jaeger.yaml
  5. Run the following command to watch the progress of the pods during the installation process:

    $ oc get pods -n jaeger-system -w

    Once the installation process has completed, you should see output similar to the following:

    NAME                                         READY   STATUS    RESTARTS   AGE
    jaeger-all-in-one-inmemory-cdff7897b-qhfdx   2/2     Running   0          24s