Plugins can be installed to expand the capabilities of Gravitee APIM Gateway, APIM Management API (mAPI), AM, or Alert Engine (AE). They can customize the component’s behavior to satisfy needs and technical constraints.
{% hint style="info" %} For more technical information about plugins, including details of their directory structure and how to create your own, see the Custom Plugins Guide. {% endhint %}
The table below lists the different types of plugins you can use with APIM and the component(s) they can be plugged into, respectively:
| Type | Gateway | mAPI | AM | AE | Examples |
|---|---|---|---|---|---|
| Alert | true | true | false | false | Vertx |
| Connector | true | true | false | false | Kafka, MQTT, WebSocket |
| Fetcher | false | true | false | false | HTTP, GIT |
| Identity provider | false | true | false | false | LDAP, Oauth2, InMemory |
| Notifier | false | false | false | true | Email, Slack, Webhook |
| Policy | true | true | false | false | API Key, Rate-limiting, Cache |
| Reporter | true | false | false | false | Elasticsearch, Accesslog |
| Repository | true | true | false | false | MongoDB, Redis, Elasticsearch |
| Resource | true | true | false | false | Oauth2, Cache, LDAP |
| Secret provider | true | true | true | false | Kubernetes, HC Vault |
| Services | true | true | false | false | Sync, local-registry, health-check, monitor |
Alert
An alert is used to send triggers or events to the Alert Engine. These can be processed to send a notification via the configured plugin notifier. Configuring the notifier is the responsibility of the trigger.
Connector
A connector is used to add support for specific protocols, API styles, event brokers, and/or message queue services. For example, the Websocket and Kafka connector plugins allow you to front a Kafka topic with a Websocket API, making that Kafka topic consumable over a WebSocket connection.
Identity provider
An identity provider brokers trust with external user providers to authenticate and obtain information about end users. Out-of-the-box identity providers are:
- MongoDB
- In-memory
- LDAP / Active Directory
- OpenID Connect IdP (Azure AD, Google)
Notifier
A notifier is used to send notifications. The notifiers offered by Gravitee are:
- Slack
- Webhook
Policy
A policy modifies the behavior of the request or response handled by the Gateway. It can be considered a proxy controller, guaranteeing that a given business rule is fulfilled during request/response processing. Policies can be chained by a request or response policy chain using a logical order.
Examples:
- Authorization using an API key
- Applying header or query parameter transformations
- Applying rate limiting or quotas to avoid API flooding
See Custom Policies for how to create, use, and deploy a custom policy.
Reporter
A reporter is used by an APIM Gateway instance to report events such as:
- Request/response metrics (e.g., response-time, content-length, api-key)
- Monitoring metrics (e.g., CPU, Heap usage)
- Health-check metrics (e.g., status, response code)
Out-of-the-box reporters:
- Elasticsearch Reporter
- File Reporter
- Metrics Reporter
- TCP reporter
You can create, use and deploy custom reporters as described in the Custom Plugins guide.
Repository
A repository is a pluggable storage component for API configuration, policy configuration, analytics, etc. See the Repositories documentation for more information.
Resource
A resource can be added to an API for its whole lifecycle. APIM includes three default resources:
- Cache
- OAuth2 - Gravitee Access Management
- OAuth2 - Generic Authorization Server
See Resources for more information.
Secret provider
A secret provider resolves secrets to avoid exposing plain text passwords and secrets keys in the gravitee.yml file. For example, users can store their MongoDB password in a secret manager like HashiCorp Vault and then resolve it when the platform starts.
Deploying a plugin is as easy as copying the plugin archive (zip) into the dedicated directory. By default, you need to deploy the archives in ${GRAVITEE_HOME/plugins}. Refer to APIM Gateway Configuration for more information on modifying the directory structure.
{% hint style="warning" %} You must restart APIM nodes when applying new or updated plugins. {% endhint %}
Plugin discovery and loading occurs regardless of APIM license type. If a plugin is not included with your license, then it will be loaded but it will not be functional.
When APIM starts, all plugin zip files are read from the list of plugin directories set in the gravitee.yaml configuration file.
{% hint style="info" %} This operation is completed asynchronously for performance benefits. {% endhint %}
If duplicates are found (same type and ID), the most recent file is kept regardless of the plugin's version. This allows for easily overriding plugins.
Plugin override circumvents the need to remove plugins to use a newer version, which is a huge benefit for Kubernetes deployments via Gravitee's Helm Chart. This also benefits plugin developers, as they can pack and copy an updated plugin without having to script the removal of the old version.
After APIM finishes traversing the plugin directories, the plugins are loaded.
Plugins are immediately initialized by a specialized handler. If an error occurs while unpacking a plugin zip file, the faulty plugin is ignored. An error will be reported in the logs and the loading of the remaining plugins will resume.
The loading process is sequential and adheres to the following order based on plugin type:
- Cluster
- Cache
- Repository
- Alert
- Cockpit
- Any other types
The rest of the plugins are loaded in no particular order, except if they have dependencies. If a plugin depends on another plugin, that takes precedence over type ordering.
For example, if plugin1 (type:cluster) depends on plugin2 (type:cache) which depends on plugin3(type:alert), then the plugins are loaded in the following order:
plugin3(because plugin 2 depends on it, even if it is #4 in the type priority list)plugin2(because plugin 1 depends on it, even if it is #2 in the type priority list)plugin1