Skip to content

Latest commit

 

History

History
133 lines (85 loc) · 7.5 KB

DEVELOPER_GUIDE.md

File metadata and controls

133 lines (85 loc) · 7.5 KB
Raw

Notifications plugin for OpenSearch

Overview

Notifications plugin for OpenSearch enables other plugins to send notifications via Email, Slack, Amazon Chime, Custom web-hook etc channels

Highlights

  1. Supports sending email with attachment (PDF, PNG, CSV, etc).
  2. Supports sending multipart email with Text and HTML body with full Embedded HTML support.
  3. Supports cross-plugin calls to send notifications (without re-implementing).
  4. Supports tracking the number of email sent from this plugin and throttling based on it.

Documentation

Please see our documentation.

Setup

  1. Check out this package from version control.
  2. Launch Intellij IDEA, choose Import Project, and select the settings.gradle file in the root of this package.
  3. To build from the command line, set JAVA_HOME to point to a JDK >= 14 before running ./gradlew.

Setup email notification using localhost email relay/server

  1. Run local email server on the machine where OpenSearch is running. e.g. for Mac, run command sudo postfix start
  2. Verify that local email server does not require any authentication (Make sure server is listening on local port only)
  3. Update the notification.yml configuration file according to your setup

Setup Amazon SES and SDK

While using Amazon SES as email channel for sending mail, use below procedure for SES setup and configure environment.

  1. Setup Amazon SES account
  2. Verify Email address
  3. Create IAM role with Allowing Access to Email-Sending Actions Only Action required are SendEmail and SendRawEmail.
  4. While using command line configure AWS credentials Refer Best practices
  5. Use Amazon EC2 IAM role to grant permissions while using EC2

Build

This project uses following tools

  1. Gradle build system. Gradle comes with an excellent documentation that should be your first stop when trying to figure out how to operate or modify the build.
  2. OpenSearch build tools for Gradle. These tools are idiosyncratic and don't always follow the conventions and instructions for building regular Java code using Gradle. If you encounter such a situation, the OpenSearch build tools is your best bet for figuring out what's going on.

Building from the command line

  1. ./gradlew build builds and tests project.
  2. ./gradlew run launches a single node cluster with the notifications plugin installed.
  3. ./gradlew run -PnumNodes=3 launches a multi-node cluster (3 nodes) with the notifications plugin installed.
  4. ./gradlew integTest launches a single node cluster with the notifications plugin installed and runs all integ tests.
  5. ./gradlew integTest -PnumNodes=3 launches a multi-node cluster with the notifications plugin installed and runs all integ tests.
  6. ./gradlew integTest -Dtests.class="*RunnerIT" runs a single integ test class
  7. ./gradlew integTest -Dtests.method="test execute * with dryrun" runs a single integ test method (remember to quote the test method name if it contains spaces).
  8. ./gradlew notificationsBwcCluster#mixedClusterTask launches a cluster with three nodes of bwc version of OpenSearch with notifications and tests backwards compatibility by upgrading one of the nodes with the current version of OpenSearch with notifications, creating a mixed cluster.
  9. ./gradlew notificationsBwcCluster#rollingUpgradeClusterTask launches a cluster with three nodes of bwc version of OpenSearch with notifications and tests backwards compatibility by performing rolling upgrade of each node with the current version of OpenSearch with notifications.
  10. ./gradlew notificationsBwcCluster#fullRestartClusterTask launches a cluster with three nodes of bwc version of OpenSearch with notifications and tests backwards compatibility by performing a full restart on the cluster upgrading all the nodes with the current version of OpenSearch with notifications.
  11. ./gradlew bwcTestSuite runs all the above bwc tests combined.

When launching a cluster using above commands, logs are placed in notifications/build/testclusters/integTest-0/logs/.

Run integration tests with Security enabled

  1. Setup a local OpenSearch cluster with security plugin.
  • ./gradlew build
  • ./gradlew integTest -Dtests.rest.cluster=localhost:9200 -Dtests.cluster=localhost:9200 -Dtests.clustername=opensearch-integrationtest -Dhttps=true -Duser=admin -Dpassword=admin
  • ./gradlew integTestRunner -Dtests.rest.cluster=localhost:9200 -Dtests.cluster=localhost:9200 -Dtests.clustername=opensearch-integrationtest -Dhttps=true -Duser=admin -Dpassword=admin --tests "<test name>"

Debugging

Sometimes it's useful to attach a debugger to either the OpenSearch cluster, or the integ tests to see what's going on. When running unit tests, hit Debug from the IDE's gutter to debug the tests. You must start your debugger to listen for remote JVM before running the below commands.

To debug code running in an actual server, run:

./gradlew integTest -Dopensearch.debug # to start a cluster and run integ tests

OR

./gradlew run --debug-jvm # to just start a cluster that can be debugged

The OpenSearch server JVM will launch suspended and wait for a debugger to attach to localhost:5005 before starting the OpenSearch server. The IDE needs to listen for the remote JVM. If using Intellij you must set your debug-configuration to "Listen to remote JVM" and make sure "Auto Restart" is checked. You must start your debugger to listen for remote JVM before running the commands.

To debug code running in an integ test (which exercises the server from a separate JVM), run:

./gradlew -Dtest.debug integTest

The test runner JVM will start suspended and wait for a debugger to attach to localhost:5005 before running the tests.

Advanced: Launching multi-node clusters locally

Sometimes you need to launch a cluster with more than one OpenSearch server process.

You can do this by running ./gradlew run -PnumNodes=<numberOfNodesYouWant>

You can also run the integration tests against a multi-node cluster by running ./gradlew integTest -PnumNodes=<numberOfNodesYouWant>

You can also debug a multi-node cluster, by using a combination of above multi-node and debug steps. You must set up debugger configurations to listen on each port starting from 5005 and increasing by 1 for each node.

Backport

See link to backport documentation

Code of Conduct

See CODE_OF_CONDUCT for more information.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License. See LICENSE for more information.

Notice

See NOTICE for more information.

Copyright

Copyright OpenSearch Contributors. See NOTICE for details.