IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Integrations

›

Help for plugin authors

edit

Help for plugin authors

edit

The Elasticsearch repository contains examples of:

a site plugin for serving static HTML, JavaScript, and CSS.
a Java plugin which contains Java code.

These examples provide the bare bones needed to get started. For more information about how to write a plugin, we recommend looking at the plugins listed in this documentation for inspiration.

Site plugins

The example site plugin mentioned above contains all of the scaffolding needed for integrating with Maven builds. If you don’t plan on using Maven, then all you really need in your plugin is:

The plugin-descriptor.properties file
The _site/ directory
The _site/index.html file

Plugin descriptor file

edit

All plugins, be they site or Java plugins, must contain a file called plugin-descriptor.properties in the root directory. The format for this file is described in detail here:

dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties.

Either fill in this template yourself (see elasticsearch-kopf as an example) or, if you are using Elasticsearch’s Maven build system, you can fill in the necessary values in the pom.xml for your plugin. For instance, see plugins/site-example/pom.xml.

Mandatory elements for all plugins

edit

Element	Type	Description
`description`	String	simple summary of the plugin
`version`	String	plugin’s version
`name`	String	the plugin name

Mandatory elements for Java plugins

edit

Element	Type	Description
`jvm`	Boolean	true if the `classname` class should be loaded from jar files in the root directory of the plugin. Note that only jar files in the root directory are added to the classpath for the plugin! If you need other resources, package them into a resources jar.
`classname`	String	the name of the class to load, fully-qualified.
`java.version`	String	version of java the code is built against. Use the system property `java.specification.version`. Version string must be a sequence of nonnegative decimal integers separated by "."'s and may have leading zeros.
`elasticsearch.version`	String	version of elasticsearch compiled against.

Plugin release lifecycle

You will have to release a new version of the plugin for each new elasticsearch release. This version is checked when the plugin is loaded so Elasticsearch will refuse to start in the presence of plugins with the incorrect elasticsearch.version.

Mandatory elements for Site plugins

edit

Element	Type	Description
`site`	Boolean	true to indicate contents of the `_site/` directory in the root of the plugin should be served.

Loading plugins from the classpath

edit

When testing a Java plugin, it will only be auto-loaded if it is in the plugins/ directory. If, instead, it is in your classpath, you can tell Elasticsearch to load it with the plugin.types setting:

settingsBuilder()
    .put("cluster.name", cluster)
    .put("path.home", getHome())
    .put("plugin.types", MyCustomPlugin.class.getName()) 
    .build();

Tells Elasticsearch to load your plugin.

« Integrations