Skip to content

Latest commit

 

History

History
93 lines (73 loc) · 3.85 KB

custom-plugins.md

File metadata and controls

93 lines (73 loc) · 3.85 KB
Raw
description
Learn how to build and deploy your own plugins

Custom Plugins

Overview

Gravitee API Management (APIM) plugins extend and customize component behavior to meet your strategic needs. Each APIM distribution includes a default set of plugins. You can also deploy additional Gravitee-maintained and third-party plugins from the plugin marketplace.

Common structure

Plugins follow a common structure:

-----------------
.
├── pom.xml
├── README.md
└── src
    ├── assembly
    │   └── <plugin>-assembly.xml
    ├── main
    │   ├── java
    │   │   └── <main java files>
    │   └── resources
    │       └── plugin.properties
    └── test
        └── java
            └── <test java files>
-----------------

Below are the different key files:

FileDescription
pom.xmlThe main Maven POM file
README.mdThe main entry point for the plugin documentation
<plugin>-assembly.xmlThe common Maven assembly descriptor
plugin.propertiesThe plugin descriptor file

{% tabs %} {% tab title="pom.xml" %} Gravitee projects are Maven-managed. A plugin project is described via the Maven Project Object Model file. {% endtab %}

{% tab title="README.md" %} Each plugin should by documented by a dedicated README.md file that contains comprehensive information related to the use of your plugin. {% endtab %}

{% tab title="-assembly.xml" %} To integrate with the Gravitee ecosystem, a plugin needs to be deployed with a given file structure. The <plugin>-assembly.xml file is the Maven Assembly descriptor used to build the distribution file, which has the following structure:

-----------------
.
├── <main Jar file>.jar
└── lib
-----------------

The different files/folders are described below:

FileDescription
<main Jar file>.jarThe plugin’s main Jar file
lib/A directory containing external libraries to correctly execute the .jar

{% tabs %} {% tab title=".jar" %} The main .jar file of each plugin contains information on the business behavior and the plugin descriptor file. {% endtab %}

{% tab title="lib/" %} This directory contains all of the plugin's external dependencies (non-provided-scope Maven dependencies). {% endtab %} {% endtabs %} {% endtab %}

{% tab title="plugin.properties" %} The plugin.properties file is the plugin descriptor, which acts as an ID card and is read by APIM Gateway during the plugin loading process. The descriptor includes the following parameters:

Parameter Description
id The plugin identifier
name The plugin name
version The plugin version
description The plugin description
class The main plugin class
type The type of plugin (e.g., policy, reporter)

{% hint style="warning" %} The plugin identifier must be unique for the APIM Gateway to load it correctly {% endhint %} {% endtab %} {% endtabs %}

{% hint style="info" %} See this page to learn how to deploy your custom plugin {% endhint %}