DocsICP FilingConsole
官方文档
首页

Plug-in datasets

更新时间：
复制 MD 格式
产品详情
我的收藏

API Gateway plug-ins offer rich features and flexible metadata management, but their text-based configuration can be limiting in large-scale scenarios. Plug-in datasets decouple configuration data from plug-in logic, letting you manage data as separate objects and significantly improving usability and scalability.

1. Limitations of text-based plug-ins

API Gateway plug-ins have the following characteristics:

  • Text-based configuration.

  • A size limit on the configuration.

These limitations make some plug-ins difficult to use in certain scenarios. For example, the following code shows a typical configuration for the IP address-based access control plug-in:

---
type: ALLOW 
items: 
- blocks:
  - 61.3.XX.XX/24
  - 192.168.34.XX/32
  - 192.168.158.XX/32
  appId: 219810
- blocks:
  - 79.11.XX.XX
  - 85.13.XX.XX
  - 72.152.XX.XX

This configuration works well for small applications with a few CIDR blocks. However, for large-scale applications with dozens or hundreds of CIDR blocks, this approach has two major drawbacks:

  • Management is error-prone. To change a single CIDR block, you must update the entire plug-in configuration.

  • With a large number of CIDR blocks, the configuration can exceed the plug-in's size limit.

These challenges are inherent to the text-based configuration model. Plug-in datasets solve both problems.

2. Decoupling configuration with plug-in datasets

A plug-in dataset decouples configuration data from the plug-in itself. You store data in a separate dataset object and reference it from within a plug-in. Changes to the dataset take effect in real time for all plug-ins that reference it.

On the plug-in configuration page, in the Script Configuration area, select Whitelist Mode Configuration from the Select Configuration Template drop-down list. The editor displays the IP address whitelist configuration in YAML format, including fields such as type: ALLOW and items (which contains blocks for CIDR blocks and appId). Below, the Dataset area displays the data entries in a table. The columns include Value, Description, Expiration Time, Creation Time, Modification Time, and Actions. You can add new entries by clicking Create Data Entry, or you can Edit or Delete existing entries.

Using a plug-in dataset, the configuration for the IP address-based access control plug-in can be simplified as follows:

---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3

You no longer need to modify the plug-in itself. To update your access control policy, modify the data entries in the referenced plug-in datasets.

Plug-in datasets solve the two problems described above:

  • The dataset size is flexible and not constrained by the plug-in's size limit, so you can manage large volumes of data.

  • You can modify the plug-in's behavior by making targeted changes to the dataset. For example, to add an IP address to a whitelist, add a new data entry to the dataset instead of modifying the entire plug-in.

API Gateway currently supports plug-in datasets for the JWT authentication plug-in. Support will be extended to other plug-ins, including IP address-based access control, parameter-based access control, and backend routing.

3. Features of plug-in datasets

Plug-in datasets let you dynamically modify a plug-in's configuration data. They have the following characteristics:

  1. Changes to data entries in a dataset take effect across all your dedicated instances within ten seconds.

  2. You can create up to 100 datasets, and each dataset can contain up to 200 data entries. If you need higher limits, submit a ticket to request a quota increase.

  3. A single dataset can be referenced by multiple plug-ins. Changes to the dataset take effect simultaneously for all referencing plug-ins.

  4. Data entry values within a dataset must be unique.

  5. You can set an expiration time for each data entry. The entry is automatically invalidated upon expiration. You can also configure an entry to never expire.

  6. Plug-in datasets are effective only for groups on dedicated instances. If a group is migrated to a shared instance, the plug-in dataset becomes invalid immediately.

4. Configure JWT authentication with plug-in datasets

4.1. Configure the plug-in dataset

  • Create a dataset.

Specify a name and select a type for the dataset. You can change the name at any time, but the type cannot be changed after selection. For the JWT authentication plug-in, select the JWT_BLOCKING type.

  • Create data entries in the dataset.

Open a plug-in dataset to create data entries. Each data entry value must be unique within the dataset. You can set an expiration time for each entry, after which the entry is automatically invalidated.

The value must be 1 to 64 characters long and can contain letters, digits, periods (.), underscores (_), hyphens (-), forward slashes (/), and backslashes (\). For the expiration time, you can select Short-term (which requires specifying a date range) or Long-term. You can also add a description of up to 180 characters.

  • Obtain the plug-in dataset ID.

After you create a plug-in dataset, the system generates a permanent ID for it. You can find this ID on the dataset list page. Use this ID to link plug-ins to the dataset.

4.2. Configure the JWT authentication plug-in

The JWT authentication plug-in in API Gateway now supports plug-in datasets.

A common use case is blocking requests from users who have a valid token but are on a blacklist. With plug-in datasets, the JWT authentication plug-in can reject requests based on a claim parameter decoded from the token. API Gateway rejects matching requests and lets you customize the rejection response. The following example shows how to configure this. Pay special attention to the parameters that start with block:

---
parameter: Authorization   # The parameter from which the token is obtained.
parameterLocation: header  # The location from which the token is obtained.
claimParameters:           # Claim parameter conversion. The gateway maps JWT claims to backend parameters.
- claimName: aud           # The claim name, which can be public or private.
  parameterName: X-Aud     # The name of the mapped parameter.
  location: header         # The location of the mapped parameter. Valid values: query, header, path, and formData.
- claimName: userId        # The claim name, which can be public or private.
  parameterName: userId    # The name of the mapped parameter.
  location: query          # The location of the mapped parameter. Valid values: query, header, path, and formData.
blockClaimParameterName: userId  # The claim parameter whose value is checked against the blocklist.
blockByDataSet: 87b65008e92541938537b1a4a236eda5  # The ID of the plug-in dataset that contains the blocklist.
blockStatusCode: 403       # The status code of the response returned for a rejected request.
blockResponseHeaders:      # The headers of the response returned for a rejected request.
  Content-Type: application/xml
blockResponseBody:         # The body of the response returned for a rejected request.
  <Reason>be blocked</Reason>
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz         # When configuring multiple JWKs, use a different kid for each.
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....

5. Summary

Plug-in datasets shift plug-in configuration from a text-based model to a structured data model. This enables partial hot updates and raises the data volume limit by an order of magnitude. For large-scale use cases, API Gateway supports plug-in datasets with millions of entries, unlocking new ways to use plug-ins.

API Gateway currently supports plug-in datasets only for the JWT authentication plug-in. Support will be extended to other plug-ins, including IP address-based access control, parameter-based access control, and backend routing.

Previous：Use parameters and conditional expressionsNext：Attach a plug-in to an API group