How to Create Custom Elasticsearch Plugins

Posted by Adam Vanderbush March 3, 2017

We all know that Elasticsearch is a powerful search engine that comes with a lot of additional plugins to meet most of the requirements. Suppose you have a special requirement to work with Elasticsearch that is not provided by any of the plugins available in the market. Don’t worry. Elasticsearch provides many custom plugin classes that can be extended and helps you create your own plugin to serve those purposes.

In this article we explain how to write a custom plugin for Elasticsearch.

Tutorial

We will be using hosted Elasticsearch on Qbox.io for this post. You can sign up or launch your cluster here, or click “Get Started” in the header navigation. If you need help setting up, refer to “Provisioning a Qbox Elasticsearch Cluster.“

You can create a wide variety of plugins for Elasticsearch such as a REST endpoint or an HTTP service or a custom analyzer and lot more. For now, we are focusing on the plugin that handles a custom REST endpoint. For example, let us take our requirement as a sample rest API called “_hello”. When this API is called it will return a hello message with the cluster name.

To achieve this, we have to extend the BaseRestHandler and register the rest API that we are planning to introduce to Elasticsearch.

public class HelloRestAction extends BaseRestHandler {
      @Inject   
public HelloRestAction (Settings settings, RestController controller) {
  super(settings);    
  controller.registerHandler(GET, "/_ hello", this);
}
}

This will register the rest endpoint that we want when Elasticsearch boots up, and whenever we do a rest call using _hello, Elasticsearch will direct the request to this plugin. For Elasticsearch to know what is to be done with the request we need one more thing – the handleRequest method.

@Override
public void handleRequest(RestRequest request, RestChannel channel, NodeClient client) {
      String clustername = client.settings().get(“cluster.name”);
      channel.sendResponse(new BytesRestResponse(RestStatus.OK, XContentFactory.jsonBuilder().startObject().field(“hello”, “This is cluster –“+clustername).endObject()));
}

Plugins modules are added to Elasticsearch when it boots up. To load a plugin, it must have a plugin class that implements one of Elasticsearch’s plugin interfaces. In this example we are implementing a rest action. That is why we use the ActionPlugin. The getRestHandlers method in the ActionPlugin needs to be overridden and our HelloRestAction class is returned as array as shown in the example.

public class HelloPlugin extends Plugin implements ActionPlugin {
@Override
public List<Class<?extends RestHandler>> getRestHandlers() {
       return Arrays.asList(HelloRestAction.class);
}
}

The PluginService scans for the plugin-descriptor.properties file in the plugins folder to know the plugin class to load during bootstrap. The mandatory contents of the plugin-descriptor.properties are:

description=${description}  ------------------------ 'description': simple summary of the plugin
version=${version} --------------------------------- 'version': plugin's version
name=${name}---------------------------------------- 'name': the plugin name
classname=${classname}------------------------------ 'classname': the name of the class to load
java.version=${javaVersion}------------------------- 'java.version' java version used to build code
elasticsearch.version=${elasticsearchVersion}------- 'elasticsearch.version' version of elasticsearch

If using the Gradle or Maven build system, it will take care of packaging the plugin with all the dependencies and the plugin-descriptor.properties. Otherwise, you will have to create the plugin zip file with the plugin jar file and plugin-descriptor.properties. If there are any dependency jar files for your plugin, add those too, in the zip file.

Using the bin>plugin install command install the plugin to Elasticsearch and boot up Elasticsearch. You can test the _hello command using browser or curl command.

plugin1.png#asset:1194

Conclusion

In this article we have explained how to create a plugin for Elasticsearch to have a custom rest API. Similarly, you can try out various functionalities such as custom search or indexing or any other rest endpoints that you like to experiment.

Related Helpful Resources

Give It a Whirl!

It’s easy to spin up a standard hosted Elasticsearch cluster on any of our 47 Rackspace, Softlayer, Amazon or Microsoft Azure data centers. And you can now provision a replicated cluster.

Questions? Drop us a note, and we’ll get you a prompt response.

Not yet enjoying the benefits of a hosted ELK-stack enterprise search on Qbox? We invite you to create an account today and discover how easy it is to manage and scale your Elasticsearch environment in our cloud hosting service.

Categorized under: