All Products
Search

This Product

    API Gateway:Manage plugins

    Document Center

    API Gateway:Manage plugins

    Last Updated:Jun 22, 2026

    Cloud-native API Gateway provides built-in plugins for authentication, traffic control, and security protection, and supports custom plugins for flexible gateway extensions. You can install, enable, uninstall, and manage plugin versions, including seamless rolling updates, upgrades, and downgrades.

    Introduction to plugins

    Cloud-native API Gateway plugins fall into three categories based on their source:

    • Official plugins: Plugins released by the Higress team.

    • Community plugins: Plugins contributed by the Higress community.

    • Custom plugins: Plugins uploaded by users for their own use.

    Install and enable a plugin

    To use a plugin, select it in the Cloud-native API Gateway console and install it on a gateway instance. A plugin takes effect only after you install it, configure its rules, and enable it. You can install plugins in two ways:

    Note

    • MCP/Route Level Plugin Rules: These rules apply to routes and take effect when a request matches a specific route.

    • Domain-level plug-in rules: These rules apply to domain names. Rules for specific domain names have a higher priority than rules for wildcard domain names.

    • Instance-level plug-in rules: These rules apply globally to the gateway and are matched when no routing-level or domain-level rules are matched.

    Method 1: Install from outside a gateway instance

    1. Go to the Plugins page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. On the Plug-in page, in the Quick Navigation pane, select a plugin type or search for a plugin by name. Click Install failed. on the card for the plugin. In the Install Plug-in dialog box, select the gateway instance for the plugin, and then click OK.

    3. In the Configuration section, find the target gateway instance and click Rule Configuration in the Actions column. On the rule configuration page, select an Effective Scope.

      • If you select MCP/Route Level Plugin Rules or Domain-level plug-in rules, click Add Rule. On the Add Routing Level Rule or Add Domain Level Rule page, turn on Status (enabled by default). Select a Target, configure the Plug-in Rules, and then click OK.

      • If you select Instance-level plug-in rules, enable Status (enabled by default), configure the Plug-in Rules, and then click Save.

    Method 2: Install from within a gateway instance

    1. Go to the Instances page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. Go to the details page for the target instance. In the navigation pane on the left, select Plug-in.

    3. Click Install Plug-in. On the Install Plugin page, use the Quick Navigation pane to select a plugin type or search for a plugin by name. Click the plugin card and then click Install and Configure in the dialog box that appears.

    4. In the Rule Configuration dialog box, configure rules for the selected plugin, select an effective scope, and click OK.

    5. (Optional) On the gateway instance page, select Plug-in in the left navigation pane. In the plugin list, find the target plugin and click Rule Configuration in the Actions column. Then, configure the rules and select an effective scope.

      • If you select MCP/Route Level Plugin Rules or Domain-level plug-in rules, click Add Rule. On the Add Routing Level Rule or Add Domain Level Rule page, turn on Status (enabled by default), select a Target, configure the Plug-in Rules, and click OK.

      • If you select Instance-level plug-in rules, turn on Status (enabled by default), configure the Plug-in Rules, and click Save.

    Uninstall a plugin

    Background

    Uninstalling a plugin completely removes it from a gateway. You can uninstall plugins in two ways.

    Important

    Before uninstalling a plugin, disable all active plugin rules. If a plugin is not enabled, uninstalling it also deletes all configured rules.

    Method 1: Uninstall from outside a gateway instance

    1. Go to the Plugins page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. On the Plug-in page, in the Quick Navigation pane, select a plugin type or search for a plugin by name. Click the card of the plugin that you want to uninstall.

    3. Click the Configuration tab. Find the gateway instance from which you want to uninstall the plugin and click Uninstall in the Actions column.

    4. In the dialog box that appears, click the OK button. A message confirms that the plugin was successfully uninstalled.

    Method 2: Uninstall from within a gateway instance

    1. Go to the Instances page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. Go to the details page of the target instance and in the navigation pane on the left, select Plug-in.

    3. In the plugin list, find the plugin that you want to uninstall and click Uninstall in the Actions column.

    4. In the dialog box that appears, click the OK button. A message confirms that the plugin was uninstalled successfully.

    Add a version to a custom plugin

    Important

    You cannot add versions to custom Lua plugins.

    Adding a version creates a new version record for each modification to a custom plugin, helping you track changes and control releases. Follow these steps:

    1. Go to the Plugins page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. On the Plug-in page, in the Quick Navigation pane, set Plug-in Type to Custom or search for a plugin by name. Click Add Version on the plugin card. In the Add Version panel, configure the Version Information:

      • Version: Enter the version number for the plugin. The version number must follow the semantic versioning (semver) specification, such as 1.0.1.

      • Version Description: A brief description of the features and changes in this version, such as Added rate limiting feature.

      • WASM File: The compiled .wasm file that executes the plugin logic in the gateway.

      • Execution Stage: Select the phase of the request processing flow in which the plugin is executed, such as Default Phase.

      • Execution Priority: Enter a number to specify the execution order of the plugin. A larger number indicates a higher priority.

      • Adapt to Gateway Version: Enter the gateway engine version number that this plugin is compatible with. This ensures that the plugin runs correctly.

        Note

        This is the minimum gateway version on which this plugin can be installed.

    Plugin version changes

    Important

    To ensure a smooth upgrade, make sure that the new version is compatible with the rule configuration of the original version.

    1. Go to the Instances page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. Go to the details page of the target instance. In the navigation pane on the left, select Plug-in.

    3. In the plugin list, find the target plugin. Then, click Version Change in the Actions column.

    4. In the Version Change dialog box, select the desired version, and then click OK.

    Delete a version

    1. Go to the Plugins page in the Cloud-native API Gateway console. In the top menu bar, select a region.

    2. On the Plug-in page, find a plugin by setting Plug-in Type to Custom in the Quick Navigation pane or searching for the plugin by name. Point to the image icon on the plugin card.

    3. Then click Deleted.. In the dialog box that appears, select the version to delete and click OK.