All Products
Search

This Product

    API Gateway:Manage plugins

    Document Center

    API Gateway:Manage plugins

    Last Updated:Dec 03, 2025

    Cloud-native API Gateway provides built-in extension plugins for features such as authentication, traffic control, and security protection. You can also upload custom plugins to flexibly extend gateway capabilities. This topic describes how to install, enable, and uninstall plugins. It also covers plugin version management, seamless hot updates, and upgrades or downgrades.

    Introduction to plugins

    Cloud-native API Gateway plugins are categorized into the following three types based on their source:

    • Official plugins: Plugins released by Higress.

    • Community plugins: Plugins contributed by the Higress community.

    • Custom plugins: Plugins that you upload for your own use.

    Install and enable plugins

    To install a plugin, select it in Cloud-native API Gateway and install it on a gateway instance. For a plugin to take effect, you must install it, configure its rules, and enable it. Cloud-native API Gateway provides two methods for installing plugins:

    Note

    • MCP/Routing-level Plugin Rules: These rules apply to routes. These rules take effect when a request matches a specific route.

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

    • Instance-level Plugin Rules: These rules apply globally to the gateway. These rules are matched if no routing-level or domain-level rules are matched.

    Method 1: Install from outside a gateway instance

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

    2. On the Plug-in page, use the Quick Navigation section to select a plugin type or search for a plugin by name. Click Install on the plugin card. In the Install Plugin dialog box, select the target gateway instance, 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 a Scope.

      • If you select Operation-/Route-level Plug-in Rules or Domain-level Plug-in Rules, click Add Rule. On the AddOperation/RouteRule Level or AddDomain NameRule Level page, turn on the Status switch (enabled by default), select a Target, configure the Plug-in Rules, and then click OK.

      • If you select Instance-level Plug-in rules, turn on the Status switch (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. Navigate to the details page of the target instance. In the navigation pane on the left, click Plug-in.

    3. Click Install Plug-in. On the Install Plugin page, use the Quick Navigation section to select a plugin type or search for a plugin by name. Click the plugin card. In the dialog box, click Install And Configure.

    4. In the Rule Configurations dialog box, configure the rules for the selected plugin and select a scope. Click OK.

    5. (Optional) On the gateway instance page, choose Plug-in in the navigation pane on the left. In the plugin list, click Rule Configuration in the Actions column for the desired plugin to configure its rules and scope.

      • If you select Operation-/Route-level Plug-in Rules or Domain-level Plug-in Rules, click Add Rule. On the AddOperation/RouteRule Level or AddDomain NameRule Level page, turn on the Status switch (enabled by default), select a Target, configure the Plug-in Rules, and then click OK.

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

    Uninstall plugins

    Background

    If you no longer need a plugin on a gateway, you can uninstall it to permanently remove it. Cloud-native API Gateway provides two methods for uninstalling plugins:

    Important

    Before you uninstall a plugin that has enabled rules, you must first disable it. If a plugin is not enabled, uninstalling it also deletes all of its configured rules.

    Method 1: Uninstall from outside a gateway instance

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

    2. On the Plug-in page, use the Quick Navigation section to 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 confirmation dialog box, click OK. A success message is displayed.

    Method 2: Uninstall from within a gateway instance

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

    2. Navigate to the details page of the target instance. In the navigation pane on the left, click 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 confirmation dialog box, click OK. A success message is displayed.

    Add a version to a custom plugin

    Important

    Lua custom plugins are an exception and do not support versioning.

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

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

    2. On the Plug-in page, use the Quick Navigation section to set Plugin 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 a version identifier for the plugin. The version number must comply with the Semantic Versioning (SemVer) specification, such as 1.0.1.

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

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

      • Execution Stage: Select the phase in the request processing flow when the plugin runs, 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 is compatible with this plugin to ensure that it runs correctly.

        Note

        The minimum gateway version on which this plugin can be installed.

    Change a plugin version

    Important

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

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

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

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

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

    Delete a version

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

    2. On the Plug-in page, use the Quick Navigation section to set Plugin Type to Custom or search for a plugin by name. On the plugin card, move the mouse pointer over the image icon.

    3. Click Uninstall, select the version that you want to delete, and click OK.