Plugin Metadata
In this document, you will learn the basic concept of plugin metadata in APISIX and why you may need them.
Explore additional resources at the end of the document for more information on related topics.
Overview
In APISIX, a plugin metadata object configures shared settings for all instances of the same plugin. It is useful for values, such as log-format templates, that should normally remain consistent wherever the plugin is enabled.
APISIX stores one plugin metadata object for each plugin name. Only plugins that define a metadata schema support plugin metadata. Fields and behavior depend on the plugin. Check the plugin's documentation in the Plugin Hub before configuring its metadata.
The following diagram illustrates the concept of plugin metadata using two instances of syslog plugins on two different routes, as well as a plugin metadata object setting a global log_format for the syslog plugin:
The plugin metadata object in the diagram defines a shared log_format for the two syslog plugin instances. The instance on the /delivery route does not define its own log_format, so it uses the metadata value. The instance on the /order route defines a different log_format, so syslog uses that instance-level value for requests to the route.
For logger plugins that support shared log_format metadata, an instance-level log_format takes precedence over the metadata value. This behavior is shared by plugins such as syslog, http-logger, kafka-logger, and file-logger.
Plugin metadata is not merged with every plugin configuration by a universal precedence rule. Each plugin determines how its instances consume metadata and whether an instance-level field overrides a metadata field.
Additional Resource(s)
- Key Concepts - Plugins
- Control API - Plugin Metadata
- Admin API - Plugin Metadata
- Plugin Hub