How to Create Custom Elasticsearch Plugins
Posted by Adam Vanderbush March 3, 2017We 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.
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
- How to Secure Your Elasticsearch with Your Own Authentication Plugin
- Making Elasticsearch Secure – A Peek into SSL/TLS Implementation
- How to Index Attachments and Files to Elasticsearch
- How to Index NMAP Port Scan Results into Elasticsearch
- Migrating MySql Data Into Elasticsearch Using Logstash
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.