Skip to content

Latest commit

 

History

History
143 lines (83 loc) · 6.22 KB

INSTALL.md

File metadata and controls

143 lines (83 loc) · 6.22 KB
Raw

Building, Installing, and Running the RCA Framework

This document walks you through the process of building and deploying the RCA framework along with the Performance Analyzer plugin. The RCA framework relies on the metrics provided by the performance analyzer plugin. Since this code is still in development, the released versions of performance analyzer plugin do not support the RCA framework yet and you will have to build the plugin from source.

Building the Performance Analyzer plugin

Prerequisites

Make sure you have the following tools and libraries installed.

  1. git (Mac: brew install git)
  2. maven (Mac: brew install maven) - Only needed if you are also building the Performance Analyzer plugin.
  3. JDK12+

Set up

1. Create a workspace where you will have all the code checked out

`mkdir workspace`

`cd workspace`

2. Clone the Performance Analyzer RCA repository as follows:

`git clone https://github.com/opensearch-project/performance-analyzer-rca.git`

`cd performance-analyzer-rca`

3. Set JAVA_HOME environment variable to point to JDK12 or higher

`export JAVA_HOME=/path/to/jdk12+`

4. (Optional) IntelliJ setup

a. Launch IntelliJ IDEA

b. Choose Import Project and select the `build.gradle` file in the root of this package

5. (Optional) Encryption in Transit Setup

This section contains instruction for enabling encryption transit between the client and server for REST and gRPC requests. This will not currently enforce client authentication. This feature, including full support for TLS is planned for an upcoming release.

a. Open $OPENSEARCH-HOME/config/opensearch-performance-analyzer/performance-analyzer.properties

b. Modify the certificate-file-path, private-key-file-path, and https-enabled entries

c. Example performance-analyzer.properties:
    
    certificate-file-path = /etc/ssl/certs/cert.pem
    private-key-file-path = /etc/ssl/certs/key.pem
    https-enabled = true

Build RCA framework

This package uses the Gradle build system. Gradle comes with excellent documentation that should be your first stop when trying to figure out how to operate or modify the build.

Building from command line

  • ./gradlew build - Builds, runs unit tests and creates a zip distribution for deployment.
  • The zip distribution can be found under build/distributions/ folder.
  • You will need to publish the RCA artifact to your maven local repository.

./gradlew publishToMavenLocal

Building from the IDE

  • Currently, the only IDE we support is IntelliJ IDEA. It's free, it's open source, it works. The gradle tasks above can also be launched from IntelliJ's Gradle toolbar.
  • The zip distribution can be found under build/distributions/ folder.

Build Performance Analyzer Plugin

  1. Move back to the workspace folder created during setup

  2. Clone the Performance Analyzer plugin repository as follows:

    git clone -b main --single-branch https://github.com/opensearch-project/performance-analyzer.git

  3. cd performance-analyzer

  4. Because we are supplying our own version of the RCA framework, the SHA might have changed. So, delete the old SHA file if it exists. The SHA will get updated during build time.

    rm -f licenses/performanceanalyzer-rca-3.0.0.0.jar.sha1

  5. Trigger a gradle build. This builds the plugin, runs unit tests and creates the plugin jar.

    ./gradlew build

  6. The plugin JAR can be found under build/distributions folder.

Installing the plugin

Prerequisites

  1. Docker - Download and install docker desktop from Docker website for Mac.

Setup

Currently, for the alpha development-only source code release, we support installing and running the RCA framework only on OpenSearch Docker containers.

NOTE: If planning to use this framework with security plugin, the demo configuration requires an initial admin password to be set. You can set this by creating a .env file next to the docker compose and add following line to it: OPENSEARCH_INITIAL_ADMIN_PASSWORD=<your-password> There is a password validation in place, which requires a strong password.

You can use the packaged Dockerfile and docker-compose.yml files here to spin up a cluster with RCA framework installed.

  1. Create a folder that will hold all the resources that are needed to install and run the RCA framework.

    mkdir rca-infra

  2. cd rca-infra

  3. Copy all the contents of the docker folder in this repo into our rca-infra folder.

    cp <RCA framework root>/docker/* ./

  4. Copy the RCA framework artifact and the Performance Analyzer plugin JAR into this folder

    cp <RCA framework root>/build/distributions/performance-analyzer-rca-3.0.0.0-SNAPSHOT.zip ./ cp <Performance Analyzer plugin root>/build/distributions/opensearch-performance-analyzer-3.0.0.0.zip ./

Installation

  1. Make sure you're in the rca-infra folder.

  2. Build and tag the Docker image with our RCA framework.

    docker build -t opensearch/pa-rca:3.0 .

  3. Spin up a two node cluster as follows:

    DATA_VOLUME1=opensearchdata1 DATA_VOLUME2=opensearchdata2 docker-compose -f docker-compose.yml -f docker-compose.hostports.yml -f docker-compose.cluster.yml up opensearch1 opensearch2

Running

Once the cluster is up and running, you will need to enable Performance Analyzer and the RCA framework. Both of them are behind feature flags currently.

NOTE: Performance Analyzer needs to be enabled before the RCA framework is started.

  1. Enable Performance Analyzer

    curl localhost:9200/_plugins/_performanceanalyzer/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

  2. Enable RCA Framework

    curl localhost:9200/_plugins/_performanceanalyzer/rca/cluster/config -H 'Content-Type: application/json' -d '{"enabled": true}'

  3. Verify the Settings curl -XGET localhost:9200/_plugins/_performanceanalyzer/cluster/config. It should give you {"currentPerformanceAnalyzerClusterState":3}